Merge #636

636: Add wrapper for try_from_instance_id r=toasteater a=toasteater

Close #464

Co-authored-by: toasteater <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **The minimum compatible engine version is now 3.2-stable.**
+
 ## [0.9.1] - 2020-10-19
 
 ### Added

README.md

@@ -17,7 +17,7 @@ The bindings cover most of the exposed API of Godot 3.2, and are being used on a
 
 We are serious about engine compatibility. We are committed to keeping compatibility with the latest stable patch releases of all minor versions of the engine, starting from Godot 3.2.
 
-The current minimum compatible version, with `api.json` replacement, is Godot 3.1.1-stable. Changes to this will be considered a breaking change, and will be called out in the release notes.
+The current minimum compatible version, with `api.json` replacement, is Godot 3.2-stable. Changes to this will be considered a breaking change, and will be called out in the release notes.
 
 The bindings do *not* support Godot 4.0 (`master` branch) currently.
 

gdnative-core/src/object.rs

@@ -151,6 +151,36 @@ pub unsafe trait GodotObject: Sized + crate::private::godot_object::Sealed {
     {
         Ref::from_sys(self.as_raw().sys())
     }
+
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive. See also `TRef::try_from_instance_id`.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    unsafe fn try_from_instance_id<'a>(id: i64) -> Option<TRef<'a, Self, Shared>> {
+        TRef::try_from_instance_id(id)
+    }
+
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive, and panics otherwise. This does **NOT** guarantee that the resulting
+    /// reference is safe to use.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the given id refers to a destroyed object. For a non-panicking version, see
+    /// `try_from_instance_id`.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    unsafe fn from_instance_id<'a>(id: i64) -> TRef<'a, Self, Shared> {
+        TRef::from_instance_id(id)
+    }
 }
 
 /// Marker trait for API types that are subclasses of another type. This trait is implemented
@@ -892,6 +922,41 @@ where
     }
 }
 
+impl<'a, T: GodotObject> TRef<'a, T, Shared> {
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    pub unsafe fn try_from_instance_id(id: i64) -> Option<Self> {
+        let api = get_api();
+        let ptr = NonNull::new((api.godot_instance_from_id)(id as sys::godot_int))?;
+        let raw = RawObject::try_from_sys_ref(ptr)?;
+        Some(TRef::new(T::cast_ref(raw)))
+    }
+
+    /// Recovers a instance ID previously returned by `Object::get_instance_id` if the object is
+    /// still alive, and panics otherwise. This does **NOT** guarantee that the resulting
+    /// reference is safe to use.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the given id refers to a destroyed object. For a non-panicking version, see
+    /// `try_from_instance_id`.
+    ///
+    /// # Safety
+    ///
+    /// During the entirety of `'a`, the thread from which `try_from_instance_id` is called must
+    /// have exclusive access to the underlying object, if it is still alive.
+    #[inline]
+    pub unsafe fn from_instance_id(id: i64) -> Self {
+        Self::try_from_instance_id(id).expect("instance should be alive")
+    }
+}
+
 /// Trait for safe conversion from Godot object references into API method arguments. This is
 /// a sealed trait with no public interface.
 ///

gdnative-sys/godot_headers/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2017-2020 GodotNativeTools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gdnative-sys/godot_headers/README.md

@@ -0,0 +1,247 @@
+# godot_headers
+#### `GDNative / NativeScript`
+
+> `GDNative` enables the use of dynamically linked libraries inside of [**Godot**](https://github.com/godotengine/godot).
+
+> `NativeScript` uses GDNative to implement scripts backed by native code.
+
+-   [**Branches**](#branches)
+-   [**Getting Started**](#getting-started)
+-   [**FAQ**](#faq)
+
+## Branches
+
+We maintain branches on this repo that relate directly to the main builds of Godot.
+Make sure you use the correct branch for the version of Godot you are using!
+
+| Branch | Version of Godot |
+| --- | --- |
+| [master](https://github.com/GodotNativeTools/godot_headers) | Godot master  |
+| [3.2](https://github.com/GodotNativeTools/godot_headers/tree/3.2) | Godot 3.2.x  |
+| [3.1](https://github.com/GodotNativeTools/godot_headers/tree/3.1) | Godot 3.1.x  |
+| [3.0](https://github.com/GodotNativeTools/godot_headers/tree/3.0) | Godot 3.0.x  |
+
+## Getting Started
+
+| **Build latest version of Godot** | [**GitHub**](https://github.com/godotengine/godot) | [**Docs**](https://godot.readthedocs.io/en/latest/development/compiling/index.html) |
+| --- | --- | --- |
+
+### Clone godot_headers into Library
+
+Clone `godot_headers` under `SimpleLibrary/`
+
+```bash
+cd SimpleLibrary
+git clone https://github.com/GodotNativeTools/godot_headers
+```
+
+> Note that the master branch of this repository contains the header for the latest Godot master. If you want to build GDNative modules for older versions of Godot add `-b <version>` to the git clone command above. i.e. `git clone https://github.com/GodotNativeTools/godot_headers -b 3.0` will retrieve headers compatible with Godot 3.0.
+
+> With the exception of a breaking change in the ARVR module between 3.0 and 3.1, GDNative plugins written for an older version of Godot will work in newer versions.
+
+```bash
+[SimpleLibrary]
+  ├── lib/
+  └── src/
+```
+
+### Create Script
+
+Create `test.c` under `SimpleLibrary/src/`
+
+<details>
+
+```c
+#include <gdnative/gdnative.h>
+#include <nativescript/godot_nativescript.h>
+
+#include <stdio.h>
+
+void *test_constructor(godot_object *obj, void *method_data) {
+        printf("test.constructor()\n");
+        return 0;
+}
+
+void test_destructor(godot_object *obj, void *method_data, void *user_data) {
+        printf("test.destructor()\n");
+}
+
+/** func _ready() **/
+godot_variant test_ready(godot_object *obj, void *method_data, void *user_data, int num_args, godot_variant **args) {
+        godot_variant ret;
+        godot_variant_new_nil(&ret);
+
+        printf("_ready()\n");
+
+        return ret;
+}
+
+/** Library entry point **/
+void GDN_EXPORT godot_gdnative_init(godot_gdnative_init_options *o) {
+}
+
+/** Library de-initialization **/
+void GDN_EXPORT godot_gdnative_terminate(godot_gdnative_terminate_options *o) {
+}
+
+/** Script entry (Registering all the classes and stuff) **/
+void GDN_EXPORT godot_nativescript_init(void *desc) {
+	printf("nativescript init\n");
+
+	godot_instance_create_func create_func = {
+		.create_func = &test_constructor,
+                .method_data = 0,
+                .free_func   = 0
+        };
+
+        godot_instance_destroy_func destroy_func = {
+                .destroy_func = &test_destructor,
+                .method_data  = 0,
+                .free_func    = 0
+        };
+
+        godot_nativescript_register_class(desc, "SimpleClass", "Node", create_func, destroy_func);
+
+        {
+                godot_instance_method method = {
+                        .method = &test_ready,
+                        .method_data = 0,
+                        .free_func = 0
+                };
+
+                godot_method_attributes attr = {
+                        .rpc_type = GODOT_METHOD_RPC_MODE_DISABLED
+                };
+
+                godot_nativescript_register_method(desc, "SimpleClass", "_ready", attr, method);
+        }
+}
+
+godot_variant GDN_EXPORT some_test_procedure(void *data, godot_array *args) {
+        godot_variant ret;
+        godot_variant_new_int(&ret, 42);
+
+        godot_string s;
+        godot_string_new_unicode_data(&s, L"Hello World", 11);
+        godot_print(&s);
+
+        godot_string_destroy(&s);
+
+        return ret;
+}
+```
+
+</details>
+
+`Expand details for example code.`
+
+### Compile Library
+
+On Linux:
+
+```bash
+clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os
+clang -g -shared src/test.os -o lib/test.so
+```
+
+On MacOS:
+
+```bash
+clang -g -fPIC -std=c99 -c src/test.c -I/path/to/godot/headers/ -o src/test.os
+clang -g -shared -framework Cocoa -Wl,-undefined,dynamic_lookup src/test.os -o lib/test.dylib
+```
+
+- `-g` is for debugging information.
+- Use `godot_nativescript_*` methods only in the `nativescript_init()` function.
+
+### Create GDNativeLibrary Resource
+The GDNativeLibrary resource contains links to the libraries for each platform.
+
+1. Create a new resource in memory and edit it.
+1. Select `Resource > GDNativeLibrary`.
+1. Set the library file for your platform inside the inspector.
+1. Save the edited resource as a `.tres`
+
+<details>
+
+![](images/faq/dllibrary_create_new_resource.png?raw=true)
+
+![](images/faq/dllibrary_create_new_dllibrary.png?raw=true)
+
+![](images/faq/dllibrary_save_as_resource.png?raw=true)
+
+*Note*: Remember to save `GDNativeLibrary` as `.gdnlib`
+
+</details>
+
+`Expand details for screenshots.`
+
+### Using GDNativeLibrary in GDScript
+
+```gdscript
+extends Node
+
+func _ready():
+        var gdn = GDNative.new()
+        gdn.library = load("res://lib/libtest.tres")
+
+        gdn.initialize()
+
+        var res = gdn.call_native("standard_varcall", "some_test_procedure", [])
+
+        print("result: ", res)
+
+        gdn.terminate()
+```
+
+### Attaching GDNativeLibrary to a Node
+
+1. Attach a new script to a node.
+1. In the pop-up dialog, choose NativeScript in the `Language` menu.
+1. Enable built-in script, or create a `.gdn` file, which only contains a name.
+1. Specify the `Class Name`.
+1. Press `Create`.
+
+The GDNativeLibrary field in a NativeScript is empty by default.
+
+
+<details>
+
+![](images/faq/create_dlscript.png?raw=true)
+
+![](images/faq/set_script_dllibrary.png?raw=true)
+
+</details>
+
+`Expand details for screenshots.`
+
+## FAQ
+
+**What is the difference between `GDNative` and `NativeScript`?**
+
+`GDNative` is a new class that can call native functions in libraries.
+GDScript / VisualScript / C#, etc, are able to use this class.
+
+Godot treats `NativeScript` as a scripting language, enabling the
+use of GDNative to implement scripts backed by native code.
+
+**Which languages are binding as a NativeScript?**
+
+[**C++**](https://github.com/GodotNativeTools/cpp_bindings),
+[**D**](https://github.com/GodotNativeTools/d_bindings),
+[**Nim**](https://github.com/pragmagic/godot-nim)
+
+**Can you debug NativeScripts?**
+
+You must compile the library with debug
+symbols, and then you can use your debugger as usual.
+
+**Can you use one GDNativeLibrary for all NativeScripts?**
+
+You can! ✨
+
+**What is the reason behind the name "GDNative"?**
+
+GDNative was originally named "cscript" because it exposes a C API, but people
+mistook a relation to C#, which is sometimes abbreviated as "cs". Then named "DLScript", but that brought up some confusion, so we settled with
+GDNative. 📖

gdnative-sys/godot_headers/android/godot_android.h

@@ -5,8 +5,8 @@
 /*                           GODOT ENGINE                                */
 /*                      https://godotengine.org                          */
 /*************************************************************************/
-/* Copyright (c) 2007-2019 Juan Linietsky, Ariel Manzur.                 */
-/* Copyright (c) 2014-2019 Godot Engine contributors (cf. AUTHORS.md)    */
+/* Copyright (c) 2007-2020 Juan Linietsky, Ariel Manzur.                 */
+/* Copyright (c) 2014-2020 Godot Engine contributors (cf. AUTHORS.md).   */
 /*                                                                       */
 /* Permission is hereby granted, free of charge, to any person obtaining */
 /* a copy of this software and associated documentation files (the       */
@@ -46,6 +46,8 @@ extern "C" {
 
 JNIEnv *GDAPI godot_android_get_env();
 jobject GDAPI godot_android_get_activity();
+jobject GDAPI godot_android_get_surface();
+bool GDAPI godot_android_is_activity_resumed();
 
 #ifdef __cplusplus
 }