The API to create runtime-loadable compression plugins. More...
#include <sys/types.h>#include <co/plugins/compressorTokens.h>#include <co/plugins/compressorTypes.h>
Include dependency graph for plugins/compressor.h:
This graph shows which files directly or indirectly include this file:
Go to the source code of this file.
Classes | |
| struct | EqCompressorInfo |
| Information about one compressor. More... | |
Defines | |
Compressor Plugin API Versioning | |
| #define | EQ_COMPRESSOR_VERSION 4 |
| The version of the Compressor API described by this header. | |
| #define | EQ_COMPRESSOR_VERSION_1 1 |
| At least version 1 of the Compressor API is described by this header. | |
| #define | EQ_COMPRESSOR_VERSION_2 1 |
| At least version 2 of the Compressor API is described by this header. | |
| #define | EQ_COMPRESSOR_VERSION_3 1 |
| At least version 3 of the Compressor API is described by this header. | |
| #define | EQ_COMPRESSOR_VERSION_4 1 |
| At least version 4 of the Compressor API is described by this header. | |
Compressor capability flags | |
Capability flags define what special features a compressor supports. They are queried from the DSO, and passed as input to certain functions to select a given capability of the plugin. | |
| #define | EQ_COMPRESSOR_INPLACE 0x1 |
| The compressor can (query time) or should (compress) write the compressed data in the same place as the uncompressed data. | |
| #define | EQ_COMPRESSOR_DATA_1D 0x2 |
| The compressor can handle linear data (query time), or the input data is linear (compress, decompress). | |
| #define | EQ_COMPRESSOR_DATA_2D 0x4 |
| The compressor can handle two-dimensional data (query time), or the input data is two-dimensional (compress, decompress). | |
| #define | EQ_COMPRESSOR_IGNORE_ALPHA 0x8 |
| The compressor can, does or should drop the alpha channel. | |
| #define | EQ_COMPRESSOR_IGNORE_MSE EQ_COMPRESSOR_IGNORE_ALPHA |
| Deprecated. | |
| #define | EQ_COMPRESSOR_CPU 0 |
| The compressor is a CPU compressor. | |
| #define | EQ_COMPRESSOR_TRANSFER 0x10 |
| The compressor is a CPU-GPU transfer engine. | |
| #define | EQ_COMPRESSOR_USE_TEXTURE_RECT 0x20 |
| Capability to use a GL_TEXTURE_RECTANGLE_ARB texture as source or destination. | |
| #define | EQ_COMPRESSOR_USE_TEXTURE_2D 0x80 |
| Capability to use a GL_TEXTURE_2D texture as source or destination. | |
| #define | EQ_COMPRESSOR_USE_FRAMEBUFFER 0x40 |
| Capability to use the frame buffer as source or destination. | |
| #define | EQ_COMPRESSOR_USE_ASYNC_DOWNLOAD 0x100 |
| Capability to use asynchronous downloads. | |
Functions | |
DSO information interface. | |
| EQ_PLUGIN_API size_t | EqCompressorGetNumCompressors () |
| EQ_PLUGIN_API void | EqCompressorGetInfo (const size_t n, EqCompressorInfo *const info) |
| Query information of the nth compressor in the DSO. | |
Compressor lifecycle management. | |
| EQ_PLUGIN_API void * | EqCompressorNewCompressor (const unsigned name) |
| Instantiate a new compressor or a new downloader. | |
| EQ_PLUGIN_API void | EqCompressorDeleteCompressor (void *const compressor) |
| Release a compressor or downloader instance. | |
| EQ_PLUGIN_API void * | EqCompressorNewDecompressor (const unsigned name) |
| Instantiate a new decompressor or a new uploader. | |
| EQ_PLUGIN_API void | EqCompressorDeleteDecompressor (void *const decompressor) |
| Release a decompressor instance. | |
CPU Compressor worker functions | |
| EQ_PLUGIN_API void | EqCompressorCompress (void *const compressor, const unsigned name, void *const in, const eq_uint64_t *inDims, const eq_uint64_t flags) |
| Compress data. | |
| EQ_PLUGIN_API unsigned | EqCompressorGetNumResults (void *const compressor, const unsigned name) |
| Return the number of results produced by the last compression. | |
| EQ_PLUGIN_API void | EqCompressorGetResult (void *const compressor, const unsigned name, const unsigned i, void **const out, eq_uint64_t *const outSize) |
| Return the ith result of the last compression. | |
| EQ_PLUGIN_API void | EqCompressorDecompress (void *const decompressor, const unsigned name, const void *const *in, const eq_uint64_t *const inSizes, const unsigned numInputs, void *const out, eq_uint64_t *const outDims, const eq_uint64_t flags) |
| Decompress data. | |
Transfer engine worker functions | |
| EQ_PLUGIN_API bool | EqCompressorIsCompatible (const unsigned name, const GLEWContext *glewContext) |
| Check if the compressor may be used with the current OpenGL context. | |
| EQ_PLUGIN_API void | EqCompressorDownload (void *const compressor, const unsigned name, const GLEWContext *glewContext, const eq_uint64_t inDims[4], const unsigned source, const eq_uint64_t flags, eq_uint64_t outDims[4], void **out) |
| Transfer frame buffer data into main memory. | |
| EQ_PLUGIN_API void | EqCompressorStartDownload (void *const compressor, const unsigned name, const GLEWContext *glewContext, const eq_uint64_t inDims[4], const unsigned source, const eq_uint64_t flags) |
| Start transferring frame buffer data into main memory. | |
| EQ_PLUGIN_API void | EqCompressorFinishDownload (void *const compressor, const unsigned name, const GLEWContext *glewContext, const eq_uint64_t inDims[4], const eq_uint64_t flags, eq_uint64_t outDims[4], void **out) |
| Finish transferring frame buffer data into main memory. | |
| EQ_PLUGIN_API void | EqCompressorUpload (void *const decompressor, const unsigned name, const GLEWContext *glewContext, const void *buffer, const eq_uint64_t inDims[4], const eq_uint64_t flags, const eq_uint64_t outDims[4], const unsigned destination) |
| Transfer data from main memory into GPU memory. | |
Detailed Description
The API to create runtime-loadable compression plugins.
The image compositing pipeline in Equalizer uses two types of plugins: transfer engines and CPU compressors. A transfer engine downloads and uploads the data from the GPU to main memory. A CPU compressor compresses and decompresses the data produced by a transfer engine. The chain of operations for an image transfer is:
- Select and instantiate transfer compressor for image to download
- Run the download operation from the render thread
- Select and instantiate a CPU compressor based on the transfer output token type
- Run the compress operation from the transmission thread
- Send the compressed data results to the receiving node(s)
- Instantiate a CPU decompressor
- Run the decompressor from the command thread
- Select and instantiate a transfer compressor based on the CPU decompressor token type
- Run the upload operation on each render thread
The operations 3 to 7 are omitted if the input and output frame are on the same node. The operations 3 to 7 are replaced by transmitting the output data of the download operation if no matching CPU compressor is found. Plugin instances are cached and reused for subsequent operations from the same thread.
To implement a compression plugin, the following steps are to be taken:
- Create a new shared library named EqualizerCompressorNAME.dll (Win32), libEqualizerCompressorNAME.dylib (Mac OS X) or libEqualizerCompressorNAME.so (Linux).
- Define EQ_PLUGIN_BUILD and then include eq/plugins/compressor.h (this header file).
- Implement all relevant C functions from this header file. All plugins have to implement EqCompressorGetNumCompressors, EqCompressorGetInfo, EqCompressorNewCompressor, EqCompressorNewDecompressor, EqCompressorDeleteCompressor and EqCompressorDeleteDecompressor. In addition, CPU compressors have to implement EqCompressorCompress, EqCompressorDecompress, EqCompressorGetNumResults and EqCompressorGetResult. Transfer plugins have to additionally implement EqCompressorIsCompatible, EqCompressorDownload and EqCompressorUpload. The default Equalizer compressors in src/lib/compressor may be used as a template.
- Put the library in the plugin search path (see eq::Global::getPluginDirectories(), defaults to EQ_PLUGIN_PATH or "/usr/local/share/Equalizer/plugins;.eqPlugins;$HOME/.eqPlugins;$PWD;$LD_LIBRARY_PATH".
- Run the image unit test (tests/image) to verify your plugin.
- Set the compression ratio and speed according to the output of the image unit test. Use the Equalizer RLE compressor as baseline.
- Request official names for your compressors.
Changes
Version 4
- Added support for asynchronous downloads
- Added functions: EqCompressorStartDownload, EqCompressorFinishDownload
- Added flag: EQ_COMPRESSOR_USE_ASYNC_DOWNLOAD
Version 3
- Added GPU-based compression during upload and download:
- Added functions: EqCompressorIsCompatible, EqCompressorDownload, EqCompressorUpload
- Added members in EqCompressorInfo: outputTokenType, outputTokenSize
- Added flags: EQ_COMPRESSOR_CPU, EQ_COMPRESSOR_TRANSFER, EQ_COMPRESSOR_USE_TEXTURE_2D, EQ_COMPRESSOR_USE_TEXTURE_RECT, EQ_COMPRESSOR_USE_FRAMEBUFFER
- Added data types: EQ_COMPRESSOR_DATATYPE_INVALID, EQ_COMPRESSOR_DATATYPE_RGBA_UNSIGNED_BYTE, EQ_COMPRESSOR_DATATYPE_RGBA_UNSIGNED_INT_8_8_8_8_REV, EQ_COMPRESSOR_DATATYPE_RGBA_UNSIGNED_INT_10_10_10_2, EQ_COMPRESSOR_DATATYPE_RGBA_HALF_FLOAT, EQ_COMPRESSOR_DATATYPE_RGBA_FLOAT, EQ_COMPRESSOR_DATATYPE_BGRA_UNSIGNED_BYTE, EQ_COMPRESSOR_DATATYPE_BGRA_UNSIGNED_INT_8_8_8_8_REV, EQ_COMPRESSOR_DATATYPE_BGRA_UNSIGNED_INT_10_10_10_2, EQ_COMPRESSOR_DATATYPE_BGRA_HALF_FLOAT, EQ_COMPRESSOR_DATATYPE_BGRA_FLOAT, EQ_COMPRESSOR_DATATYPE_DEPTH_UNSIGNED_FLOAT, EQ_COMPRESSOR_DATATYPE_DEPTH_UNSIGNED_INT, EQ_COMPRESSOR_DATATYPE_DEPTH_UNSIGNED_INT_24_8_NV, EQ_COMPRESSOR_DATATYPE_RGB_UNSIGNED_BYTE, EQ_COMPRESSOR_DATATYPE_RGB_HALF_FLOAT, EQ_COMPRESSOR_DATATYPE_RGB_FLOAT, EQ_COMPRESSOR_DATATYPE_BGR_UNSIGNED_BYTE, EQ_COMPRESSOR_DATATYPE_BGR_HALF_FLOAT, EQ_COMPRESSOR_DATATYPE_BGR_FLOAT
- Added compressor type names: EQ_COMPRESSOR_DIFF_RLE_YUVA_50P, EQ_COMPRESSOR_RLE_YUVA_50P, EQ_COMPRESSOR_TRANSFER_RGBA_TO_RGBA, EQ_COMPRESSOR_TRANSFER_RGBA_TO_BGRA, EQ_COMPRESSOR_TRANSFER_RGBA_TO_RGBA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_TRANSFER_RGBA_TO_BGRA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_TRANSFER_RGB10A2_TO_RGB10A2, EQ_COMPRESSOR_TRANSFER_RGB10A2_TO_BGR10A2, EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_RGBA16F, EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_BGRA16F, EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_RGBA32F, EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_BGRA32F, EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_BGRA_25P, EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_RGBA_25P, EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_BGRA16F_50P, EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_RGBA16F_50P, EQ_COMPRESSOR_TRANSFER_RGBA_TO_YUVA_50P, EQ_COMPRESSOR_TRANSFER_RGB_TO_RGB, EQ_COMPRESSOR_TRANSFER_RGB_TO_BGR, EQ_COMPRESSOR_TRANSFER_RGB16F_TO_RGB16F, EQ_COMPRESSOR_TRANSFER_RGB16F_TO_BGR16F, EQ_COMPRESSOR_TRANSFER_RGB32F_TO_RGB32F, EQ_COMPRESSOR_TRANSFER_RGB32F_TO_BGR32F, EQ_COMPRESSOR_TRANSFER_RGB32F_TO_RGB_25P, EQ_COMPRESSOR_TRANSFER_RGB32F_TO_BGR_25P, EQ_COMPRESSOR_TRANSFER_RGB32F_TO_BGR16F_50P, EQ_COMPRESSOR_TRANSFER_RGB32F_TO_RGB16F_50P, EQ_COMPRESSOR_TRANSFER_RGB16F_TO_RGB_50P, EQ_COMPRESSOR_TRANSFER_RGB16F_TO_BGR_50P, EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_RGBA_50P, EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_BGRA_50P, EQ_COMPRESSOR_TRANSFER_DEPTH_TO_DEPTH_UNSIGNED_INT, EQ_COMPRESSOR_DIFF_RLE_RGBA, EQ_COMPRESSOR_DIFF_RLE_BGRA, EQ_COMPRESSOR_DIFF_RLE_RGBA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_DIFF_RLE_BGRA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_DIFF_RLE_RGB10_A2, EQ_COMPRESSOR_DIFF_RLE_BGR10_A2, EQ_COMPRESSOR_DIFF_RLE_RGB, EQ_COMPRESSOR_DIFF_RLE_BGR, EQ_COMPRESSOR_DIFF_RLE_DEPTH_UNSIGNED_INT, EQ_COMPRESSOR_RLE_RGBA16F, EQ_COMPRESSOR_RLE_BGRA16F, EQ_COMPRESSOR_DIFF_RLE_RGBA16F, EQ_COMPRESSOR_DIFF_RLE_BGRA16F, EQ_COMPRESSOR_DIFF_RLE_565_RGBA, EQ_COMPRESSOR_DIFF_RLE_565_BGRA, EQ_COMPRESSOR_DIFF_RLE_565_RGBA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_DIFF_RLE_565_BGRA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_DIFF_RLE_565_RGB10_A2, EQ_COMPRESSOR_DIFF_RLE_565_BGR10_A2, EQ_COMPRESSOR_RLE_RGBA, EQ_COMPRESSOR_RLE_BGRA, EQ_COMPRESSOR_RLE_RGBA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_RLE_BGRA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_RLE_RGB10_A2, EQ_COMPRESSOR_RLE_BGR10_A2, EQ_COMPRESSOR_RLE_RGB, EQ_COMPRESSOR_RLE_BGR, EQ_COMPRESSOR_RLE_DEPTH_UNSIGNED_INT, EQ_COMPRESSOR_AG_RTT_JPEG_HQ, EQ_COMPRESSOR_AG_RTT_JPEG_MQ, EQ_COMPRESSOR_AG_RTT_JPEG_LQ
Version 2
- Added EQ_COMPRESSOR_DIFF_RLE_565 to type name registry
- Added EQ_COMPRESSOR_DIFF_RLE_10A2 to type name registry
- Added EQ_COMPRESSOR_DATATYPE_RGB10_A2 to token list
Version 1
- Initial Release
Definition in file plugins/compressor.h.
Define Documentation
| #define EQ_COMPRESSOR_CPU 0 |
The compressor is a CPU compressor.
CPU compressors implement data compression and decompression of a block of memory.
Definition at line 264 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_DATA_1D 0x2 |
The compressor can handle linear data (query time), or the input data is linear (compress, decompress).
Typically used for binary data.
Definition at line 229 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_DATA_2D 0x4 |
The compressor can handle two-dimensional data (query time), or the input data is two-dimensional (compress, decompress).
Typically used for image data.
Definition at line 236 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_IGNORE_ALPHA 0x8 |
The compressor can, does or should drop the alpha channel.
The plugin sets this flag during information time to indicate that it will drop the alpha channel (transfer plugins) or can drop the alpha channel (compressor plugins).
During download, the flag will always be set if it was set at query time. During compression, it will be set only if the alpha channel should be dropped. It will never be set for plugins which did not indicate this capability.
For compression plugins it is assumed that setting this flag improves the compression ratio by 25 percent. For transfer plugins, it is assumed that the ratio already includes the alpha reduction.
Definition at line 254 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_TRANSFER 0x10 |
The compressor is a CPU-GPU transfer engine.
GPU compressors implement the download from a GPU framebuffer or texture to main memory, as well as the corresponding upload. During this operation, compression might take place.
Definition at line 272 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_USE_ASYNC_DOWNLOAD 0x100 |
Capability to use asynchronous downloads.
If set, the transfer engine will (query time) or shall (download time) use asynchronous downloads.
- Version:
- 4
Definition at line 302 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_USE_FRAMEBUFFER 0x40 |
Capability to use the frame buffer as source or destination.
If set, the transfer engine can (query time) or shall (compress time) use the frame buffer as the source or destination for its operations.
Definition at line 294 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_USE_TEXTURE_2D 0x80 |
Capability to use a GL_TEXTURE_2D texture as source or destination.
If set, the transfer engine can (query time) or shall (compress time) use a 2D texture as the source or destination for its operations.
Definition at line 287 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_USE_TEXTURE_RECT 0x20 |
Capability to use a GL_TEXTURE_RECTANGLE_ARB texture as source or destination.
If set, the transfer engine can (query time) or shall (compress time) use a rectangular texture as the source or destination for its operations.
Definition at line 280 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_VERSION 4 |
The version of the Compressor API described by this header.
Definition at line 192 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_VERSION_1 1 |
At least version 1 of the Compressor API is described by this header.
Definition at line 194 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_VERSION_2 1 |
At least version 2 of the Compressor API is described by this header.
Definition at line 196 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_VERSION_3 1 |
At least version 3 of the Compressor API is described by this header.
Definition at line 198 of file plugins/compressor.h.
| #define EQ_COMPRESSOR_VERSION_4 1 |
At least version 4 of the Compressor API is described by this header.
Definition at line 200 of file plugins/compressor.h.
Function Documentation
| EQ_PLUGIN_API void EqCompressorCompress | ( | void *const | compressor, |
| const unsigned | name, | ||
| void *const | in, | ||
| const eq_uint64_t * | inDims, | ||
| const eq_uint64_t | flags | ||
| ) |
Compress data.
The number of dimensions in the input and output data is given as a flag. The input dimensions give an offset and a size for each dimension in the format dim0_offset, dim0_size, dim1_offset, ..., dimN_size. The offset does not apply to the input pointer, it is merely a hint on where the data is positioned, e.g., where a 2D image is positioned in a virtual framebuffer. The size of the input data is mul( inDims[1,3,...,n] ) * sizeof( info->dataType ).
The compressor has to store the results internally in its instance data. The result of the compression run will be queried later. Results of previous compression do not have to be retained, i.e., they can be overwritten on subsequent compression runs.
- Parameters:
-
compressor the compressor instance. name the type name of the compressor. in the pointer to the input data. inDims the dimensions of the input data. flags capability flags for the compression.
- Version:
- 1
| EQ_PLUGIN_API void EqCompressorDecompress | ( | void *const | decompressor, |
| const unsigned | name, | ||
| const void *const * | in, | ||
| const eq_uint64_t *const | inSizes, | ||
| const unsigned | numInputs, | ||
| void *const | out, | ||
| eq_uint64_t *const | outDims, | ||
| const eq_uint64_t | flags | ||
| ) |
Decompress data.
The decompressor gets all result pointers as produced by the compressor as input. The routine should use the output buffer fully. For dimensions and output size see EqCompressorCompress.
- Parameters:
-
decompressor the decompressor instance, can be 0. name the type name of the decompressor. in the pointer to an array of input data pointers. inSizes the array of input data sizes in bytes. numInputs the number of input data elements. out the pointer to a pre-allocated buffer for the uncompressed output result. outDims the dimensions of the output data. flags capability flags for the decompression.
- See also:
- EqCompressorCompress
- Version:
- 1
- Note:
- outDims should be const, which was an oversight
| EQ_PLUGIN_API void EqCompressorDeleteCompressor | ( | void *const | compressor | ) |
Release a compressor or downloader instance.
- Parameters:
-
compressor the compressor instance to free.
- Version:
- 1
| EQ_PLUGIN_API void EqCompressorDeleteDecompressor | ( | void *const | decompressor | ) |
Release a decompressor instance.
- Parameters:
-
decompressor the decompressor instance to free.
- Version:
- 1
| EQ_PLUGIN_API void EqCompressorDownload | ( | void *const | compressor, |
| const unsigned | name, | ||
| const GLEWContext * | glewContext, | ||
| const eq_uint64_t | inDims[4], | ||
| const unsigned | source, | ||
| const eq_uint64_t | flags, | ||
| eq_uint64_t | outDims[4], | ||
| void ** | out | ||
| ) |
Transfer frame buffer data into main memory.
This function has to transfer the specified frame buffer region or texture from the GPU memory into main memory. In the process, a transformation (including compression) of the data may take place. The result buffer has to be allocated by the compressor. The buffer has to be valied until the next call to this function or the destruction of this instance.
The correct SystemWindow is current, e.g., the OpenGL context is current and the frame buffer is bound correctly. The format and type of the input frame buffer are determined indirectly by the information provided by the plugin for the given compressor name, that is, the plugin has pre-declared the frame buffer type it processes during EqCompressorGetInfo().
The OpenGL context has been setup using Compositor::setupAssemblyState() using the channel's pvp. If the OpenGL state is modified by this function, it has to reset it before leaving.
The pointer and data size is returned using the out parameters. The outDims parameter has the format x, w, y, h. If the compressor produces an image (structured data), the outDims should be set to a multiple of inDims. For unstructured data the values should be set to x = 0, w = num_elements, y = 0, h = 1. The output pointer has to be valid until the next call to this function using the same compressor instance.
Flags will always contain EQ_COMPRESSOR_DATA_2D, and may contain:
- EQ_COMPRESSOR_IGNORE_ALPHA if the alpha value of a color buffer may be dropped during download
- EQ_COMPRESSOR_USE_TEXTURE_2D if the source is a 2D texture ID
- EQ_COMPRESSOR_USE_TEXTURE_RECT if the source is a rectangle texture ID
- EQ_COMPRESSOR_USE_FRAMEBUFFER if the source is an OpenGL frame buffer
- Parameters:
-
compressor the compressor instance. name the type name of the compressor. glewContext the initialized GLEW context describing corresponding to the current OpenGL context. inDims the dimensions of the input data (x, w, y, h). source texture name, if EQ_COMPRESSOR_USE_TEXTURE_2D or EQ_COMPRESSOR_USE_TEXTURE_RECT is set. flags capability flags for the compression (see description). outDims the dimensions of the output data (see description). out the pointer to the output data.
- Version:
- 3
| EQ_PLUGIN_API void EqCompressorFinishDownload | ( | void *const | compressor, |
| const unsigned | name, | ||
| const GLEWContext * | glewContext, | ||
| const eq_uint64_t | inDims[4], | ||
| const eq_uint64_t | flags, | ||
| eq_uint64_t | outDims[4], | ||
| void ** | out | ||
| ) |
Finish transferring frame buffer data into main memory.
Finish an operation started using EqCompressorStartDownload(). The correct SystemWindow is current, e.g., a shared OpenGL context is current and the frame buffer is bound correctly. No OpenGL context setup is done.
- Parameters:
-
compressor the compressor instance. name the type name of the compressor. glewContext the initialized GLEW context describing corresponding to the current OpenGL context. inDims the dimensions of the input data (x, w, y, h). flags capability flags for the compression (see description). outDims the dimensions of the output data (see description). out the pointer to the output data.
- Version:
- 4
| EQ_PLUGIN_API void EqCompressorGetInfo | ( | const size_t | n, |
| EqCompressorInfo *const | info | ||
| ) |
Query information of the nth compressor in the DSO.
Plugins aiming to be backward-compatible, i.e., usable in older version than the one compiled against, have to carefully check the provided runtime version in info. If they implement features incompatible with older Equalizer versions, e.g., a CPU compressor with an outputTokenType different from tokenType, they either have to implement a compatibility code path or to disable the compressor by setting the tokenType to EQ_COMPRESSOR_DATATYPE_INVALID.
- Version:
- 1
| EQ_PLUGIN_API size_t EqCompressorGetNumCompressors | ( | ) |
- Returns:
- the number of compressors implemented in the DSO.
- Version:
- 1
| EQ_PLUGIN_API unsigned EqCompressorGetNumResults | ( | void *const | compressor, |
| const unsigned | name | ||
| ) |
Return the number of results produced by the last compression.
A compressor might generate multiple output stream, e.g., when operating on structured data or using parallel compression routines.
- Parameters:
-
compressor the compressor instance. name the type name of the compressor.
- Returns:
- the number of output results.
- Version:
- 1
| EQ_PLUGIN_API void EqCompressorGetResult | ( | void *const | compressor, |
| const unsigned | name, | ||
| const unsigned | i, | ||
| void **const | out, | ||
| eq_uint64_t *const | outSize | ||
| ) |
Return the ith result of the last compression.
- Parameters:
-
compressor the compressor instance. name the type name of the compressor. i the result index to return. out the return value to store the result pointer. outSize the return value to store the result size in bytes.
- Version:
- 1
| EQ_PLUGIN_API bool EqCompressorIsCompatible | ( | const unsigned | name, |
| const GLEWContext * | glewContext | ||
| ) |
Check if the compressor may be used with the current OpenGL context.
The OpenGL context is current, and has not be modified by this function. The given glewContext is an initialized GLEWContext corresponding to the OpenGL context. Typically this function checks for a given OpenGL version and/or extension required by the transfer engine.
- Parameters:
-
name the type name of the compressor. glewContext the initialized GLEW context describing corresponding to the current OpenGL context.
- Returns:
- true if the compressor is compatible with the environment.
- Version:
- 3
| EQ_PLUGIN_API void* EqCompressorNewCompressor | ( | const unsigned | name | ) |
Instantiate a new compressor or a new downloader.
This function has to create a new instance of the given compressor type. Multiple instances might be used concurrently. One given instance is always used from one thread at any given time.
For one given name, there can only be one given implementation of a compressor or downloader. This type has been given by the plugin during getInfo.
- Parameters:
-
name the type name of the compressor.
- Returns:
- an opaque pointer to the compressor instance.
- Version:
- 1
| EQ_PLUGIN_API void* EqCompressorNewDecompressor | ( | const unsigned | name | ) |
Instantiate a new decompressor or a new uploader.
This function might create a new instance of the given decompressor type. Multiple instances might be used concurrently. One given instance is always used from one thread at any given time. State-less decompressors might return 0.
- Parameters:
-
name the type name of the decompressor.
- Returns:
- an opaque pointer to the decompressor instance, or 0 if no instance is needed by the implementation.
- Version:
- 1
| EQ_PLUGIN_API void EqCompressorStartDownload | ( | void *const | compressor, |
| const unsigned | name, | ||
| const GLEWContext * | glewContext, | ||
| const eq_uint64_t | inDims[4], | ||
| const unsigned | source, | ||
| const eq_uint64_t | flags | ||
| ) |
Start transferring frame buffer data into main memory.
When a plugin indicates that it supports asynchronous downloads during query time, this function will be set by Equalizer versions supporting async downloads. This function should then initiate the download using the given input parameters, which behave exactly as described in EqCompressorDownload. The operation will be completed from another thread using EqCompressorFinishDownload().
Older Equalizer versions will call EqCompressorDownload(), which should also be implemented by plugins using EqCompressorStartDownload() and EqCompressorFinishDownload() to perform a synchronous readback.
- Parameters:
-
compressor the compressor instance. name the type name of the compressor. glewContext the initialized GLEW context describing corresponding to the current OpenGL context. inDims the dimensions of the input data (x, w, y, h). source texture name, if EQ_COMPRESSOR_USE_TEXTURE_2D or EQ_COMPRESSOR_USE_TEXTURE_RECT is set. flags capability flags for the compression (see description).
- Version:
- 4
| EQ_PLUGIN_API void EqCompressorUpload | ( | void *const | decompressor, |
| const unsigned | name, | ||
| const GLEWContext * | glewContext, | ||
| const void * | buffer, | ||
| const eq_uint64_t | inDims[4], | ||
| const eq_uint64_t | flags, | ||
| const eq_uint64_t | outDims[4], | ||
| const unsigned | destination | ||
| ) |
Transfer data from main memory into GPU memory.
This function applies the inverse operation of EqCompressorDownload, that is, it transfers the specified buffer into the GPU. It may apply a transformation, including decompression, during its operation. At the end, the result must be located in the frame buffer or the provided texture.
The correct OpenGL context is current. The texture is initialized to the size provided by inDims and it is not bound. The OpenGL context has been setup using Compositor::setupAssemblyState() using the channel pvp. If the OpenGL state is modified by this function, it has to reset it before leaving.
The parameters buffer, inDims, flags will contain the same values as the parameters out, outDims, flags of the corresponding EqCompressorDownload() call. Please refer to the documentation of this function for further information.
Flags will always contain EQ_COMPRESSOR_DATA_2D, and may contain:
- EQ_COMPRESSOR_IGNORE_ALPHA if the alpha value of a color buffer may be dropped during upload
- EQ_COMPRESSOR_USE_TEXTURE_2D if the destination is a 2D texture ID
- EQ_COMPRESSOR_USE_TEXTURE_RECT if the destination is a rectancle texture ID
- EQ_COMPRESSOR_USE_FRAMEBUFFER if the destination is an OpenGL frame buffer
- Parameters:
-
decompressor the compressor instance. name the type name of the compressor. glewContext the initialized GLEW context corresponding to the current OpenGL context. buffer the input data. inDims the dimension of the input data. flags capability flags for the compression. outDims the result data size in the frame buffer. destination the destination texture name if EQ_COMPRESSOR_USE_TEXTURE_2D or EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
- Version:
- 3
