StreamingPolicy
Types
Type Aliases
|
Fields
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Functions
|
|
void |
|
void |
|
bool |
|
void |
|
void |
|
bool |
|
void |
|
bool |
|
void |
|
bool |
|
void |
|
bool |
|
void |
|
bool |
|
void |
|
const String & |
|
const String * |
|
void |
|
void |
|
bool |
|
void |
|
bool |
|
void |
|
void |
Detailed Description
-
class StreamingPolicy : public RED::Object
Class that defines the actions to be taken while loading or saving a stream.
@related The .red File Format, Defining .red File Policy , class RED::IStream, class RED::IREDFile
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
DAK_VERTICES
DAK_TANGENTS
DAK_NORMALS
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 \ref tk_defining_red_file_policy.
Public Types
-
enum DATA_KIND
Lists all types of streamable data types.
Values:
-
enumerator DAK_NONE
No data type.
-
enumerator DAK_IMAGE
Image data type.
-
enumerator DAK_NORMALS
Normals data type.
-
enumerator DAK_TANGENTS
Tangents data type.
-
enumerator DAK_TEXCOORD
Texture coordinates data type.
-
enumerator DAK_INDICES
Triangles or lines indices data type.
-
enumerator DAK_VERTICES
Vertex coordinates data type.
-
enumerator DAK_NONE
-
enum COMP_QUALITY
Defines the compression quality for streamable data.
Values:
-
enumerator CPQ_LOSSLESS
Lossless compression.
-
enumerator CPQ_LOSSY1
Lossy compression (good quality of uncompressed data).
-
enumerator CPQ_LOSSY2
Lossy compression (best compression ratio).
-
enumerator CPQ_LOSSLESS
-
enum COMP_AUTO
Defines the automatic image compression policy.
Values:
-
enumerator CPA_DONOTCOMPRESS
Leave the loaded images uncompressed.
-
enumerator CPA_RGBDXT1_RGBADXT1
RGB images -> RGB_DXT1 images
RGBA images -> RGBA_DXT1 images.
-
enumerator CPA_RGBDXT1_RGBADXT3
RGB images -> RGB_DXT1 images
RGBA images -> RGBA_DXT3 images.
-
enumerator CPA_RGBDXT1_RGBADXT5
RGB images -> RGB_DXT1 images
RGBA images -> RGBA_DXT5 images.
-
enumerator CPA_DONOTCOMPRESS
-
enum UNKNOWN_CHUNK_POLICY
Lists all possibilities when facing an unknown chunk in a file.
Values:
-
enumerator UCP_ABORT
Abort file transcription when reading an unknown chunk (the default policy).
-
enumerator UCP_IGNORE
Ignore an unknown chunk found while reading a file.
-
enumerator UCP_ASK
Use the UnknownChunkCallback when an unknown chunk is found in a file.
-
enumerator UCP_ABORT
-
typedef RED_RC (*UNKNOWN_CHUNK_CALLBACK)(RED::IStream &iStream, unsigned int iChunkSignature, RED::uint64 iChunkSize, void *iUserData)
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.
Public Functions
- SET_CID (CID_class_REDStreamingPolicy) IMPLEMENT_AS()
-
StreamingPolicy()
Constructor.
-
~StreamingPolicy()
Destructor.
-
RED_RC 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_OK on success,
RED_BAD_PARAM on an invalid combination of data kind, compression and quality settings.
-
void 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.
-
inline void 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.
-
inline bool GetForceHWImageDecompression() const
Gets the status of the force hardware images decompression flag.
- Returns
the flag value.
-
void 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.
-
RED::StreamingPolicy::DATA_KIND 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
the kind of the data bound to the given channel.
-
void 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.
-
bool 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
on if the channel can be written to the stream, off if not.
-
inline void 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)
-
inline bool IsRecursivityEnabled() const
Returns the state of the recursiveness policy flag.
- Returns
true if the recursiveness is enabled, false otherwise.
-
inline void 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.
-
inline bool IsMaterialWriteMode() const
- Returns
true if the material write mode is enabled for streamed shapes.
-
inline void 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.
-
inline bool IsLocalImages() const
Returns the status of the local images option.
- Returns
true if local storage of images is enabled, false otherwise.
-
RED_RC 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_OK if the operation has succeeded,
RED_BAD_PARAM if both iGPUStorage and iCPUStorage are false. One of the two must be true, otherwise images aren’t stored anywhere!
-
inline void 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.
-
RED_RC 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
RED_OK on success,
RED_ALLOC_FAILURE on a memory allocation error,
RED_FAIL otherwise.
-
inline bool 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
true if the instance is in the filter list, false otherwise.
-
inline void 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.
-
inline const RED::String &GetAnimationTrackLabel() const
Gets the user-defined label used in the naming of animation tracks.
- Returns
The user-defined label used in the naming of animation tracks.
-
inline const RED::String *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
A pointer to the string corresponding to a given ID on success, NULL otherwise.
-
inline void 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).
@param iMode: one of the COMP_AUTO enum entries.
-
inline COMP_AUTO GetUncompressedImageCompression() const
Gets the mode used for uncompressed images.
- Returns
the mode of compression used for loaded images that are not compressed.
-
inline void 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.
-
inline bool GetMaterialControllerAutoSaving() const
Gets the value of the material controllers automatic saving flag.
- Returns
the value of the material controllers automatic saving flag.
-
inline void 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).
-
inline bool GetSmartAnimatedShapeUpdate() const
Gets the value of the smart animated shapes saving flag.
See SetSmartAnimatedShapeUpdate for further details.
- Returns
the value of the smart animated shapes saving flag.
-
inline void 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.
-
inline void 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.
-
enum DATA_KIND
