IResourceManager

Functions

SET_CID

RED_RC

SetPlatform

HARDWARE_PLATFORM

GetPlatform

int

GetNumberOfProcessors

RED_RC

GetWindowList

Object *

GetDataManager

RED_RC

CreateMaterial

RED_RC

CloneMaterial

const Vector < Object * > &

GetMaterialList

RED_RC

DeleteMaterial

RED_RC

DeleteAllMaterials

Object *

FindMaterial

Object *

FindMaterial

RED_RC

FindMaterials

RED_RC

FindMaterials

RED_RC

CleanupMaterials

RED_RC

CreateColorMaterial

RED_RC

CreateColorFontMaterial

RED_RC

CreateTexturedFontMaterial

RED_RC

CreateParametrizationMaterial

RED_RC

CreateImage2D

RED_RC

CreateImage3D

RED_RC

CreateImageCube

RED_RC

CreateImageComposite

RED_RC

CreateImageReadback

RED_RC

CloneImage

Object *

FindImage

const Vector < Object * > &

GetImageList

RED_RC

DeleteImage

RED_RC

DeleteAllImages

RED_RC

CleanupImages

void

SetAliveImagesCheck

bool

IsAliveImagesCheck

RED_RC

CreateFont

RED_RC

DeleteFont

RED_RC

DeleteAllFonts

Object *

FindFont

const Vector < Object * > &

GetFontList

RED_RC

GetAllSystemFonts

RED_RC

CleanupFonts

RED_RC

Cleanup

const State &

BeginState

RED_RC

EndState

const State &

GetState

RED_RC

LoadShaderFromString

RED_RC

GetShader

void

SetInterruptCallback

void

GetInterruptCallback

RED_RC

ClusterMemoryTest

RED_RC

CleanupAllLayerIDs

RED_RC

RegisterMaterialController

RED_RC

UnregisterMaterialController

Object *

GetMaterialController

void

SetBatchSyncCallback

void

GetBatchSyncCallback

RED_RC

RegisterShadingCallback

bool

IsShadingCallbackRegistered

void

GetShadingCallback

RED_RC

UnRegisterShadingCallback

RED_RC

SetErrorCallback

REDSDK_ERROR_CALLBACK

GetErrorCallback

void *

GetErrorCallbackUserData

RED_RC

SetErrorFilePath

const String &

GetErrorFilePath

void

SetOpenGLMaterialCallback

OPENGL_MATERIAL_CALLBACK

GetOpenGLMaterialCallback

void *

GetOpenGLMaterialCallbackUserData

void

SetOpenGLBufferCallback

OPENGL_BUFFER_CALLBACK

GetOpenGLBufferCallback

void *

GetOpenGLBufferCallbackUserData

void

SetOpenGLViewpointCallback

OPENGL_VIEWPOINT_CALLBACK

GetOpenGLViewpointCallback

void *

GetOpenGLViewpointCallbackUserData

void

SetSynchronizationLock

bool

IsSynchronizationLock

Detailed Description

class IResourceManager : public RED::IREDObject

This interface gives access to the resource manager’s properties.

@related Resource Manager

The resource manager is the base class of a visualization cluster. It offers services for a wide range of tasks:

  • It encapsulates the state management API.

  • It’s a pool of graphical resources (materials, shaders, images, fonts).

  • It provides an access to the data manager (RED::IDataManager) for all file operations and animation controls.

  • It controls the hardware platform for the program execution. See the RED::IResourceManager::SetPlatform method for details on runtime platform management by the engine.

A single instance of resource manager is needed to run an application. A resource manager is linked with windows that contains viewpoints that themselves contain scene graphs made of shapes objects. All resources used by these shapes must be managed by the resource manager.

The resource manager should be created at the application startup, before any other graphic operation. Specifically, the resource manager may tune the graphic card driver options, and this must occur before any graphics is started in the application.

State management is defined by transactions that are comprised between RED::IResourceManager::BeginState / RED::IResourceManager::EndState calls:

RED::IWindow *iwindow = ...;
RED::IResourceManager *iresmgr = ...;

const RED::State &state = iresmgr->BeginState();
// Perform changes to cluster data, using:
//   - state for read-write access,
//   - state.GetNumber() for read-only access.
iresmgr->EndState();

// Draw the data in the state defined by the completed transaction:
iwindow->FrameDrawing();

Objects in the REDsdk are either state sensitive or not. State sensitive objects use a RED::State class instance for all read-write access to their contents and a transaction number (the current one or a past one) for all read-only access to their contents.

Read-write operations are authorized on a single thread. Read-only operations are authorized on any thread. The read-write thread may be the window rendering thread or another thread.

Read-write operations are not authorized outside of a transaction. The RED_WORKFLOW_ERROR return code value punishes erroneous accesses.

Image operations are particular because images are not state managed objects. The engine does not have transaction versions of image contents, due to the possible huge size of these data. Therefore:

  • GPU image operations must occur on the rendering thread to avoid rendering conflicts and to avoid stalling the rendering pipeline.

  • CPU image operations can’t occur while the software ray-tracer is processing a scene.

  • Hybrid operations are subject to the two limitations mentioned above.

  • Image creation can be performed anytime from the edition thread, while in transaction.

  • Image destruction can’t occur while the software ray-tracer is processing a scene, and it must occur on the rendering thread.

The resource manager is created with a started transaction, so that the IResourceManager::GetState returns a valid transaction since the startup of the cluster definition. Redundant calls to IResourceManager::BeginState are ignored. The first transaction should be closed before a call to RED::IWindow::FrameDrawing, otherwise there won’t be anything to draw.

Public Functions

SET_CID(CID_class_REDIResourceManager)
virtual RED_RC SetPlatform(RED::HARDWARE_PLATFORM iPlatformId) = 0

Selects the platform identifier for this application.

RED::Shader objects are able to register shaders per platform. A platform may be a chipset revision or an user tag. It’s used to choose the programs and parameters that’ll be used by the shader at runtime for the rendering.

For example, a shader may use a given pixel shader on a NVIDIA hardware and another one on ATI hardware. It may use a set of parameters for a given user tag and another one for another tag. If we think to a game or to a game like application, we could set a “graphic quality” setting, and choose the tag value based on the user’s input.

The engine has a runtime platform, which is set to the identifier of the GPU chipset used by the application, unless it’s changed by this method.

The engine uses a platform tree to parse shader configurations for a version of data that matches the runtime platform requirements.

If the runtime platform is any of the RED::HW_NVIDIA_<chipset> values, then if the shader has no configuration for this platform, the engine will look for a RED::HW_NVIDIA_GENERIC version of the shader. Then, if this research fails, it’ll look for a RED::HW_GENERIC version of the shader. Finally if this fails, there’ll be nothing rendered for this shader.

The same applies to any RED::HW_ATI_<chipset> platform that goes to RED::HW_ATI_GENERIC before going to RED::HW_GENERIC and to any RED::HW_INTEL_<chipset> that goes to RED::HW_INTEL_GENERIC before going to RED::HW_GENERIC.

The same rule also applies to all RED::HW_USER_<number> platforms and to the RED::HW_USER_GENERIC platform.

See RED::HARDWARE_PLATFORM for the list of all available platform identifiers.

The platform can’t be chosen after the startup of the first transaction.

See \ref bk_ba_hardware_platforms for details on this topic.

Parameters

iPlatformId – Platform identifier that’ll be used by the application.

Returns

RED_OK when the platform identifier could be changed,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_WORKFLOW_ERROR if the operation was performed too late.

virtual RED::HARDWARE_PLATFORM GetPlatform() const = 0

Gets the runtime platform identifier.

Returns the identifier of the runtime platform identifier. See the RED::HARDWARE_PLATFORM

enum for the list of all platform identifiers.

Unless specified by

RED::IResourceManager::SetPlatform, the runtime platform is defined by the chipset revision of the computer running the application.

For example, if the program is running on a ATI Radeon 9800 Pro, the returned runtime platform should be RED_HW_ATI_R300.

Note that the runtime platform is defined after the first window creation. Before that, the method will return RED_HW_GENERIC.

See \ref bk_ba_hardware_platforms for details on this topic.

Returns

The current platform identifier.

virtual int GetNumberOfProcessors() const = 0

Returns the number of CPU cores on the system.

This method returns the number of CPU cores available on the system.

See also \ref wf_generating_vector_graphics.

Returns

The effective number of cores found on the system. The method returns 0 in case of error.

virtual RED_RC GetWindowList(RED::Vector<RED::Object*> &oWindowList, int iStateNumber = -1) const = 0

Gets the list of windows we have in the cluster.

Parameters
  • oWindowList – A vector filled with all addresses of all windows that exist at that time in the cluster.

  • iStateNumber – Queried transaction number.

Returns

RED_OK when the operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.

virtual RED::Object *GetDataManager() = 0

Retrieves the cluster’s data manager instance.

This method returns the data manager object instance that is associated to this cluster. The data manager is used for all context based animations for loaded files.

The returned data manager implements the RED::IDataManager interface.

Returns

The cluster’s data manager instance,

NULL if its memory allocation has failed.

virtual RED_RC CreateMaterial(RED::Object *&oMaterial, const RED::State &iState) = 0

Creates a new REDMaterial instance.

This method instantiates a new material object. That material can be set as the material of a given shape instance using RED::IShape::SetMaterial.

See also \ref wf_hello_world.

Parameters
  • oMaterial – Pointer to the created material object.

  • iState – Current transaction parameter.

Returns

RED_OK when the material could be created,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.

virtual RED_RC CloneMaterial(RED::Object *&oMaterial, RED::Object *iSource, const RED::State &iState, bool iImageCopy = false, bool iTinyImageCopy = true) = 0

Clones a material instance.

This method performs a clone of a given iSource Material. The created clone has all shaders and all rendering configurations duplicated. Depending on the value of iImageCopy and iTinyImageCopy, all images that are pointed to by oMaterial can either be copies of all images in iSource or can be shared images.

Note that if an image is shared by several parameters in iSource, the copy of that image will be shared by the same set of cloned parameters in oMaterial if iImageCopy (or iTinyImageCopy depending on the image size) is true. If iImageCopy (or iTinyImageCopy) is false, then the same image address will be shared by both sets of parameters in iSource and in oMaterial.

iImageCopy refers to images whose pixel size is above 1 in at least one dimension, iTinyImageCopy refers to images whose pixel size is exactly 1 in all dimensions. Tiny images are often used in textured shader constructions, where if a shader uses at least one texture, all its parameters are set to textures.

Note that all local storages of all images that are cloned are overriden during the operation. Therefore, any data stored in any duplicated image storage will be lost.

See also \ref wf_using_realistic_material.

Parameters
  • oMaterial – Address of the cloned material object.

  • iSource – Material source to clone.

  • iImageCopy – If true, we do copy all images whose pixel size is greater than 1x1 in iSource and set these copies to be used by oMaterial. If false, all images in iSource are also pointed to by oMaterial.

  • iTinyImageCopy – If true, we do copy all images whose pixel size is exactly 1x1 in iSource and set these copies to be used by oMaterial. If false, all tiny images in iSource are also pointed to by oMaterial.

  • iState – Current transaction parameter.

Returns

RED_OK when the material could successfully be cloned,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_SCG_INVALID_IMAGE_ADDRESS if iSource has a shader using an invalid texture,

RED_FAIL if iSource has a shader parameter of the image kind pointing to an object which is not an image. RED_FAIL otherwise.

virtual const RED::Vector<RED::Object*> &GetMaterialList(int iStateNumber = -1) const = 0

Returns the list of materials.

The returned list is not reliable if materials are created or deleted while it’s in use.

Parameters

iStateNumber – Queried transaction number.

Returns

The resource manager list of materials. The list is returned empty if it does not exist for the provided transaction number.

virtual RED_RC DeleteMaterial(RED::Object *ioMaterial, const RED::State &iState) = 0

Deletes a material from the resource manager.

This method deletes a material from the resource manager. The caller should ensure that this material is no longer used by any shape of any scene graph in the cluster. If the material has a controller that is associated to it, the controller is unregistered from the material and destroyed by the call.

See also \ref tk_creating_and_destroying_materials.

Parameters
  • ioMaterial – Material pointer to the class to delete.

  • iState – Current transaction parameter.

Returns

RED_OK when the deletion operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_WORKFLOW_ERROR if the deletion occurs outside of a transaction,

RED_FAIL otherwise.

virtual RED_RC DeleteAllMaterials(const RED::State &iState) = 0

Deletes all the materials from the resource manager.

Parameters

iState – Current transaction parameter.

Returns

RED_OK when the deletion operation succeeded,

RED_BAD_PARAM if the method received an invalid parameter,

RED_WORKFLOW_ERROR if the deletion occurs outside of a transaction,

RED_FAIL otherwise.

virtual RED::Object *FindMaterial(unsigned int iMaterialID, int iStateNumber = -1) = 0

Search a material by its id.

Performs a search of the material by the provided iMaterialID. The first material occurrence with this ID is returned.

See also \ref wf_section_cutting.

Parameters
  • iMaterialID – Identifier of the material to look for.

  • iStateNumber – Queried transaction number.

Returns

NULL in case of failure, or the found material in case of success.

virtual RED::Object *FindMaterial(const RED::String &iMaterialLabel, int iStateNumber = -1) = 0

Search a material by its label.

This is a helper which calls FindMaterial( iMaterialLabel.ToID(), iStateNumber ).

See also \ref wf_section_cutting.

Parameters
  • iMaterialLabel – Label of the material to look for.

  • iStateNumber – Queried transaction number.

Returns

NULL in case of failure, or the found material in case of success.

virtual RED_RC FindMaterials(RED::Vector<RED::Object*> &oMaterials, unsigned int iMaterialID, int iStateNumber = -1) = 0

Searches all materials with a given id.

Searches all materials having the iMaterialID id.

Parameters
  • oMaterials – A vector filled with all materials found.

  • iMaterialID – Identifier of the material to look for.

  • iStateNumber – Queried transaction number.

Returns

RED_OK when the material list could be build,

RED_ALLOC_FAILURE if an internal allocation did fail.

virtual RED_RC FindMaterials(RED::Vector<RED::Object*> &oMaterials, const RED::String &iMaterialID, int iStateNumber = -1) = 0

Searches all materials with a given label.

This is a helper which calls FindMaterials( oMaterials, iMaterialLabel.ToID(), iStateNumber ).

Parameters
  • oMaterials – A vector filled with all materials found.

  • iMaterialID – Identifier of the material to look for.

  • iStateNumber – Queried transaction number.

Returns

RED_OK when the material list could be build,

RED_ALLOC_FAILURE if an internal allocation did fail.

virtual RED_RC CleanupMaterials(const RED::Vector<RED::Object*> &iScope, const RED::Vector<RED::Object*> &iNotMe, const RED::State &iState) = 0

Material list cleanup tool.

This method is used to delete all materials that are no longer in use within the cluster. A material is considered useless if there’s no shape object that is using it AND that is connected to a viewpoint.

The method won’t catch materials of shapes that are not in a scene graph connected to a viewpoint.

Shared resources used by the freed materials (images, fonts, programs) are not deleted by this call. See the corresponding cleanup calls to perform the dedicated operations.

All materials of the resource manager are checked, unless the ‘iScope’ list is filled with a list of objects to handle. If ‘iScope’ is not empty, then only objects in it will be searched for cleanup.

The ‘iNotMe’ list indicates a list of objects that must not be removed. That way it’s possible to clean materials but to keep some specific instances that are needed later for other purposes, but that could be unused at the time of the call.

Due to state management, effective destruction of cleaned resources only occur at the closing of the transaction after this one.

Parameters
  • iScope – If set to a non empty list, it indicates the set of objects that must be considered by the call. Let this vector empty to clean the whole contents of the resource manager.

  • iNotMe – Exclusion list. When set to a non empty list, all objects in it are kept alive.

  • iState – Current transaction parameter.

Returns

RED_OK when the operation has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC CreateColorMaterial(RED::Object *&oMaterial, const RED::Color &iColor, const RED::State &iState) = 0

Constant color material.

This method creates a material set with a constant color, in a RED::RenderShaderSolid. The shader is in the RED::MTL_PRELIT rendering pass.

See also \ref wf_geometry_layers.

Parameters
  • oMaterial – Returned created material.

  • iColor – Creation color.

  • iState – Current transaction.

Returns

RED_OK in case of success,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if a memory allocation failed,

RED_FAIL otherwise.

virtual RED_RC CreateColorFontMaterial(RED::Object *&oMaterial, const RED::Color &iColor, const RED::State &iState) = 0

Constant color material for fonts.

This method creates a material set with a constant color suitable to render RED::FNT_TRIANGLE fonts. RED::FNT_TRIANGLE fonts don’t support high definition matrices and therefore can’t be rendered using built-in shaders.

See also \ref wf_geometry_layers.

Parameters
  • oMaterial – Returned created material.

  • iColor – Creation color.

  • iState – Current transaction.

Returns

RED_OK in case of success,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if a memory allocation failed,

RED_FAIL otherwise.

virtual RED_RC CreateTexturedFontMaterial(RED::Object *&oMaterial, const RED::Color &iColor, const RED::State &iState) = 0

Helper to create a complete textured font material.

Creates a complete material for the rendering of textured fonts. A state shader is set in the RED::MTL_PRELIT to do an ADDITIVE blending of the RED::RenderShaderText that follows after. The rendering uses the provided ‘iColor’. The shader uses the linear alpha interpolation mode.

See also \ref wf_displaying_texts.

Parameters
  • oMaterial – Returned created material.

  • iColor – Creation color.

  • iState – Current transaction.

Returns

RED_OK in case of success,

RED_BAD_PARAM if the method received an invalid parameter,

RED_ALLOC_FAILURE if a memory allocation failed,

RED_FAIL otherwise.

virtual RED_RC CreateParametrizationMaterial(RED::Object *&oMaterial, RED::MESH_CHANNEL iParameterChannel, const RED::Color &iColor, float iLineWidth, int iStippleFactor, unsigned short iStipplePattern, bool iSmooth, const RED::State &iState) = 0

Creates a material for the display of dashed lines after a parametrization.

A special material is required to display the results of a call to RED::ILineShape::Parametrize. This method creates the material with the requested setup to do so. Specifically, it discards connectivity strip segments that are requested to draw the strip geometry into one single part.

See the RED::ILineShape::Parametrize method for all details. The ‘iParameterChannel’ should be set to the geometrical channel used to store the results of the parametrization. Then, the material is set to render lines with a stipple pattern ( ‘iStippleFactor’ and ‘iStipplePattern’ ) as they can be specified in a RED::StateShader, and may apply line smoothing (and blending) based on ‘iSmooth’.

The created material has disabled batching capabilities (RED::IMaterial::SetBatchMode) so that different shapes can use it.

See also \ref wf_generating_vector_graphics.

Parameters
  • oMaterial – The created material.

  • iParameterChannel – The channel that contains the parametrization of the strip to draw.

  • iColor – The material’s color.

  • iLineWidth – Line thickness.

  • iStippleFactor – The repeating factor of the stipple pattern.

  • iStipplePattern – The stipple pattern. If the value of the pattern is set to 0xffff, a continuous line is rendered without stipple pattern.

  • iSmooth – Enable line smoothing on / off.

  • iState – Current transaction parameter.

Returns

RED_OK if the creation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC CreateImage2D(RED::Object *&oImage2D, const RED::State &iState) = 0

Creates a new 2D image instance.

Creates a new 2D bitmap image instance. At least one window must have been created before calling this method. Images can be created from any thread that is the unique edition thread, assuming that the engine has a valid transaction being opened.

\task tk_creating_a_2d_image for details.

Parameters
  • oImage2D – Address of the created 2D image.

  • iState – The current transaction.

Returns

RED_OK when the image could successfully be created,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_INIT_FAILED if no window has ever been created yet,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_FAIL otherwise.

virtual RED_RC CreateImage3D(RED::Object *&oImage3D, const RED::State &iState) = 0

Creates a new 3D image instance.

Creates a new volume image instance. At least one window must have been created before calling this method. Images can be created from any thread that is the unique edition thread, assuming that the engine has a valid transaction being opened.

\task tk_creating_a_3d_image for details.

Parameters
  • oImage3D – Address of the created 3D image.

  • iState – The current transaction.

Returns

RED_OK when the image could successfully be created,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_INIT_FAILED if no window has ever been created yet,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_FAIL otherwise.

virtual RED_RC CreateImageCube(RED::Object *&oImageCube, const RED::State &iState) = 0

Creates a new cube image instance.

Creates a new cube image instance. At least one window must have been created before calling this method. Images can be created from any thread that is the unique edition thread, assuming that the engine has a valid transaction being opened.

\task tk_creating_a_cube_image for details.

Parameters
  • oImageCube – Address of the created REDImageCube.

  • iState – The current transaction.

Returns

RED_OK when the image could successfully be created,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_INIT_FAILED if no window has ever been created yet,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_FAIL otherwise.

virtual RED_RC CreateImageComposite(RED::Object *&oImageComp, const RED::State &iState) = 0

Creates a new composite image instance.

Creates a new composite image instance. At least one window must have been created before calling this method. Images can be created from any thread that is the unique edition thread, assuming that the engine has a valid transaction being opened.

See also \ref wf_setup_a_composite_image.

Parameters
  • oImageComp – Address of the created composite image.

  • iState – The current transaction.

Returns

RED_OK when the image could successfully be created,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_INIT_FAILED if no window has ever been created yet,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_FAIL otherwise.

virtual RED_RC CreateImageReadback(RED::Object *&oImageReadback, const RED::State &iState) = 0

Creates a new readback image instance.

Creates a new composite image instance. At least one window must have been created before calling this method. Images can be created from any thread that is the unique edition thread, assuming that the engine has a valid transaction being opened.

Parameters
  • oImageReadback – Address of the created REDImageReadback.

  • iState – The current transaction.

Returns

RED_OK when the image could successfully be created,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_INIT_FAILED if no window has ever been created yet,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_FAIL otherwise.

virtual RED_RC CloneImage(RED::Object *&oImageClone, RED::Object *iSource, const RED::State &iState) = 0

Creates a duplicate copy of the specified source image.

This method creates a full copy of the ‘iSource’ image. All parameters of the image are duplicated, including all pixel arrays, both in hardware and software operating environments.

Note that the local pixel storage of ‘iSource’ is used and overriden during the operation, so any former pixel data stored in the image local storage will be lost.

A built-in render image of a VRL can’t be cloned. See RED::IViewpointRenderList::GetRenderImage for details. Another render image should be created using RED::IImage2D::SetRenderImage instead.

See also \ref tk_duplicating_an_image.

Parameters
  • oImageClone – Image copy created by the method.

  • iSource – Source image to be copied. ‘iSource’ local storage will be overriden.

  • iState – The current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_SCG_INVALID_IMAGE_ADDRESS if ‘iSource’ is not a valid cluster image,

RED_ALLOC_FAILURE if a memory allocation has failed,

RED_DRV_ALLOC_FAILURE if a GPU memory allocation has failed,

RED_FAIL otherwise.

virtual RED::Object *FindImage(unsigned int iImageID, int iStateNumber = -1) const = 0

Searches an image by its id.

Performs a search of the image by the provided iImageID. The first image occurrence found with that ID is returned.

Parameters
  • iImageID – Identifier of the image to look for.

  • iStateNumber – Queried transaction number.

Returns

NULL in case of failure, or the found image in case of success.

virtual const RED::Vector<RED::Object*> &GetImageList(int iStateNumber = -1) const = 0

Returns the list of images stored by the resource manager.

Please note that the returned list is not reliable if images are created or deleted while it’s in use, as the returned vector is a pointer to the class’ internal image list.

Parameters

iStateNumber – Queried transaction number.

Returns

A reference to the resource manager list of images.

virtual RED_RC DeleteImage(RED::Object *iImage, const RED::State &iState) = 0

Deletes an image from the resource manager.

This is the caller’s responsibility to ensure that this image is no longer used by any material or viewpoint parameter or instance callback used in the cluster at the time of the operation.

On calling this method a search for remaining usages of the image is made, which can take a bit of time in large clusters. In that case, the RED::IResourceManager::SetAliveImagesCheck method can be used to enable / disable the usage search. If the image is found to be still used, RED_SCG_IMAGE_STILL_IN_USE is returned and the REDsdk error callback will provide the address of the object holding the image (viewpoint, material). The image will not be released.

Image destruction is immediate. The image may be still referenced in the previous transaction list of images stored by the resource manager. It’s the responsibility of the caller to make sure that this image is not used anymore.

Image destruction should only occur from the rendering thread and it can’t happen while the software ray-tracer is rendering a scene.

See also \ref tk_creating_and_destroying_images.

Parameters
  • iImage – Image address to be deleted.

  • iState – The current transaction.

Returns

RED_OK when the image could successfully be destroyed,

RED_WORKFLOW_ERROR if a transaction error has occurred,

RED_WORKFLOW_ERROR is a software tracer image is being processed,

RED_SCG_IMAGE_STILL_IN_USE is iImage is still used somewhere,

RED_FAIL if the object is not an image.

virtual RED_RC DeleteAllImages(const RED::State &iState) = 0

Deletes all images from the resource manager.

This is the caller’s responsibility to ensure that no more image are used by any material used in the cluster at the time of the operation.

Image destruction is immediate. Image may be still referenced in the previous transaction list of images stored by the resource manager. It’s the responsibility of the caller to make sure that these images are not used anymore.

Image destruction should only occur from the rendering thread and it can’t happen while the software ray-tracer is rendering a scene.

Parameters

iState – The current transaction.

Returns

RED_OK if the deletion operation has succeeded,

RED_WORKFLOW_ERROR if the deletion has occurred outside of a transaction,

RED_WORKFLOW_ERROR if a software traced image is in progress,

RED_FAIL otherwise.

virtual RED_RC CleanupImages(const RED::Vector<RED::Object*> &iScope, const RED::Vector<RED::Object*> &iNotMe, const RED::State &iState) = 0

Image list cleanup tool.

This method is used to delete all images that are no longer in use within the cluster. An image is considered useless if there’s no material using it.

All images of the resource manager are checked, unless the ‘iScope’ list is filled with a list of objects to handle. If ‘iScope’ is not empty, then only objects in it will be searched for cleanup.

The ‘iNotMe’ list indicates a list of objects that must not be removed. That way it’s possible to clean images but to keep some specific instances that are needed later for other purposes, but that could be unused at the time of the call.

This method calls RED::IResourceManager::DeleteImage, and is subject to the same calling restrictions.

Parameters
  • iScope – If set to a non empty list, it indicates the set of objects that must be considered by the call. Let this vector empty to clean the whole contents of the resource manager.

  • iNotMe – Exclusion list. When set to a non empty list, all objects in it are kept alive.

  • iState – The current transaction.

Returns

RED_OK when the operation has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_WORKFLOW_ERROR if the operation occurs outside of a transaction,

RED_FAIL otherwise.

virtual void SetAliveImagesCheck(bool iOnOff) = 0

Turn on or off live image checking within REDsdk.

This method can be called to turn on or off live image checking in REDsdk. When enabled, all images used in materials or by controllers are checked whenever possible for existence (e.g. are these image addresses part of RED::IResourceManager::GetImageList?).

Unless your application is performance critical, there’s no need to turn live image checking off. The extra cost is in the millisecond range and proportional to the number of material changes that occur per frame.

Default alive image checking is disabled.

An image address which is found invalid triggers a RED_SCG_INVALID_IMAGE_ADDRESS error code.

Parameters

iOnOff – Set to false to turn off live image checking.

virtual bool IsAliveImagesCheck() const = 0
Returns

true if alive image checking is enabled, false otherwise.

virtual RED_RC CreateFont(RED::Object *&oFont, const RED::State &iState) = 0

Creates a font object instance.

The created font must be specified before it can be used within a CID_REDTextShape (see RED::ITextShape) instance for the rendering.

\task tk_creating_a_font

Parameters
  • oFont – Created font object.

  • iState – Current transaction parameter.

Returns

RED_OK when the material could be created,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.

virtual RED_RC DeleteFont(RED::Object *ioFont, const RED::State &iState) = 0

Deletes a font object instance.

Deletes all fonts stored by the resource manager. It’s the caller’s responsibility to ensure that that font is no longer used by any shape in any scene graph of the cluster.

Parameters
  • ioFont – Font object address to be deleted.

  • iState – Current transaction parameter.

Returns

RED_OK when the deletion operation has succeeded,

RED_BAD_PARAM if an invalid address was provided to the method,

RED_WORKFLOW_ERROR if the deletion occurs outside of a transaction,

RED_FAIL otherwise.

virtual RED_RC DeleteAllFonts(const RED::State &iState) = 0

Deletes all font objects instances.

Deletes all fonts stored by the resource manager. It’s the caller’s responsibility to ensure that these fonts are no longer used by any shape in any scene graph of the cluster.

Parameters

iState – Current transaction parameter.

Returns

RED_OK when the deletion operation has succeeded,

RED_BAD_PARAM if an invalid address was provided to the method,

RED_WORKFLOW_ERROR if the deletion occurs outside of a transaction,

RED_FAIL otherwise.

virtual RED::Object *FindFont(unsigned int iFontID, int iStateNumber = -1) const = 0

Finds a font instance by its ID.

Parameters
  • iFontID – Identifier of the font to look for.

  • iStateNumber – Queried transaction number.

Returns

NULL in case of failure, or the found font in case of success.

virtual const RED::Vector<RED::Object*> &GetFontList(int iStateNumber = -1) const = 0

Returns the list of fonts.

The returned list is not reliable if fonts are created or deleted while it’s in use.

Parameters

iStateNumber – Queried transaction number.

Returns

The resource manager list of fonts. The list is returned empty if it does not exist for the provided transaction number.

virtual RED_RC GetAllSystemFonts(RED::Vector<RED::String> &oFontList) const = 0

Enumerates all available system fonts.

This method enumerates all fonts available in the system. Returned fonts are identified by their full typeface string. At least a window must have been created for this call to work.

Parameters

oFontList – List of available fonts.

Returns

RED_OK when the operation succeeded,

RED_INIT_FAILED if we have no valid window in the cluster,

RED_ALLOC_FAILURE if an internal allocation did fail,

RED_FAIL otherwise.

virtual RED_RC CleanupFonts(const RED::Vector<RED::Object*> &iScope, const RED::Vector<RED::Object*> &iNotMe, const RED::State &iState) = 0

Font list cleanup tool.

This method is used to delete all fonts that are no longer in use within the cluster. A fotn is considered useless if there’s no shape object that is using it AND that is connected to a viewpoint.

The method won’t catch fonts of shapes that are not in a scene graph connected to a viewpoint.

All fonts of the resource manager are checked, unless the ‘iScope’ list is filled with a list of objects to handle. If ‘iScope’ is not empty, then only objects in it will be searched for cleanup.

The ‘iNotMe’ list indicates a list of objects that must not be removed. That way it’s possible to clean fonts but to keep some specific instances that are needed later for other purposes, but that could be unused at the time of the call.

Due to state management, effective destruction of cleaned resources only occur at the closing of the transaction after this one.

Parameters
  • iScope – If set to a non empty list, it indicates the set of objects that must be considered by the call. Let this vector empty to clean the whole contents of the resource manager.

  • iNotMe – Exclusion list. When set to a non empty list, all objects in it are kept alive.

  • iState – Current transaction parameter.

Returns

RED_OK when the operation has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual RED_RC Cleanup(const RED::Vector<RED::Object*> &iScope, const RED::Vector<RED::Object*> &iNotMe, const RED::State &iState) = 0

General resource manager shared resources cleanup.

This method calls the cleanup tool for materials, images and fonts, without any exclusion list. Therefore, anyone useless is deleted. The method takes care of cleaning materials before images so that we don’t waste memory.

The iNotMe list indicates a list of objects that must not be removed. That way it’s possible to clean objects but to keep some specific instances that are needed later for other purposes, but that could be unused at the time of the call.\

The method must be called on the rendering thread during a valid transaction as it may destroy images.

Parameters
  • iScope – If set to a non empty list, it indicates the set of objects that must be considered by the call. Let this vector empty to clean the whole contents of the resource manager.

  • iNotMe – Exclusion list. When set to a non empty list, all objects in it are kept alive.

  • iState – Current transaction parameter.

Returns

RED_OK when the operation has succeeded,

RED_ALLOC_FAILURE if an internal allocation has failed,

RED_FAIL otherwise.

virtual const RED::State &BeginState() = 0

Generates a new transaction (or frame) identifier.

This method creates a RED::State object that must be used for all changes in REDsdk. It uniquely identifies the transaction (or frame) being defined (see RED::State::GetNumber to get the transaction number). The transaction defines a begin / end interval. Any change that occur between a call to RED::IResourceManager::BeginState and RED::IResourceManager::EndState is recorded as being part of that transaction. All methods actually modifying the engine contents are using a RED::State instance as the last method parameter.

Note that if a transaction has already been started, this method returns the current transaction.

From this call up to RED::IResourceManager::EndState, all calls that perform modifications on the rendered data in the engine should occur on the same thread.

The resource manager is created with a started transaction, so there’s no need for call to RED::IResourceManager::BeginState call upon startup, before the first draw. However, a transaction must be closed before the first draw.

See \ref bk_ba_transaction_management for details on transactions.

Returns

The RED::State object identifying the transaction.

virtual RED_RC EndState() = 0

Indicates the end of a transaction.

This method terminates the transaction initiated earlier on by RED::IResourceManager::BeginState. From now on, all changes to perform on engine data must occur using another transaction, that is to be initiated again by a call to RED::IResourceManager::BeginState.

The next draw method will render the most recent finished transaction. This is the transaction number defined by the last call to RED::IResourceManager::EndState. Note that at least one first transaction must be finished to before calling a rendering method on the RED::IWindow.

Calling this method several times has no effect. The first call closes the current transaction and all subsequent calls are ignored.

This method flushes all the pending orders that have been defined during the transaction. It destroys all objects that have been sent to the RED::Factory::DeleteInstance, and performs the update of the entire engine data cluster for the rendering.

This method should not be called if no window has been created yet. As REDsdk is a hybrid CPU / GPU rendering engine, it may need to do OpenGL operations during the EndState call. Before it can proceed with any OpenGL operation, it needs a window that provides the necessary informations to setup the link with the OpenGL layer of the hosting system.

See \ref bk_ba_transaction_management for details on transactions.

Returns

RED_OK when the transaction could be successfully ended,

RED_ALLOC_FAILURE if an internal memory allocation has failed,

RED_INIT_FAILED if we have no window created yet. Due to possible GPU updates, REDsdk needs a window to be created before any transaction can be closed,

Any other return code issued from modified objects.

virtual const RED::State &GetState() const = 0

Gets the current state transaction object.

This method can be queried anytime to figure out the current status of the cluster versus transactions.

If we’re in a BeginState/EndState transaction, the method returns the current state, that is also retrieved by the RED::IResourceManager::BeginState method. If we are not in a transaction, the method returns an invalid state, whose mode is set to RED::TRANSACTION_OUT.

See \ref bk_ba_transaction_management for details on transactions.

Returns

A reference to a RED::State indicating the current transaction.

virtual RED_RC LoadShaderFromString(RED::ShaderProgramID &oShaderID, const RED::String &iShaderProgram) = 0

Loads a shader program from a character string.

This method loads the shader from the iShaderProgram contents. The method returns an identifier in oShaderId that can be used to access to the loaded byte buffer, using RED::IResourceManager::GetShader.

Theis method can be used to load ARB programs or GLSL programs under OpenGL.

See also \ref wf_cartoon_shading.

Parameters
  • oShaderIDShader identifier to rely on for this shader. This identifier value will remain valid until the resource manager’s destruction.

  • iShaderProgramShader program string.

Returns

RED_OK when the shader was successfully accessed,

RED_ALLOC_FAILURE if an internal memory allocation did fail,

RED_FAIL when an unexpected error occurred.

virtual RED_RC GetShader(const RED::String *&oShaderString, const RED::ShaderProgramID &iShaderID) = 0

Gets the shader program string.

This method returns the program associated to a given iShaderID shader ID.

Parameters
  • oShaderString – Returned shader program when found, NULL otherwise. This string address directly points into the resource manager program storage, so please don’t delete it!

  • iShaderIDShader identifier.

Returns

RED_OK if the shader program could be accessed,

RED_BAD_PARAM if the method has received an invalid parameter,

RED_FAIL otherwise.

virtual void SetInterruptCallback(RED::INTERRUPT_CALLBACK iCallback, void *iUserData) = 0

Sets the user defined interruption callback.

The engine calls the interrupt callback on a regular basis during the rendering of a frame. This can be used to stop a frame whenever the user does not want it to finish.

Parameters
  • iCallback – Pointer to the user defined callback.

  • iUserData – User data argument to the callback.

virtual void GetInterruptCallback(RED::INTERRUPT_CALLBACK &oCallback, void *&oUserData) const = 0

Returns the current user interruption callback.

Parameters
  • oCallback – The address of the callback being set if any.

  • oUserData – The user data associated to the callback.

virtual RED_RC ClusterMemoryTest(void **oInvalidAddress) = 0

Tests the entire cluster memory.

This method tests the existence of every object inside the cluster. All windows, viewpoints, materials, shaders, images, etc… addresses are verified. The test will stop on the first invalid address found.

The method only works if the

RED::MemoryLeakTracker has been enabled before the resource manager creation. If this is not the case, then the method will return RED_WORKFLOW_ERROR.

Parameters

oInvalidAddress – Returned set to an invalid address if an error occurs during the cluster test.

Returns

RED_OK if the cluster is safe,

RED_BAD_PARAM if oInvalidAddress is not a valid address. RED_WORKFLOW_ERROR if the memory leak tracker is not active or has not been activated before the resource manager creation,

RED_FAIL if an invalid address has been found inside the cluster.

virtual RED_RC CleanupAllLayerIDs(const RED::State &iState) = 0

Clears all known layer identifiers for the cluster.

This method must be carefully used as it’ll destroy all IDs known for all layers in the cluster. Therefore, after use, an existing RED::LayerSet object won’t be valid anymore, as it’s existing layer mask won’t correspond to anything valid for the cluster.

After the call, new layers that are declared will re-use existing layer bits positions that could have been used before by other layers.

The method automatically removes all layersets for all shapes instances connected to cameras that are inserted in cluster windows. However, it can’t clear layersets of shapes that are not connected to a cluster connected camera.

Parameters

iState – Current transaction parameter.

Returns

RED_OK if the operation has succeeded,

RED_FAIL otherwise.

virtual RED_RC RegisterMaterialController(RED::Object *iMaterialController) = 0

Registers a material controller.

The given controller will be registered for the material it points to (the one passed at the controller creation). If the material has already a controller registered for, the passed controller will be ignored and nothing will be done by the call. You must previously ensure that the material has no controller registered for (by using GetMaterialController and optionally UnregisterMaterialController).

Parameters

iMaterialController – pointer to the material controller.

Returns

RED_OK on success,

RED_BAD_PARAM if the parameter is NULL or does not implement the required interface,

RED_ALLOC_FAILURE on memory allocation error,

RED_FAIL otherwise.

virtual RED_RC UnregisterMaterialController(const RED::Object *iMaterial) = 0

Unregisters a material controller.

If the given material has no controller registered for or is NULL, the method will return RED_OK. The controller, if it exists, is not destroyed by the call.

Parameters

iMaterial – pointer to the controlled material.

Returns

RED_OK on success,

RED_FAIL otherwise.

virtual RED::Object *GetMaterialController(const RED::Object *iMaterial) const = 0

Gets a material controller for a given material.

The returned object implements the RED::IMaterialController interface.

See also \ref wf_using_realistic_material.

Parameters

iMaterial – pointer to the material.

Returns

a pointer to the material controller if any, NULL otherwise.

virtual void SetBatchSyncCallback(RED::BATCH_SYNC_CALLBACK iCallback, void *iUserData) = 0

Setups a callback to flag the end of GPU data synchronization.

See the RED::BATCH_SYNC_CALLBACK details for explanations on the batch synchronization callback.

Parameters
  • iCallback – The callback address.

  • iUserData – User data argument to the callback.

virtual void GetBatchSyncCallback(RED::BATCH_SYNC_CALLBACK &oCallback, void *&oUserData) const = 0

Returns the batch sync callback parameters currently set.

Parameters
  • oCallback – The address of the callback being set if any.

  • oUserData – The user data associated to the callback.

virtual RED_RC RegisterShadingCallback(const RED::String &iLabel, RED::SOFT_SHADER_CALLBACK iCallback, void *iUserData) = 0

Registers a custom shading callback.

If a different callback has already been registered for the given label, RED_FAIL is returned.

See also \ref wf_cartoon_shading.

Parameters
  • iLabel – label of the custom callback. This is the label passed to the RED::ShaderString::SoftShaderStart method.

  • iCallback – pointer to the shading callback.

  • iUserData – optional custom user data.

Returns

RED_BAD_PARAM on an invalid parameter,

RED_ALLOC_FAILURE on a memory allocation error,

RED_OK on success.

virtual bool IsShadingCallbackRegistered(const RED::String &iLabel) const = 0

Checks if a custom shading callback has already been registered for the given label.

Parameters

iLabel – label of the custom callback.

Returns

true if a callback has already been registered for the given label, false otherwise.

virtual void GetShadingCallback(RED::SOFT_SHADER_CALLBACK &oCallback, void *&oUserData, const RED::String &iLabel) const = 0

Gets a registered shading callback from its label.

Parameters
  • oCallback – pointer to the callback registered with the provided label on sucess, NULL otherwise.

  • oUserData – pointer to the custom user data on sucess, NULL otherwise.

  • iLabel – registration label of the shading callback.

virtual RED_RC UnRegisterShadingCallback(const RED::String &iLabel) = 0

Un-registers a custom shading callback.

If no callback is registered for the given label, the method returns RED_OK.

Parameters

iLabel – label of the custom callback to unregister.

Returns

RED_OK on success, RED_FAIL otherwise.

virtual RED_RC SetErrorCallback(RED::REDSDK_ERROR_CALLBACK iCallback, void *iUserData) = 0

Setup an error callback.

Parameters
  • iCallback – The error callback. Set it to NULL to remove any previous callback.

  • iUserData – User data pointer.

Returns

RED_OK if the method has succeeded,

RED_FAIL otherwise.

virtual RED::REDSDK_ERROR_CALLBACK GetErrorCallback() const = 0
Returns

The current error callback.

virtual void *GetErrorCallbackUserData() const = 0
Returns

The current error callback user data.

virtual RED_RC SetErrorFilePath(const RED::String &iFilePath) = 0

Sets the path of the REDsdk error file.

Defines the complete filepath of the “redsdk_error.txt” file which can be produced by REDsdk whenever an error occurs. See \ref bk_ba_error_tracking for details on detailed error handling within REDsdk. If the folder does not exist, no error file will be written by REDsdk. The default error filepath is the current directory: “.”.

Parameters

iFilePath – The complete filepath to the folder in which the error file will be written to. Example: “C:/Users/Bob/log”.

Returns

RED_OK if the method has succeeded,

RED_ALLOC_FAILURE if a memory allocation error has occurred.

virtual const RED::String &GetErrorFilePath() const = 0
Returns

The current error file path.

virtual void SetOpenGLMaterialCallback(RED::OPENGL_MATERIAL_CALLBACK iCallback, void *iUserData) = 0

Setup an OpenGL material callback.

Parameters
  • iCallback – The callback. Set it to NULL to remove any previous callback.

  • iUserData – User data pointer.

virtual RED::OPENGL_MATERIAL_CALLBACK GetOpenGLMaterialCallback() const = 0
Returns

The current OpenGL material callback.

virtual void *GetOpenGLMaterialCallbackUserData() const = 0
Returns

The current OpenGL material callback user data.

virtual void SetOpenGLBufferCallback(RED::OPENGL_BUFFER_CALLBACK iCallback, void *iUserData) = 0

Setup an OpenGL buffer callback.

Parameters
  • iCallback – The callback. Set it to NULL to remove any previous callback.

  • iUserData – User data pointer.

virtual RED::OPENGL_BUFFER_CALLBACK GetOpenGLBufferCallback() const = 0
Returns

The current OpenGL buffer callback.

virtual void *GetOpenGLBufferCallbackUserData() const = 0
Returns

The current OpenGL buffer callback user data.

virtual void SetOpenGLViewpointCallback(RED::OPENGL_VIEWPOINT_CALLBACK iCallback, void *iUserData) = 0

Setup an OpenGL viewpoint callback.

Parameters
  • iCallback – The callback. Set it to NULL to remove any previous callback.

  • iUserData – User data pointer.

virtual RED::OPENGL_VIEWPOINT_CALLBACK GetOpenGLViewpointCallback() const = 0
Returns

The current OpenGL viewpoint callback.

virtual void *GetOpenGLViewpointCallbackUserData() const = 0
Returns

The current OpenGL viewpoint callback user data.

virtual void SetSynchronizationLock(bool iOnOff) = 0

Turn on or off the synchronization lock.

This method can be used to disarm the internal synchronization lock used to prevent concurrent accesses to occur while using REDsdk in a multi-threaded environment with reader & writer threads. This method should be called once at the application startup. Turning off the synchronization lock can improve REDsdk edition performance a bit in performance critical applications.

Parameters

iOnOff – true (default) to turn on the synchronization lock, false to disable it.

virtual bool IsSynchronizationLock() const = 0
Returns

true if the synchronization lock is enabled, false otherwise.