OffscreenGecko object basics

The OffscreenGecko API is centered around objects.

Whatever you do with it, an object is involved: Initializing the library is equivalent to creating an object. A "browser" to display is an object. And so on.

All objects are reference counted for lifetime management. That means if a reference/pointer to an object is stored anywhere for a somewhat longer time, a reference must be "added". Likewise, is the referenced/pointed to object is not needed any more, the reference must be "released". That way the object is cleaned up automatically when it's not used at all any more. One important point here is that reference adding and releasing must be balanced, ie each reference added must be released at some point.

There is one exception where a reference must not be added: when storing an object returned from a "create" funtion. Object creation implicitly adds a reference and the creation function "gives" that reference back to the caller. Thus adding a reference would actually cause an excess reference, released by noone, meaning that the object can't be properly cleaned up.

(These are just very very terse descriptions of "object orientedness" and "reference counting". If these concepts are new to you, it's *strongly* recommended you get some literature on the subjects.)

Dealing with OffscreenGecko objects (C)

In the C interface objects are represented by opaque pointers. To add a reference, use the osgk_addref() function. To release a references, use the osgk_release() function.

Dealing with OffscreenGecko objects (C++)

The OffscreenGecko C++ interface wraps all OffscreenGecko objects into C++ classes; so instead of calling a function and passing in the opaque object pointer you can directly call a method on the object. Furthermore, reference counting is handled automatically when an object is created, destroyed, copied etc.

However, to use these classes efficiently, an implementation detail must be noted: the C++ classes merely wrap the opaque pointers from the C interface. This has several implications:

• A copy is not a true copy - the "copy" is merely an additional reference to the same object as the original.
• Creating objects on the heap is somewhat wasteful, it will just allocate the storage for the pointer and add another layer of indirection. In that sense, the wrapper classes have a behaviour that more resembles Java references to classes than "true" C++ inlined classes.

In C++, an instance of the wrapped object type is created immediately when the wrapper class is constructed. Delayed creation is still possible, though: for that, the wrapper must be initialized with a null reference. Later, a new instance of the wrapper type for the desired object can be assigned. For example code see Example: Delayed creation of an OffscreenGecko object in C++.

---