godot_core/meta/
param_tuple.rs

1/*
2 * Copyright (c) godot-rust; Bromeon and contributors.
3 * This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
6 */
7
8use godot_ffi as sys;
9
10use crate::builtin::Variant;
11use crate::meta::CallContext;
12use crate::meta::error::CallResult;
13use crate::registry::info::PropertyInfo;
14
15mod impls;
16
17/// Represents a parameter list as Rust tuple where each tuple element is one parameter.
18///
19/// This trait only contains metadata for the parameter list, the actual functionality is contained in [`InParamTuple`] and
20/// [`OutParamTuple`].
21pub trait ParamTuple: Sized {
22    /// The number of elements in this parameter list.
23    const LEN: usize;
24
25    /// The param info of the parameter at index `index`.
26    #[doc(hidden)]
27    fn param_info(
28        index: usize,
29        param_name: &str,
30    ) -> Option<crate::registry::method::MethodParamOrReturnInfo>;
31
32    /// The property info of the parameter at index `index`.
33    fn property_info(index: usize, param_name: &str) -> Option<PropertyInfo> {
34        Self::param_info(index, param_name).map(|param| param.info)
35    }
36
37    /// Return a string representing the arguments.
38    fn format_args(&self) -> String;
39}
40
41/// Represents a parameter list that is received from some external location (usually Godot).
42///
43/// As an example, this would be used for user-defined functions that will be called from Godot, however this is _not_ used when
44/// calling a Godot function from Rust code.
45pub trait InParamTuple: ParamTuple {
46    /// Converts `args_ptr` to `Self`, merging with default values if needed.
47    ///
48    /// # Safety
49    ///
50    /// - `args_ptr` must be a pointer to an array of length `arg_count`
51    /// - Each element of `args_ptr` must be reborrowable as a `&Variant` with a lifetime that lasts for the duration of the call.
52    /// - `arg_count + default_values.len()` must equal `Self::LEN`
53    #[doc(hidden)]
54    unsafe fn from_varcall_args(
55        args_ptr: *const sys::GDExtensionConstVariantPtr,
56        arg_count: usize,
57        default_values: &[Variant],
58        call_ctx: &CallContext,
59    ) -> CallResult<Self>;
60
61    /// Converts `args_ptr` to `Self` directly.
62    ///
63    /// # Safety
64    ///
65    /// - `args_ptr` must be a pointer to a valid array of length [`Self::LEN`](ParamTuple::LEN)
66    /// - each element of `args_ptr` must be of the same type as each element of `Self`
67    #[doc(hidden)] // Hidden since v0.3.2.
68    unsafe fn from_ptrcall_args(
69        args_ptr: *const sys::GDExtensionConstTypePtr,
70        call_type: sys::PtrcallType,
71        call_ctx: &CallContext,
72    ) -> CallResult<Self>;
73
74    /// Converts `array` to `Self` by calling [`from_variant`](crate::meta::FromGodot::from_variant) on each argument.
75    fn from_variant_array(array: &[&Variant]) -> Self;
76}
77
78/// Represents a parameter list that is used to call some external code.
79///
80/// As an example, this would be used to call Godot functions through FFI, however this is _not_ used when Godot calls a user-defined
81/// function.
82pub trait OutParamTuple: ParamTuple {
83    /// Call `f` on the tuple `self` by first converting `self` to an array of [`Variant`]s.
84    fn with_variants<F, R>(self, f: F) -> R
85    where
86        F: FnOnce(&[Variant]) -> R;
87
88    /// Call `f` on the tuple `self` by first converting `self` to an array of [`Variant`] pointers.
89    #[doc(hidden)] // Hidden since v0.3.2.
90    fn with_variant_pointers<F, R>(self, f: F) -> R
91    where
92        F: FnOnce(&[sys::GDExtensionConstVariantPtr]) -> R;
93
94    /// Call `f` on the tuple `self` by first converting `self` to an array of Godot type pointers.
95    #[doc(hidden)] // Hidden since v0.3.2.
96    fn with_type_pointers<F, R>(self, f: F) -> R
97    where
98        F: FnOnce(&[sys::GDExtensionConstTypePtr]) -> R;
99
100    /// Converts `array` to `Self` by calling [`to_variant`](crate::meta::ToGodot::to_variant) on each argument.
101    fn to_variant_array(&self) -> Vec<Variant>;
102}
103
104/// Helper trait to verify that all tuple elements implement `FromGodot`.
105///
106/// Used internally by [`crate::meta::ensure_func_bounds()`] to ensure each parameter in a `#[func]` method
107/// implements `FromGodot`, not just `EngineFromGodot`.
108#[doc(hidden)]
109pub trait TupleFromGodot: Sized {}
godot_core/meta/param_tuple.rs

godot_core/meta/
param_tuple.rs
