IResourceManager
Functions
int |
|
Object * |
|
Object * |
|
Object * |
|
Object * |
|
void |
|
bool |
|
Object * |
|
const State & |
|
const State & |
|
void |
|
void |
|
Object * |
|
void |
|
void |
|
bool |
|
void |
|
void * |
|
const String & |
|
void |
|
void * |
|
void |
|
void * |
|
void |
|
void * |
|
void |
|
bool |
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
- 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!
iShaderID – Shader 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 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.
