Equalizer  1.4.1
Classes
plugins/compressor.h File Reference

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:

  1. Select and instantiate transfer compressor for image to download
  2. Run the download operation from the render thread
  3. Select and instantiate a CPU compressor based on the transfer output token type
  4. Run the compress operation from the transmission thread
  5. Send the compressed data results to the receiving node(s)
  6. Instantiate a CPU decompressor
  7. Run the decompressor from the command thread
  8. Select and instantiate a transfer compressor based on the CPU decompressor token type
  9. 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:

See also:
plugins/compressorTypes.h, plugins/compressorTokens.h

Changes

Version 4

Version 3

Version 2

Version 1

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:
compressorthe compressor instance.
namethe type name of the compressor.
inthe pointer to the input data.
inDimsthe dimensions of the input data.
flagscapability 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:
decompressorthe decompressor instance, can be 0.
namethe type name of the decompressor.
inthe pointer to an array of input data pointers.
inSizesthe array of input data sizes in bytes.
numInputsthe number of input data elements.
outthe pointer to a pre-allocated buffer for the uncompressed output result.
outDimsthe dimensions of the output data.
flagscapability 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:
compressorthe compressor instance to free.
Version:
1
EQ_PLUGIN_API void EqCompressorDeleteDecompressor ( void *const  decompressor)

Release a decompressor instance.

Parameters:
decompressorthe 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:
compressorthe compressor instance.
namethe type name of the compressor.
glewContextthe initialized GLEW context describing corresponding to the current OpenGL context.
inDimsthe dimensions of the input data (x, w, y, h).
sourcetexture name, if EQ_COMPRESSOR_USE_TEXTURE_2D or EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
flagscapability flags for the compression (see description).
outDimsthe dimensions of the output data (see description).
outthe 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:
compressorthe compressor instance.
namethe type name of the compressor.
glewContextthe initialized GLEW context describing corresponding to the current OpenGL context.
inDimsthe dimensions of the input data (x, w, y, h).
flagscapability flags for the compression (see description).
outDimsthe dimensions of the output data (see description).
outthe 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:
compressorthe compressor instance.
namethe 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:
compressorthe compressor instance.
namethe type name of the compressor.
ithe result index to return.
outthe return value to store the result pointer.
outSizethe 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:
namethe type name of the compressor.
glewContextthe 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:
namethe 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:
namethe 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:
compressorthe compressor instance.
namethe type name of the compressor.
glewContextthe initialized GLEW context describing corresponding to the current OpenGL context.
inDimsthe dimensions of the input data (x, w, y, h).
sourcetexture name, if EQ_COMPRESSOR_USE_TEXTURE_2D or EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
flagscapability 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:
decompressorthe compressor instance.
namethe type name of the compressor.
glewContextthe initialized GLEW context corresponding to the current OpenGL context.
bufferthe input data.
inDimsthe dimension of the input data.
flagscapability flags for the compression.
outDimsthe result data size in the frame buffer.
destinationthe destination texture name if EQ_COMPRESSOR_USE_TEXTURE_2D or EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
Version:
3
Generated on Mon Nov 26 2012 14:41:50 for Equalizer 1.4.1 by  doxygen 1.7.6.1