Factory

Detailed Description

class Factory : public RED::Object 

Factory class needed by REDsdk clients to create new REDsdk object instances.

The RED::Factory class is used through static API calls to create and delete SDK objects instances. Users mostly manipulate RED::Object instances when working with REDsdk. To get access to instances specific features, one can first ask for an interface using one of the RED::IREDObject::As methods.

Every RED::Object instance can expose none or several interfaces. An interface is a set of methods accessible through an object after casting it using one of the RED::IREDObject::As methods. To do so, you’ll need the Class ID (CID) of the interface you want to retrieve. Then call the RED::IREDObject::As method passing the CID of that interface to get a valid pointer on it (if it exists) or NULL otherwise. Please refer to the documentation index to get the full list of available interfaces in REDsdk.

To create instances using the factory, simply call the corresponding create method:

RED::Object* resmgr = RED::Factory::CreateInstance( CID_REDResourceManager );
RED::Object* mesh = RED::Factory::CreateInstance( CID_REDMeshShape );

and so on…

Whatever the instance you created is, you must explicitly call the deletion method of the factory to destroy it (except in case where deletion is automatically propagated as in DAGs for example):

RED_RC result = RED::Factory::DeleteInstance( object, currentState );

Public Static Functions

static RED::Object *CreateInstance(const RED::CID &iCID)

Creates an instance of a given REDsdk class.

This method creates a new object instance for all types listed below:

CID_REDLightShape: Scene graph light source.
CID_REDLineShape: Scene graph geometric lines.
CID_REDPointShape: Scene graph geometric points clouds.
CID_REDTransformShape: Node of the scene graph.
CID_REDMeshShape: Triangle based geometric object in the scene graph.
CID_REDTextShape: Scene graph text display shape.
CID_REDViewpoint: Cameras used to visualize scene graphs.
CID_REDResourceManager: Base visualization cluster object (singleton).
CID_REDFile: File handler used to load and save .red files.

Singleton objects such as the CID_REDResourceManager object are created on the first call to CreateInstance and then are returned each time the routine is called.

It’s preferable to create the resource manager singleton before any other graphic operation in the application. The resource manager may change the setup of graphic card drivers and this will only work if the resource manager is created before doing any graphics in the application.

Windows are created through the dedicated RED::Factory::CreateREDWindow method of this class. Shareable graphical resources are created directly through the RED::IResourceManager interface of the resource manager.

There are three reasons why a call to this method can fail:

The given CID is not a valid one,
The memory allocation has failed,
If we are not in a valid transaction (see the RED::IResourceManager class).

You can check that a CID is registered by calling the RED::Factory::IsRegistered method.

An example of use is given here: \ref tk_creating_and_destroying_objects_using_the_red_factory.

Parameters: iCID – ID of the class to instanciate.
Returns: A pointer to the instantiated object on success, NULL in case of failure. A failure can occur if a memory error occurs or if we’re not in a valid transaction defined by RED::IResourceManager::BeginState.

static RED::Object *CreateStatelessInstance(const RED::CID &iCID)

Creates a stateless object instance.

Works as RED::Factory::CreateInstance, but using RED::State::GetZeroState as transaction parameter. Note that stateless created objects bypass the REDsdk event handling system and therefore can’t be used as cluster objects: they must remain standalone. To delete a stateless object, call RED::Factory::DeleteInstance using RED::State::GetZeroState for the transaction parameter.

Only shapes can be created using this method.

Parameters: iCID – ID of the class to instanciate.
Returns: A pointer to the instantiated object on success, NULL in case of failure.

static RED_RC DeleteInstance(RED::Object *iInstance, const RED::State &iState)

Deletes an object instance that was previously created using the RED::Factory.

Please refer to \ref bk_ba_life_cycle_of_redsdk_objects for all details on object destruction mechanisms in REDsdk.

An example of use is given here: \ref tk_creating_and_destroying_objects_using_the_red_factory.

Parameters

iInstance – Object address.
iState – The current transaction parameter.

Returns

RED_OK when the method has succeeded,

RED_BAD_PARAM if the method has received an invalid iInstance address,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_SCG_NO_ROOT_DESTRUCTION if iInstance is the root of a scene graph. The destruction of scene graph roots is the responsibility of REDsdk,

RED_SCG_SHAPE_ALREADY_DESTROYED if iInstance is a shape object and if this shape has been already destroyed during the transaction (from a hierarchical destruction of a scene graph tree),

RED_WFLOW_WINDOW_DESTRUCTION_ERROR if a window is being released and it’s system window has been already released,

RED_FAIL otherwise.

static RED::Object *CreateREDWindow(RED::Object &iResourceManager, void *iOSHandler, unsigned int iWidth, unsigned int iHeight, RED::WindowRenderInfo *iInfo, RED_RC &oErrorCode)

Creates a window.

A window must be created before image operations can occur if a GPU has to be used. Similarly, file operations with images require a window to be created first.

Please note that on MacOS / Cocoa environments, the NSView must be shown and ready for the display, otherwise, the internal context creation may return an ‘invalid drawable’ error code while trying to link with the window.

Please refer to the \ref bk_buildingapp for Operating system specific window initialization and creation code.

An example of use can be seen here: \ref tk_creating_a_redsdk_window_using_the_red_factory.

Parameters

iResourceManager – Cluster’s resource manager.
iOSHandler – OS handler. The HWND on Windows, the X-Window id on Linux/UNIX or the NSView address on MacOS / Cocoa.
iDisplay – (Linux/UNIX only) pointer to the X display.
iScreen – (Linux/UNIX only) index of the screen.
iVisual – (Linux/UNIX only) pointer to the X visual.
iWidth – Window pixel width.
iHeight – Window pixel height.
iInfo – Optional address of a RED::WindowRenderInfo class whose parameters can change the created window hardware parameters. Can be set to NULL to let all default window behaviors unmodified. Any supplied iInfo is duplicated internally by the method, so it can be discarded after the call.
oErrorCode –
RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_BAD_PARAM if iWidth or iHeight is zero or below zero,

RED_DRV_INIT_FAILED if an internal OpenGL error was found,

RED_DRV_CONTEXT_SHARING_NOT_ALLOWED if two windows are using the same external rendering context (every window must own its rendering context),

RED_DRV_CONTEXT_SHARING_ERROR if a global context pool sharing error has occurred (on windows platforms). Please refer to the
RED::WindowRenderInfo
class for all details on the external context sharing mechanism,

RED_DRV_HOST_ERROR if an error was found using the external window and rendering contexts supplied through iInfo. Check that there’s no pending OpenGL error in the external context before creating the window,

RED_DRV_ALLOC_FAILURE if a driver memory allocation has failed,

RED_DRV_UNSUPPORTED_GPU if the computer’s primary GPU is not supported by the engine,

RED_DRV_FRAMEBUFFER_CREATION_ERROR if the window (the first created window) can’t initialize internal auxiliary buffers used by REDsdk,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_WORKFLOW_ERROR if there’s no valid transaction open at the time of the operation,

RED_FAIL otherwise.

Returns

A pointer to the new window on success, NULL otherwise.

static RED::Object *CreateMaterialController(RED::Object &iResourceManager, RED::Object *iMaterial, const RED::String &iCategory, const RED::String &iSubCategory, const RED::String &iDescription, const RED::String &iName, const RED::String &iAuthor, RED_RC &oErrorCode)

Creates an object implementing the RED::IMaterialController interface.

A material controller is used to expose only a few, explicit, high-level parameters for a material. It can be saved and reloaded from .red files. Material controllers register themselves atomatically at their creation to the resource manager and can later be accessed by material using the RED::IResourceManager::GetMaterialController method.

Please go to the \ref bk_bm_the_material_controller page to have details about material controllers.

Parameters

iResourceManager – Reference to the resource manager.
iMaterial – Pointer to the material to be controlled.
iCategory – Category of the controller. There are a number of pre- defined material controllers categories; please, refer to the page: \ref bk_bm_builtin_lib_mat_categories for a full description of the categories.
iSubCategory – Sub-category of the controller. Same as for iCategory above.
iDescription – Description of the material being controlled.
iName – Public name of the material being controlled.
iAuthor – Author of the material.
oErrorCode –
RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

Returns

A pointer to the new object on success, NULL otherwise.

static RED::Object *CreateAnimationClipController(RED::Object &iResourceManager, const RED::AnimationClip &iAnimationClip, RED_RC &oErrorCode)

Creates an object implementing the RED::IAnimationClipController interface.

Parameters

iResourceManager – Reference to the resource manager.
iAnimationClip – Animation clip to be controlled.
oErrorCode –
RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

Returns

A pointer to the new object on success, NULL otherwise.

static RED::Object *CreateSkeletalAnimationClipController(RED::Object &iResourceManager, const RED::AnimationClip &iAnimationClip, RED_RC &oErrorCode)

Creates an object implementing the RED::IAnimationClipController and RED::ISkeletalAnimationController interfaces.

Parameters

iResourceManager – Reference to the resource manager.
iAnimationClip – Animation clip to be controlled.
oErrorCode –
RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

Returns

A pointer to the new object on success, NULL otherwise.

static RED::Object *CreateSkeletalAnimationBlender(RED::Object &iResourceManager, RED_RC &oErrorCode)

Creates an object implementing the RED::ISkeletalAnimationBlender interface.

Parameters

iResourceManager – Reference to the resource manager.
oErrorCode –
RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_FAIL otherwise.

Returns

A pointer to the new object on success, NULL otherwise.

static bool IsRegistered(const RED::CID &iCID)

Checks that a class with the given CID is registered.

This call can be used to verify that a client application will have all creation and usage rights for a given class ID.

Returns: true if a class with the given CID is registered, false otherwise.

static RED::Object *CreateMemoryStream(unsigned char *iStart, RED::uint64 iSize)

Creates a memory stream starting at a given memory address.

Use the RED::IStream interface to manipulate the returned object.

Parameters

iStart – Starting memory address of the stream.
iSize – Allocated size of the memory stream (can’t be 0).

Returns

A pointer on the newly created stream on success,

NULL otherwise.

static RED::Object *CreateMemoryStream()

Creates a memory stream that owns its memory.

Unlike for the other RED::Factory::CreateMemoryStream method, this method lets the memory stream manages it’s own memory. The memory stream will grow in memory upon write requests that are made to it.

Use the RED::IStream interface to manipulate the returned object.

Returns

A pointer on the newly created stream on success,

NULL otherwise, if an error has occurred.

static RED::Object *CreateFileStream(const RED::String &iPath)

Creates a file stream at a given location.

Use the RED::IStream interface to manipulate the returned object.

Parameters

iPath – Path to the location of the stream.

Returns

A pointer on the newly created stream on success,

NULL otherwise.

static RED_RC DeleteStream(RED::Object *iStream)

Deletes a memory or file stream previously created with a call to CreateMemoryStream or CreateFileStream.

Parameters

iStream – pointer to the stream to delete.

Returns

RED_BAD_PARAM if iStream is not a valid pointer to a stream,

RED_OK otherwise.

static RED::Object *CreatePeer()

Creates a REDnet peer.

The returned peer implements the RNET::IPeer interface.

Note that if REDnet is not correctly registered with a valid license, the call will fail returning NULL each time.

Have a look at \ref bk_rednet to have more information about peers with REDnet.

Returns

a pointer to the new REDnet peer on success,

NULL otherwise.

static RED_RC DeletePeer(RED::Object *iPeer)

Deletes a REDnet peer previously created with a call to CreatePeer.

Have a look at \ref bk_rednet to have more information about peers with REDnet.

Returns

RED_OK on success,

RED_BAD_PARAM if iPeer is not a valid pointer to a peer,

RED_FAIL otherwise.

Object *	`CreateInstance`
Object *	`CreateStatelessInstance`
`RED_RC`	`DeleteInstance`
Object *	`CreateREDWindow`
Object *	`CreateMaterialController`
Object *	`CreateAnimationClipController`
Object *	`CreateSkeletalAnimationClipController`
Object *	`CreateSkeletalAnimationBlender`
bool	`IsRegistered`
Object *	`CreateMemoryStream`
Object *	`CreateMemoryStream`
Object *	`CreateFileStream`
`RED_RC`	`DeleteStream`
Object *	`CreatePeer`
`RED_RC`	`DeletePeer`

Factory

Functions

Detailed Description