Merge pull request #1308 from godot-rust/feature/as-object-arg-unify

Merge `AsObjectArg<T>` into `AsArg<Gd<T>>`

Author: Bromeon

godot-codegen/src/conv/type_conversions.rs

@@ -237,8 +237,7 @@ fn to_rust_type_uncached(full_ty: &GodotTy, ctx: &mut Context) -> RustTy {
 
         RustTy::EngineClass {
             tokens: quote! { Gd<#qualified_class> },
-            object_arg: quote! { ObjectArg<#qualified_class> },
-            impl_as_object_arg: quote! { impl AsObjectArg<#qualified_class> },
+            impl_as_object_arg: quote! { impl AsArg<Option<Gd<#qualified_class>>> },
             inner_class: ty,
         }
     }

godot-codegen/src/generator/functions_common.rs

@@ -392,7 +392,7 @@ pub(crate) enum FnArgExpr {
 /// How parameters are declared in a function signature.
 #[derive(Copy, Clone)]
 pub(crate) enum FnParamDecl {
-    /// Public-facing, i.e. `T`, `&T`, `impl AsArg<T>` or `impl AsObjectArg<T>`.
+    /// Public-facing, i.e. `T`, `&T`, `impl AsArg<T>`.
     FnPublic,
 
     /// Public-facing with explicit lifetime, e.g. `&'a T`. Used in `Ex` builder methods.
@@ -401,7 +401,7 @@ pub(crate) enum FnParamDecl {
     /// Parameters in internal methods, used for delegation.
     FnInternal,
 
-    /// Store in a field, i.e. `v`, `CowArg<T>` or `ObjectCow<T>`.
+    /// Store in a field, i.e. `v` or `CowArg<T>`.
     Field,
 }
 
@@ -446,20 +446,24 @@ pub(crate) fn make_param_or_field_type(
     let mut special_ty = None;
 
     let param_ty = match ty {
-        // Objects: impl AsObjectArg<T>
+        // Objects: impl AsArg<Gd<T>>
         RustTy::EngineClass {
-            object_arg,
             impl_as_object_arg,
             inner_class,
             ..
         } => {
-            special_ty = Some(quote! { #object_arg });
+            let lft = lifetimes.next();
+            special_ty = Some(quote! { CowArg<#lft, Option<Gd<crate::classes::#inner_class>>> });
 
             match decl {
                 FnParamDecl::FnPublic => quote! { #impl_as_object_arg },
-                FnParamDecl::FnPublicLifetime => quote! { #impl_as_object_arg },
-                FnParamDecl::FnInternal => quote! { #object_arg },
-                FnParamDecl::Field => quote! { ObjectCow<crate::classes::#inner_class> },
+                FnParamDecl::FnPublicLifetime => quote! { #impl_as_object_arg + 'a },
+                FnParamDecl::FnInternal => {
+                    quote! { CowArg<Option<Gd<crate::classes::#inner_class>>> }
+                }
+                FnParamDecl::Field => {
+                    quote! { CowArg<'a, Option<Gd<crate::classes::#inner_class>>> }
+                }
             }
         }
 
@@ -513,11 +517,11 @@ pub(crate) fn make_arg_expr(name: &Ident, ty: &RustTy, expr: FnArgExpr) -> Token
     match ty {
         // Objects.
         RustTy::EngineClass { .. } => match expr {
-            FnArgExpr::PassToFfi => quote! { #name.as_object_arg() },
-            FnArgExpr::PassToFfiFromEx => quote! { #name.cow_as_object_arg() },
+            FnArgExpr::PassToFfi => quote! { #name.into_arg() },
+            FnArgExpr::PassToFfiFromEx => quote! { #name },
             FnArgExpr::Forward => quote! { #name },
-            FnArgExpr::StoreInField => quote! { #name.consume_arg() },
-            FnArgExpr::StoreInDefaultField => quote! { #name.consume_arg() },
+            FnArgExpr::StoreInField => quote! { #name.into_arg() },
+            FnArgExpr::StoreInDefaultField => quote! { #name.into_arg() },
         },
 
         // Strings.

godot-codegen/src/models/domain.rs

@@ -541,7 +541,7 @@ impl FnParam {
         }
     }
 
-    /// `impl AsObjectArg<T>` for object parameters. Only set if requested and `T` is an engine class.
+    /// `impl AsArg<Gd<T>>` for object parameters. Only set if requested and `T` is an engine class.
     pub fn new_no_defaults(method_arg: &JsonMethodArg, ctx: &mut Context) -> FnParam {
         FnParam {
             name: safe_ident(&method_arg.name),
@@ -653,10 +653,7 @@ pub enum RustTy {
         /// Tokens with full `Gd<T>` (e.g. used in return type position).
         tokens: TokenStream,
 
-        /// Tokens with `ObjectArg<T>` (used in `type CallSig` tuple types).
-        object_arg: TokenStream,
-
-        /// Signature declaration with `impl AsObjectArg<T>`.
+        /// Signature declaration with `impl AsArg<Gd<T>>`.
         impl_as_object_arg: TokenStream,
 
         /// only inner `T`

godot-codegen/src/special_cases/special_cases.rs

@@ -638,7 +638,7 @@ pub fn is_class_method_const(class_name: &TyName, godot_method: &JsonClassMethod
 }
 
 /// Currently only for virtual methods; checks if the specified parameter is required (non-null) and can be declared as `Gd<T>`
-/// instead of `Option<Gd<T>>`.
+/// instead of `Option<Gd<T>>`. By default, parameters are optional since we don't have nullability information in GDExtension.
 pub fn is_class_method_param_required(
     class_name: &TyName,
     godot_method_name: &str,

godot-codegen/src/util.rs

@@ -25,7 +25,7 @@ pub fn make_imports() -> TokenStream {
     quote! {
         use godot_ffi as sys;
         use crate::builtin::*;
-        use crate::meta::{AsArg, AsObjectArg, ClassName, CowArg, InParamTuple, ObjectArg, ObjectCow, OutParamTuple, ParamTuple, RefArg, Signature};
+        use crate::meta::{AsArg, ClassName, CowArg, InParamTuple, OutParamTuple, ParamTuple, RefArg, Signature};
         use crate::classes::native::*;
         use crate::classes::Object;
         use crate::obj::Gd;

godot-core/src/meta/args/as_arg.rs

@@ -11,6 +11,7 @@ use crate::builtin::{GString, NodePath, StringName, Variant};
 use crate::meta::sealed::Sealed;
 use crate::meta::traits::GodotFfiVariant;
 use crate::meta::{CowArg, GodotType, ToGodot};
+use crate::obj::{bounds, Bounds, DynGd, Gd, GodotClass, Inherits};
 
 /// Implicit conversions for arguments passed to Godot APIs.
 ///
@@ -22,10 +23,8 @@ use crate::meta::{CowArg, GodotType, ToGodot};
 ///   - These all implement `ToGodot<Pass = ByValue>` and typically also `Copy`.
 /// - `&T` for **by-ref** built-ins: `GString`, `Array`, `Dictionary`, `PackedArray`, `Variant`...
 ///   - These all implement `ToGodot<Pass = ByRef>`.
-/// - `&str`, `&String` additionally for string types `GString`, `StringName`, `NodePath`.
-///
-/// See also the [`AsObjectArg`][crate::meta::AsObjectArg] trait which is specialized for object arguments. It may be merged with `AsArg`
-/// in the future.
+/// - `&str`, `&String` additionally for string types `GString`, `StringName`, `NodePath`, see [String arguments](#string-arguments).
+/// - `&Gd`, `Option<&Gd>` for objects, see [Object arguments](#object-arguments).
 ///
 /// # Owned values vs. references
 /// Implicitly converting from `T` for **by-ref** built-ins is explicitly not supported, i.e. you need to pass `&variant` instead of `variant`.
@@ -35,7 +34,14 @@ use crate::meta::{CowArg, GodotType, ToGodot};
 /// Sometimes, you need exactly that for generic programming though: consistently pass `T` or `&T`. For this purpose, the global functions
 /// [`owned_into_arg()`] and [`ref_to_arg()`] are provided.
 ///
-/// # Performance for strings
+/// # Using the trait
+/// `AsArg` is meant to be used from the function call site, not the declaration site. If you declare a parameter as `impl AsArg<...>` yourself,
+/// you can only forward it as-is to a Godot API -- there are no stable APIs to access the inner object yet.
+///
+/// The blanket implementations of `AsArg` for `T` (in case of `Pass = ByValue`) and `&T` (`Pass = ByRef`) should readily enable most use
+/// cases, as long as your type already supports `ToGodot`. In the majority of cases, you'll simply use by-value passing, e.g. for enums.
+///
+/// # String arguments
 /// Godot has three string types: [`GString`], [`StringName`] and [`NodePath`]. Conversions between those three, as well as between `String` and
 /// them, is generally expensive because of allocations, re-encoding, validations, hashing, etc. While this doesn't matter for a few strings
 /// passed to engine APIs, it can become a problematic when passing long strings in a hot loop.
@@ -48,12 +54,29 @@ use crate::meta::{CowArg, GodotType, ToGodot};
 /// If you want to convert between Godot's string types for the sake of argument passing, each type provides an `arg()` method, such as
 /// [`GString::arg()`]. You cannot use this method in other contexts.
 ///
-/// # Using the trait
-/// `AsArg` is meant to be used from the function call site, not the declaration site. If you declare a parameter as `impl AsArg<...>` yourself,
-/// you can only forward it as-is to a Godot API -- there are no stable APIs to access the inner object yet.
+/// # Object arguments
+/// This section treats `AsArg<Gd<*>>`. The trait is implemented for **shared references** in multiple ways:
+/// - [`&Gd<T>`][crate::obj::Gd]  to pass objects. Subclasses of `T` are explicitly supported.
+/// - [`Option<&Gd<T>>`][Option], to pass optional objects. `None` is mapped to a null argument.
+/// - [`Gd::null_arg()`], to pass `null` arguments without using `Option`.
 ///
-/// The blanket implementations of `AsArg` for `T` (in case of `Pass = ByValue`) and `&T` (`Pass = ByRef`) should readily enable most use
-/// cases, as long as your type already supports `ToGodot`. In the majority of cases, you'll simply use by-value passing, e.g. for enums.
+/// The following table lists the possible argument types and how you can pass them. `Gd` is short for `Gd<T>`.
+///
+/// | Type              | Closest accepted type | How to transform |
+/// |-------------------|-----------------------|------------------|
+/// | `Gd`              | `&Gd`                 | `&arg`           |
+/// | `&Gd`             | `&Gd`                 | `arg`            |
+/// | `&mut Gd`         | `&Gd`                 | `&*arg`          |
+/// | `Option<Gd>`      | `Option<&Gd>`         | `arg.as_ref()`   |
+/// | `Option<&Gd>`     | `Option<&Gd>`         | `arg`            |
+/// | `Option<&mut Gd>` | `Option<&Gd>`         | `arg.as_deref()` |
+/// | (null literal)    |                       | `Gd::null_arg()` |
+///
+/// ## Nullability
+/// <div class="warning">
+/// The GDExtension API does not inform about nullability of its function parameters. It is up to you to verify that the arguments you pass
+/// are only null when this is allowed. Doing this wrong should be safe, but can lead to the function call failing.
+/// </div>
 #[diagnostic::on_unimplemented(
     message = "Argument of type `{Self}` cannot be passed to an `impl AsArg<{T}>` parameter",
     note = "if you pass by value, consider borrowing instead.",
@@ -97,6 +120,106 @@ where
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Object (Gd + DynGd) impls
+
+// TODO(v0.4): all objects + optional objects should be pass-by-ref.
+
+impl<T, Base> AsArg<Gd<Base>> for &Gd<T>
+where
+    T: Inherits<Base>,
+    Base: GodotClass,
+{
+    fn into_arg<'r>(self) -> CowArg<'r, Gd<Base>>
+    where
+        Self: 'r,
+    {
+        CowArg::Owned(self.clone().upcast::<Base>())
+    }
+}
+
+impl<T, U, D> AsArg<DynGd<T, D>> for &DynGd<U, D>
+where
+    T: GodotClass,
+    U: Inherits<T>,
+    D: ?Sized,
+{
+    fn into_arg<'r>(self) -> CowArg<'r, DynGd<T, D>>
+    where
+        Self: 'r,
+    {
+        CowArg::Owned(self.clone().upcast::<T>())
+    }
+}
+
+// Convert DynGd -> Gd (with upcast).
+impl<'r, T, U, D> AsArg<Gd<T>> for &'r DynGd<U, D>
+where
+    T: GodotClass,
+    U: Inherits<T>,
+    D: ?Sized,
+{
+    fn into_arg<'cow>(self) -> CowArg<'cow, Gd<T>>
+    where
+        'r: 'cow,
+    {
+        CowArg::Owned(self.clone().upcast::<T>().into_gd())
+    }
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Optional object (Gd + DynGd) impls
+
+impl<T, U> AsArg<Option<Gd<T>>> for &Option<Gd<U>>
+where
+    T: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
+    U: Inherits<T>,
+{
+    fn into_arg<'r>(self) -> CowArg<'r, Option<Gd<T>>> {
+        match self {
+            Some(gd) => CowArg::Owned(Some(gd.clone().upcast::<T>())),
+            None => CowArg::Owned(None),
+        }
+    }
+}
+
+impl<T, U> AsArg<Option<Gd<T>>> for Option<&Gd<U>>
+where
+    T: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
+    U: Inherits<T>,
+{
+    fn into_arg<'cow>(self) -> CowArg<'cow, Option<Gd<T>>> {
+        // This needs to construct a new Option<Gd<T>>, so cloning is unavoidable
+        // since we go from Option<&Gd<U>> to Option<Gd<T>>
+        match self {
+            Some(gd) => CowArg::Owned(Some(gd.clone().upcast::<T>())),
+            None => CowArg::Owned(None),
+        }
+    }
+}
+
+impl<T, U> AsArg<Option<Gd<T>>> for &Gd<U>
+where
+    T: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
+    U: Inherits<T>,
+{
+    fn into_arg<'cow>(self) -> CowArg<'cow, Option<Gd<T>>> {
+        CowArg::Owned(Some(self.clone().upcast::<T>()))
+    }
+}
+
+impl<T, U, D> AsArg<Option<Gd<T>>> for &DynGd<U, D>
+where
+    T: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
+    U: Inherits<T>,
+    D: ?Sized,
+{
+    fn into_arg<'cow>(self) -> CowArg<'cow, Option<Gd<T>>> {
+        let gd: &Gd<U> = self; // Deref
+        CowArg::Owned(Some(gd.clone().upcast::<T>()))
+    }
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Public helper functions (T|&T -> AsArg)
 

godot-core/src/meta/args/mod.rs

@@ -23,9 +23,8 @@ pub use as_arg::{owned_into_arg, ref_to_arg, ArgPassing, AsArg, ByRef, ByValue,
 pub use cow_arg::CowArg;
 #[cfg(not(feature = "trace"))]
 pub(crate) use cow_arg::CowArg;
-pub use object_arg::AsObjectArg;
-#[allow(unused_imports)] // ObjectCow is used in generated code.
-pub(crate) use object_arg::{ObjectArg, ObjectCow, ObjectNullArg};
+#[allow(unused)] // TODO(v0.4): replace contents with newer changes
+pub use object_arg::ObjectArg;
 pub use ref_arg::RefArg;
 
 // #[doc(hidden)]