godot-core 0.5.1

Internal crate used by godot-rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

/*
 * Copyright (c) godot-rust; Bromeon and contributors.
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */

//! Meta-information about Godot types, their properties and conversions between them.
//!
//! # Conversions between types
//!
//! ## Godot representation
//!
//! The library provides two traits [`FromGodot`] and [`ToGodot`], which are used at the Rust <-> Godot boundary, both in user-defined functions
//! ([`#[func]`](../register/attr.godot_api.html#user-defined-functions)) and engine APIs ([`godot::classes` module](crate::classes)).
//! Their `to_godot()` and `from_godot()` methods convert types from/to their _closest possible Godot type_ (e.g. `GString` instead of Rust
//! `String`). You usually don't need to call these methods yourself, they are automatically invoked when passing objects to/from Godot.
//!
//! Most often, the two traits appear in pairs, however there are cases where only one of the two is implemented. For example, `&str` implements
//! `ToGodot` but not `FromGodot`. Additionally, [`GodotConvert`] acts as a supertrait of both [`FromGodot`] and [`ToGodot`]. Its sole purpose
//! is to define the "closest possible Godot type" [`GodotConvert::Via`].
//!
//! For fallible conversions, you can use [`FromGodot::try_from_godot()`].
//!
//! ## Variants
//!
//! [`ToGodot`] and [`FromGodot`] also implement a conversion to/from [`Variant`][crate::builtin::Variant], which is the most versatile Godot
//! type. This conversion is available via `to_variant()` and `from_variant()` methods. These methods are also available directly on `Variant`
//! itself, via `to()`, `try_to()` and `from()` functions.
//!
//! ## Class conversions
//!
//! Godot classes exist in a hierarchy. In OOP, it is usually possible to represent pointers to derived objects as pointer to their bases.
//! For conversions between base and derived class objects, you can use `Gd` methods [`cast()`][crate::obj::Gd::cast],
//! [`try_cast()`][crate::obj::Gd::try_cast] and [`upcast()`][crate::obj::Gd::upcast]. Upcasts are infallible.
//!
//! ## Argument conversions
//!
//! Rust does not support implicit conversions, however it has something very close: the `impl Into<T>` idiom, which can be used to convert
//! "T-compatible" arguments into `T`.
//!
//! This library specializes this idea with the trait [`AsArg<T>`]. `AsArg` allows argument conversions from arguments into `T`.
//! This is most interesting in the context of strings (so you can pass `&str` to a function expecting `GString`) and objects (pass
//! `&Gd<Node2D>` to a function expecting `Node2D` objects).

mod args;
mod class_id;
mod godot_convert;
mod object_to_owned;
mod param_tuple;
mod raw_ptr;
mod signature;
mod traits;
mod uniform_object_deref;

pub(crate) mod sealed;

/// Re-exports for proc-macros and generated code. Not part of the public API.
#[doc(hidden)]
pub mod private_reexport {
    pub use super::param_tuple::TupleFromGodot;
    pub use super::signature::{CallContext, Signature, ensure_func_bounds};
}

pub mod conv;
pub mod error;
pub mod inspect;
pub mod shape;
pub(crate) mod signed_range;

// Public re-exports
pub use args::*;
pub use class_id::ClassId;
pub use godot_convert::{EngineFromGodot, EngineToGodot, FromGodot, GodotConvert, ToGodot};
pub use object_to_owned::ObjectToOwned;
pub use param_tuple::{InParamTuple, OutParamTuple, ParamTuple};
pub use raw_ptr::{FfiRawPointer, RawPtr};
#[cfg(feature = "trace")] #[cfg_attr(published_docs, doc(cfg(feature = "trace")))]
pub use signature::trace;
pub use signed_range::{SignedRange, wrapped};
pub use traits::{Element, GodotImmutable, GodotType, PackedElement, element_variant_type};
pub use uniform_object_deref::UniformObjectDeref;

// Macro re-exports (used as `meta::arg_into_owned!` etc.).
#[doc(hidden)]
pub use crate::arg_into_owned;
#[doc(hidden)]
pub use crate::arg_into_ref;

// Crate-local re-exports. Done like this to prevent rustfmt from mixing with public export.
mod reexport_crate {
    pub(crate) use super::param_tuple::TupleFromGodot;
    pub(crate) use super::signature::{CallContext, Signature, varcall_return_checked};
    pub(crate) use super::traits::{
        ExtVariantType, GodotFfiVariant, GodotNullableType, ffi_variant_type,
    };
    pub(crate) use crate::impl_godot_as_self;
    // Private imports for this module only.
    pub(super) use crate::registry::method::MethodParamOrReturnInfo;
}
pub(crate) use reexport_crate::*;

// ----------------------------------------------------------------------------------------------------------------------------------------------

/// Clean up various resources at end of usage.
///
/// # Safety
/// Must not use meta facilities (e.g. `ClassId`) after this call.
pub(crate) unsafe fn cleanup() {
    unsafe {
        class_id::cleanup();
    }
}