A function that creates an object and returns it to the script engine might look like this:
// Registered as "obj@ CreateObject()" obj *CreateObject() { // The constructor already initializes the ref count to 1 return new obj(); }
A function that receives an object handle from the script and stores it in a global variable might look like this:
// Registered as "void StoreObject(obj@)" obj *o = 0; void StoreObject(obj *newO) { // Release the old object handle if( o ) o->Release(); // Store the new object handle o = newO; }
A function that retrieves a previously stored object handle might look like this:
// Registered as "obj@ RetrieveObject()" obj *RetrieveObject() { // Increase the reference counter to account for the returned handle if( o ) o->AddRef(); // It is ok to return null if there is no previous handle stored return o; }
A function that receives an object handle in the parameter, but doesn't store it looks like this:
// Registered as "void DoSomething(obj@)" void DoSomething(obj *o) { // When finished with the object it must be released if( o ) o->Release(); }
// Registered as "obj@+ ChooseObj(obj@+, obj@+)" obj *ChooseObj(obj *a, obj *b) { // Because of the auto handles AngelScript will // automatically manage the reference counters return some_condition ? a : b; }
However, it is not recommended to use this feature unless you can't change the functions you want to register to properly handle the reference counters. When using the auto handles, AngelScript needs to process all of the handles which causes an extra overhead when calling application registered functions.
The auto handles does not affect the behaviour of the handles when the generic calling convention is used.