Class TReferenceCounted

Unit

Irrlicht

Declaration

type TReferenceCounted = class(TWrapper)

Description

Base class of most objects of the Irrlicht Engine.
This class provides reference counting through the methods Grab and Drop. It also is able to store a debug string for every instance of an object. Most objects of the Irrlicht Engine are derived from TReferenceCounted, and so they are reference counted.
When you create an object in the Irrlicht engine, calling a method which starts with 'Create', an object is created, and you get a pointer to the new object. If you no longer need the object, you have to call Drop. This will destroy the object, if Grab was not called in another part of you program, because this part still needs the object. Note, that you only need to call Drop to the object if you created it, and the returning method had a 'Create' in it.

A simple example:
If you want to create a texture, you may want to call an imaginable method TVideoDriver.CreateTexture. You call

    var Texture: TTexture;
    ...
    Texture = VideoDriver.CreateTexture(Size(128, 128));
        

If you no longer need the texture, call

    Texture.Drop;
        

If you want to load a texture, you may want to call imaginable method TVideoDriver.LoadTexture. You will not have to drop the pointer to the loaded texture, because the name of the method does not start with 'Create'. The texture is stored somewhere by the driver.

As every wrapped irr::IReferenceCounted pointer requires a TRefereceCounted wrapper object, additional care has to be taken of this wrapper object.
When the internal reference count of a TReferenceCounted instance reaches zero, Free is called. The internal reference count works just like the IReferenceCounted one; it's increased by 1 everytime you Grab, and decreased by 1 everytime you Drop it. "Create"d objects start with an internal ref count of 1, non-"create"d with 0.
If you call Free manually, all remaining internal references will be dropped. E.g. if you call Free on a wrapper object with ref count 2, Drop will be called twice.

Hierarchy

• TInterfacedObject
• TWrapper
• TReferenceCounted

Overview

Methods

	constructor Create(NReference: Pointer; AutoDrop: Boolean = False);
	destructor Destroy; override;
	function Drop: Boolean; inline;
	procedure Grab; inline;

Properties

	property DebugName: AnsiString read GetDebugName;
	property InternalReferenceCount: LongWord read MyRefCount;
	property ReferenceCount: LongWord read GetReferenceCount;

Description

Methods

	constructor Create(NReference: Pointer; AutoDrop: Boolean = False);
Constructor. Only used internally. Parameters NReference The wrapped reference AutoDrop Whether to drop the object automatically on Free.

	destructor Destroy; override;
Destructor. Drops all remaining internal references.

	function Drop: Boolean; inline;
Drops the object. Decrements the reference counter by one. Returns True if the wrapper object was destroyed.

	procedure Grab; inline;

Properties

	property DebugName: AnsiString read GetDebugName;
Sets the debug name of the object. The debug name may only be set and changed by the object itself. This method should only be used in debug mode.

	property InternalReferenceCount: LongWord read MyRefCount;
The internal reference count. Decides when to free the object.

	property ReferenceCount: LongWord read GetReferenceCount;
The actual irr::IReferenceCounted reference count.