class RED::StreamingPolicy
Class that defines the actions to be taken while loading or saving a stream. More...
#include <REDStreamingPolicy.h>Inherits: Object.
Public functions:
Public static functions:
| static RED::CID | GetClassID ( ) |
Public enumerations:
| enum | COMP_AUTO { CPA_DONOTCOMPRESS = 0, CPA_RGBDXT1_RGBADXT1 = 1, CPA_RGBDXT1_RGBADXT3 = 2, CPA_RGBDXT1_RGBADXT5 = 3 } |
| enum | COMP_QUALITY { CPQ_LOSSLESS = 0, CPQ_LOSSY1 = 1, CPQ_LOSSY2 = 2 } |
| enum | DATA_KIND { DAK_NONE = 0, DAK_MATRIX = 1, DAK_IMAGE = 2, DAK_NORMALS = 3, DAK_TANGENTS = 4, DAK_TEXCOORD = 5, DAK_PROGRAMS = 6, DAK_INDICES = 7, DAK_VERTICES = 8 } |
| enum | UNKNOWN_CHUNK_POLICY { UCP_ABORT = 1, UCP_IGNORE = 2, UCP_ASK = 3 } |
Public typedefs:
| typedef RED_RC(* | UNKNOWN_CHUNK_CALLBACK )(RED::IStream &iStream, unsigned int iChunkSignature, RED::uint64 iChunkSize, void *iUserData) |
Private variables:
| COMP_AUTO | _autocompmode |
| DATA_KIND | _binding [RED::MCL_SIZE] |
| bool | _channel_write [RED::MCL_SIZE] |
| bool | _cpu_storage |
| RED::Map< const RED::Object *, bool > | _filter |
| bool | _forcehwimagedecomp |
| bool | _gpu_storage |
| RED::Map< unsigned int, RED::String > | _idtonames |
| bool | _localimages |
| bool | _material_write_mode |
| bool | _mtlctrlsave |
| bool | _recursive |
| RED::Map< DATA_KIND, unsigned int > | _settings |
| bool | _smartupdate |
| RED::String | _tracklabel |
| UNKNOWN_CHUNK_POLICY | _ucp |
| UNKNOWN_CHUNK_CALLBACK | _ucpcb |
| void * | _ucpcb_data |
Detailed description:
Class that defines the actions to be taken while loading or saving a stream.
The user may want to have a per-chunk control on how the data are streamed, i.e. are they compressed? what's the compression quality? how data are bound inside a mesh? The RED::StreamingPolicy enables the user to define how each data type must be streamed. A callback may even be defined that is called for each written chunk, letting the user decide on-the-fly what the policy must be.
The quality parameter of the compression is not meaningful for every kind of data. Here is a table that summarizes the incompatibilities between data types and compression settings:
| Data kind | Support compression | Compression quality |
|---|---|---|
| DAK_MATRIX | true | CPQ_LOSSLESS |
| DAK_IMAGE | true | CPQ_LOSSLESS, CPQ_LOSSY1, CPQ_LOSSY2 |
| DAK_NORMALS | true | CPQ_LOSSY1, CPQ_LOSSY2 |
| DAK_TANGENTS | true | CPQ_LOSSY1, CPQ_LOSSY2 |
| DAK_TEXCOORD | false | N/A |
| DAK_PROGRAMS | true | CPQ_LOSSLESS |
| DAK_TRIANGLES | true | CPQ_LOSSLESS |
| DAK_VERTICES | true | CPQ_LOSSLESS |
When an un-supported compression quality is chosen for a given data kind, no compression is performed.
By default, REDsdk expects the following default channels binding:
| Channel | Data kind |
|---|---|
| RED::MCL_VERTEX | DAK_VERTICES |
| RED::MCL_USER0 | DAK_TANGENTS |
| RED::MCL_NORMAL | DAK_NORMALS |
| RED::MCL_TEX0 | DAK_TEXCOORD |
| RED::MCL_TEX1 | DAK_TEXCOORD |
| RED::MCL_TEX2 | DAK_TEXCOORD |
| RED::MCL_TEX3 | DAK_TEXCOORD |
| RED::MCL_TEX4 | DAK_TEXCOORD |
| RED::MCL_TEX5 | DAK_TEXCOORD |
| RED::MCL_TEX6 | DAK_TEXCOORD |
| RED::MCL_TEX7 | DAK_TEXCOORD |
If your data doesn't meet this configuration, you need to inform REDsdk of your actual channels binding by calling RED::StreamingPolicy::SetChannelBinding for each of your channels.
See also Defining .red file policy.
Functions documentation
Constructor.
Destructor.
| public static RED::CID RED::StreamingPolicy::GetClassID | ( | ) |
Reimplements: RED::Object::GetClassID.
| public RED_RC RED::StreamingPolicy::AddToFilter | ( | const RED::Object * | iObject | ) |
Adds a RED::Object instance to the filter list.
All RED::Object instances lying in the filter list will not be streamed.
Adding the same instance more than once has no effect (i.e the instance will be filtered anyway).
Parameters:
| iObject: | Pointer to the instance being filtered. |
Returns:
| public virtual void * RED::StreamingPolicy::As | ( | const RED::CID & | iCID | ) |
Converts the object to an instance of the given type.
Parameters:
| iCID: | Requested class. |
Returns:
Reimplements: RED::Object::As.
| template< class T_As > public const T_As * RED::StreamingPolicy::As | ( | ) const |
Template version of the as const method.
Simply set T to be the class you want to retrieve an interface to.
Returns:
Reimplements: RED::Object::As.
| public virtual const void * RED::StreamingPolicy::As | ( | const RED::CID & | iCID | ) const |
Converts the object to an instance of the given type.
Parameters:
| iCID: | Requested class. |
Returns:
Reimplements: RED::Object::As.
| template< class T_As > public T_As * RED::StreamingPolicy::As | ( | ) |
Template version of the as method.
Simply set T to be the class you want to retrieve an interface to.
Returns:
Reimplements: RED::Object::As.
| public const RED::String & RED::StreamingPolicy::GetAnimationTrackLabel | ( | ) const |
Gets the user-defined label used in the naming of animation tracks.
Returns:
| public RED::StreamingPolicy::DATA_KIND RED::StreamingPolicy::GetChannelBinding | ( | RED::MESH_CHANNEL | iChannel | ) const |
Gets the type of the data bound to a given channel.
See RED::StreamingPolicy::SetChannelBinding for details on the data channel typing and the setup of compression.
Parameters:
| iChannel: | ID of the channel of interest. |
Returns:
| public bool RED::StreamingPolicy::GetChannelWriteMode | ( | RED::MESH_CHANNEL | iChannel | ) const |
Gets the write mode of a given data channel.
See RED::StreamingPolicy::SetChannelWriteMode for details on this operation.
Parameters:
| iChannel: | Channel identifier. |
Returns:
| public void RED::StreamingPolicy::GetCompression | ( | DATA_KIND | iData, |
| bool & | oEnabled, | ||
| COMP_QUALITY & | oQuality | ||
| ) | const |
Gets the compression settings for a given data type.
See the SetCompression method's documentation for details.
Parameters:
| iData: | Type of the data. |
| oEnabled: | Reference to the returned compression enabled flag. |
| oQuality: | Reference to the returned compression quality value. |
| public bool RED::StreamingPolicy::GetForceHWImageDecompression | ( | ) const |
Gets the status of the force hardware images decompression flag.
Returns:
| public void RED::StreamingPolicy::GetImagesStorage | ( | bool & | oGPUStorage, |
| bool & | oCPUStorage | ||
| ) | const |
Retrieve the current pixel storage mode for images.
See RED::StreamingPolicy::SetImagesStorage for details.
Parameters:
| oGPUStorage: | Current image data storage mode on the GPU. |
| oCPUStorage: | Current image data storage mode on the CPU. |
| public bool RED::StreamingPolicy::GetMaterialControllerAutoSaving | ( | ) const |
Gets the value of the material controllers automatic saving flag.
Returns:
| public bool RED::StreamingPolicy::GetSmartAnimatedShapeUpdate | ( | ) const |
Gets the value of the smart animated shapes saving flag.
See SetSmartAnimatedShapeUpdate for further details.
Returns:
| public const RED::String * RED::StreamingPolicy::GetStringFromID | ( | unsigned int | iID | ) const |
Reverts from an ID to a string.
This method works only if a valid FileInfo instance has been supplied to the GetAnimationTrackLabel method.
Parameters:
| iID: | ID to revert from. |
Returns:
| public COMP_AUTO RED::StreamingPolicy::GetUncompressedImageCompression | ( | ) const |
Gets the mode used for uncompressed images.
Returns:
| public void RED::StreamingPolicy::GetUnknownChunkPolicy | ( | UNKNOWN_CHUNK_POLICY & | oPolicy, |
| UNKNOWN_CHUNK_CALLBACK * | oCallback, | ||
| void ** | oUserData | ||
| ) | const |
Retrieves the current 'unknown chunk policy'.
Parameters:
| oPolicy: | reference to the returned policy. |
| oCallback: | pointer to the optional unknown chunk callback. |
| oUserData: | optional user data associated with the callback. |
| public bool RED::StreamingPolicy::IsFiltered | ( | const RED::Object * | iObject | ) const |
Checks if a given instance has been marked for filtering.
Parameters:
| iObject: | Pointer to the instance to be checked. |
Returns:
| public bool RED::StreamingPolicy::IsLocalImages | ( | ) const |
Returns the status of the local images option.
Returns:
| public bool RED::StreamingPolicy::IsMaterialWriteMode | ( | ) const |
Returns:
| public bool RED::StreamingPolicy::IsRecursivityEnabled | ( | ) const |
Returns the state of the recursiveness policy flag.
Returns:
| public void RED::StreamingPolicy::SetAnimationTrackLabel | ( | const RED::String & | iLabel, |
| const RED::Map< unsigned int, RED::String > & | iIDToNames | ||
| ) |
Sets the user label used to find animation tracks.
Animation tracks are automatically extracted from a DAG if the naming of the nodes follows this rule: each animation track root node must contain a user-defined string. This way, while exporting to a .red file, each time a node following that rule is met, a new animation track is built and exported.
The user-defined string must be declared to the streaming policy to avoid multiple exports of the same nodes during recursive parsing of the DAG.
Parameters:
| iLabel: | User-defined string that must be searched in every DAG node name. |
| iIDToNames: | Reference to the map needed to resolve IDs to names. |
| public void RED::StreamingPolicy::SetChannelBinding | ( | MESH_CHANNEL | iChannel, |
| DATA_KIND | iData | ||
| ) |
Sets the type of the data of a given mesh channel.
This method defines the type of data (e.g. the RED::StreamingPolicy::DATA_KIND) that will be considered for all 'iChannel' channels of all meshes. For instance, this method can be used to define that all RED::MCL_NORMAL channels in the scene graph to save are of the RED::StreamingPolicy::DAK_NORMALS type. Then, the RED::StreamingPolicy::SetCompression method can be used to define the way DAK_NORMALS data are to be compressed before being written to the stream.
Parameters:
| iChannel: | Channel identifier. |
| iData: | Data coded by the given channel. |
| public void RED::StreamingPolicy::SetChannelWriteMode | ( | RED::MESH_CHANNEL | iChannel, |
| bool | iOnOff | ||
| ) |
Sets whether mesh channels are written to the stream or not.
This method lets the caller define which data channels of a mesh can be streamed. By default, all data channels in a mesh or line or point are enabled for streaming. This method can be used to disable or enable the streaming of each data channel.
Parameters:
| iChannel: | Channel identifier. |
| iOnOff: | on to authorize the channel write, off to disable it. |
| public RED_RC RED::StreamingPolicy::SetCompression | ( | DATA_KIND | iData, |
| bool | iEnabled, | ||
| COMP_QUALITY | iQuality = CPQ_LOSSLESS | ||
| ) |
Sets the compression to be used for a given data type.
For example, if you want the matrices being compressed, call SetCompression( DAK_MATRIX, true ).
The quality parameter lets you define is the compression is lossless or not, and if not, how lossy it is.
The higher the quality the less the data are compressed. Maximum quality RED::StreamingPolicy::CPQ_LOSSLESS means compression with no loss in data.
Note that for images, the same compression must be enabled on saving AND on reloading the data for the policy to work, otherwise unexpected results can occur.
Parameters:
| iData: | Type of the data. |
| iEnabled: | true if the data lust be compressed, false otherwise. |
| iQuality: | Quality of the compression. Default is CPQ_LOSSLESS |
Returns:
RED_BAD_PARAM on an invalid combination of data kind, compression and quality settings.
| public void RED::StreamingPolicy::SetForceHWImageDecompression | ( | bool | iForce | ) |
Forces the decompression of all hardware-compressed images (i.e DXTx compressed images).
DXT image formats are patented and can not be handled without a compliant graphics card. When processing data for pure software rendering, it can be useful to force the DXT compressed images to be decompressed on-the-fly before sending them to the rendering unit.
This flag has no effect on loading of data but only on saving.
By default, this flag is set to false.
Parameters:
| iForce: | true to force decompression, false otherwise. |
| public RED_RC RED::StreamingPolicy::SetImagesStorage | ( | bool | iGPUStorage, |
| bool | iCPUStorage | ||
| ) |
Define pixel storage mode - GPU, CPU or both.
This policy controls how pixel data of images are actually stored by REDsdk. If REDsdk runs in hardware mode (see RED::OPTIONS_RAY_ENABLE_SOFT_TRACER), then images are stored on the GPU. If REDsdk runs in software mode, then images are stored on the CPU. If REDsdk runs in hybrid mode, by default, images are stored on both the GPU and the CPU. The application loading a .red file may decide that images that are loaded should be only stored on one or either memory, but not in both, to save resources.
Please note that the policy does not have any effect if REDsdk does not run in hybrid mode.
The CPU image storage is NOT the local storage of the image, which is another transient storage that can be used by images anytime. The CPU image storage is the memory zone where image pixels are stored by the engine.
Parameters:
| iGPUStorage: | Set to true (default) to allow image storage on the GPU. |
| iCPUStorage: | Set to true (default) to allow image storage on the CPU. |
Returns:
RED_BAD_PARAM if both iGPUStorage and iCPUStorage are false. One of the two must be true, otherwise images aren't stored anywhere!
| public void RED::StreamingPolicy::SetLocalImages | ( | bool | iEnabled = true | ) |
Enables/Disables the local storage of loaded images.
By default, operations on images are synchronous with the GPU, i.e creating or applying modifications to an image while the GPU is rendering will interrupt it. Enabling local storage avoids such interruptions. The data are read and stored in main CPU RAM instead of GPU RAM. It's up to the user to later force the loading of the images to the GPU RAM by calling any of the RED::IImage2D::SetPixels, RED::IImageCube::SetFacePixels or RED::IImage3D::SetPixels methods.
The local images policy also applies to image that are written to a stream. If the local images policy is enabled, then the image contents are sourced from the image local storage rather than from the normal image storage.
Parameters:
| iEnabled: | true to enable local storage for images, false otherwise. |
| public void RED::StreamingPolicy::SetMaterialControllerAutoSaving | ( | bool | iEnable = true | ) |
Sets the flag for automatic saving of the material controllers.
If the flag is set to true, each saved material will have its controller saved too (if any). Default value of the flag is true.
Parameters:
| iEnable: | Material controller auto-saving flag value. |
| public void RED::StreamingPolicy::SetMaterialWriteMode | ( | bool | iWriteMode | ) |
Sets the material writing policy for the streaming of scene graphs.
This policy can be used to disable the writing of materials in saved scene graphs. Any shape being saved will be either saved with its material (the default policy) or with NULL if the material writing policy is disabled.
This policy can be useful for the streaming of partial scene graph data when material data should not be saved. Streaming shapes with their materials imply the need to also stream the materials otherwise the file reloading will fail. This policy can change this behavior.
Parameters:
| iWriteMode: | The write mode for materials. |
| public void RED::StreamingPolicy::SetRecursivity | ( | bool | iEnabled = true | ) |
Sets the recursiveness policy.
For specific chunks like those implementing the RED::ITransformShape interface, recursive streaming may be needed to ensure that all the object's children are written to the stream too. If not, it is to the user responsibility to guarantee the graph coherence.
Parameters:
| iEnabled: | true to enable recursive streaming, false otherwise. Default is true (recursive) |
| public void RED::StreamingPolicy::SetSmartAnimatedShapeUpdate | ( | bool | iEnable = true | ) |
Sets the flag to activate smart animated shapes saving.
Animated shapes can lead to huge .red files when saved to disk. To avoid useless data to be written at each frame, one can set this flag to true to enable smart saving. In that case, only the changing data from frame to frame will be saved.
Parameters:
| iEnable: | smart animated shape update flag (default value for this flag is false). |
| public void RED::StreamingPolicy::SetUncompressedImageCompression | ( | COMP_AUTO | iMode | ) |
Sets the auto-compression of uncompressed images.
When loading uncompressed images from a .red file, you can choose to automatically compress the images in GPU memory or not. Default is CPA_DONOTCOMPRESS.
If you choose local image loading (by calling SetLocalImages(true)), the uncompressed images will be stored uncompressed (even if you cal SetUncompressedImageCompression with a different setting).
Parameters:
| iMode: | one of the COMP_AUTO enum entries. |
| public void RED::StreamingPolicy::SetUnknownChunkPolicy | ( | UNKNOWN_CHUNK_POLICY | iPolicy, |
| UNKNOWN_CHUNK_CALLBACK | iCallback = NULL, | ||
| void * | iUserData = NULL | ||
| ) |
Sets the loader policy to apply when loading unknown chunks.
By default, the policy applied is RED::StreamingPolicy::UCP_ABORT. If the user choose the UCP_ASK policy, he must provide a callback pointer. Otherwise, the method will return RED_BAD_PARAM.
Parameters:
| iPolicy: | Unknown chunk policy. |
| iCallback: | Optional pointer to a user callback. |
| iUserData: | Optional user data associated with the callback. |
Variables documentation
Auto-compression mode of uncompressed images.
List of channels binding.
List of write modes for each data channel.
CPU image data storage mode.
List of the objects to filter.
Force decompression of hardware images flag.
GPU image data storage mode.
Map needed to resolve node IDs when looking for an animation track pattern.
Status of the local images flag.
Write mode for materials of streamed shapes.
Auto-saving of the material controllers flag.
Status of the recursiveness flag.
Map of the data settings.
Smart animated shapes saving flag.
Label to be searched in every node name.
The unknown chunk policy to be applied.
Pointer to the unknown policy user callback.
Pointer to the user data associated to the unknown policy user callback.
Enumerations documentation
Defines the automatic image compression policy.
Enumerator:
| CPA_DONOTCOMPRESS | Leave the loaded images uncompressed. |
| CPA_RGBDXT1_RGBADXT1 | RGB images -> RGB_DXT1 images |
| CPA_RGBDXT1_RGBADXT3 | RGB images -> RGB_DXT1 images |
| CPA_RGBDXT1_RGBADXT5 | RGB images -> RGB_DXT1 images |
Defines the compression quality for streamable data.
Enumerator:
| CPQ_LOSSLESS | Lossless compression. |
| CPQ_LOSSY1 | Lossy compression (good quality of uncompressed data). |
| CPQ_LOSSY2 | Lossy compression (best compression ratio). |
Lists all types of streamable data types.
Enumerator:
| DAK_NONE | No data type. |
| DAK_MATRIX | Matrix data type. |
| DAK_IMAGE | Image data type. |
| DAK_NORMALS | Normals data type. |
| DAK_TANGENTS | Tangents data type. |
| DAK_TEXCOORD | Texture coordinates data type. |
| DAK_PROGRAMS | Shader programs data type. |
| DAK_INDICES | Triangles or lines indices data type. |
| DAK_VERTICES | Vertex coordinates data type. |
Lists all possibilities when facing an unknown chunk in a file.
Enumerator:
| UCP_ABORT | Abort file transcription when reading an unknown chunk (the default policy). |
| UCP_IGNORE | Ignore an unknown chunk found while reading a file. |
| UCP_ASK | Use the UnknownChunkCallback when an unknown chunk is found in a file. |
Types documentation
Prototype of the callback used to handle unknown chunks.
A .red file or data stream may contain user chunks that have a chunk signature that is not known to the engine or to the reading application. This callback is used along with the RED::UCP_ASK chunk handling policy and called for each chunk in the file that is not known to the engine.
The callback receives the 'iStream' data of the file, the signature of the chunk ('iChunkSignature') and its size ('iChunkSize') in bytes. Note that the chunk size does not include the chunk header size (signature + size = 12 bytes). The read/write cursor is set just after the chunk size field in the stream.
It must return RED_OK to resume loading or anything else to abort.
