StreamingPolicy

Fields

DAK_NONE
DAK_MATRIX
DAK_IMAGE
DAK_NORMALS
DAK_TANGENTS
DAK_TEXCOORD
DAK_PROGRAMS
DAK_INDICES
DAK_VERTICES
CPQ_LOSSLESS
CPQ_LOSSY1
CPQ_LOSSY2
CPA_DONOTCOMPRESS
CPA_RGBDXT1_RGBADXT1
CPA_RGBDXT1_RGBADXT3
CPA_RGBDXT1_RGBADXT5
UCP_ABORT
UCP_IGNORE
UCP_ASK

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
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 \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_MATRIX

Matrix 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_PROGRAMS

Shader programs data type.

enumerator DAK_INDICES

Triangles or lines indices data type.

enumerator DAK_VERTICES

Vertex coordinates data type.

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).

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.

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.

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.