LCOV - code coverage report
Current view: top level - lunchbox/plugins - compressor.h (source / functions) Hit Total Coverage
Test: lcov2.info Lines: 1 7 14.3 %
Date: 2014-08-05 Functions: 1 2 50.0 %

          Line data    Source code
       1             : 
       2             : /* Copyright (c) 2009-2010, Cedric Stalder <cedric.stalder@gmail.com>
       3             :  *               2009-2012, Stefan Eilemann <eile@equalizergraphics.com>
       4             :  *
       5             :  * This library is free software; you can redistribute it and/or modify it under
       6             :  * the terms of the GNU Lesser General Public License version 2.1 as published
       7             :  * by the Free Software Foundation.
       8             :  *
       9             :  * This library is distributed in the hope that it will be useful, but WITHOUT
      10             :  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
      11             :  * FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
      12             :  * details.
      13             :  *
      14             :  * You should have received a copy of the GNU Lesser General Public License
      15             :  * along with this library; if not, write to the Free Software Foundation, Inc.,
      16             :  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
      17             :  */
      18             : 
      19             : /**
      20             :  * @file plugins/compressor.h
      21             :  *
      22             :  * The API to create runtime-loadable compression plugins.
      23             :  *
      24             :  * The image compositing pipeline in Equalizer uses two types of plugins:
      25             :  * transfer engines and CPU compressors. A transfer engine downloads and uploads
      26             :  * the data from the GPU to main memory. A CPU compressor compresses and
      27             :  * decompresses the data produced by a transfer engine. The chain of operations
      28             :  * for an image transfer is:
      29             :  *  -# Select and instantiate transfer compressor for image to download
      30             :  *  -# Run the download operation from the render thread
      31             :  *  -# Select and instantiate a CPU compressor based on the transfer output
      32             :  *     token type
      33             :  *  -# Run the compress operation from the transmission thread
      34             :  *  -# Send the compressed data results to the receiving node(s)
      35             :  *  -# Instantiate a CPU decompressor
      36             :  *  -# Run the decompressor from the command thread
      37             :  *  -# Select and instantiate a transfer compressor based on the CPU
      38             :  *     decompressor token type
      39             :  *  -# Run the upload operation on each render thread
      40             :  *
      41             :  * The operations 3 to 7 are omitted if the input and output frame are on the
      42             :  * same node. The operations 3 to 7 are replaced by transmitting the output data
      43             :  * of the download operation if no matching CPU compressor is found. Plugin
      44             :  * instances are cached and reused for subsequent operations from the same
      45             :  * thread.
      46             :  *
      47             :  * <img src="http://www.equalizergraphics.com/documents/design/images/imageCompression.png">
      48             :  *
      49             :  * To implement a compression plugin, the following steps are to be taken:
      50             :  *  - Create a new shared library named EqualizerCompressorNAME.dll (Win32),
      51             :  *    libEqualizerCompressorNAME.dylib (Mac OS X) or
      52             :  *    libEqualizerCompressorNAME.so (Linux).
      53             :  *  - Define EQ_PLUGIN_BUILD and then include eq/plugins/compressor.h (this
      54             :  *    header file).
      55             :  *  - Implement all relevant C functions from this header file. All plugins have
      56             :  *    to implement EqCompressorGetNumCompressors, EqCompressorGetInfo,
      57             :  *    EqCompressorNewCompressor, EqCompressorNewDecompressor,
      58             :  *    EqCompressorDeleteCompressor and EqCompressorDeleteDecompressor. In
      59             :  *    addition, CPU compressors have to implement EqCompressorCompress,
      60             :  *    EqCompressorDecompress, EqCompressorGetNumResults and
      61             :  *    EqCompressorGetResult. Transfer plugins have to additionally implement
      62             :  *    EqCompressorIsCompatible, EqCompressorDownload and EqCompressorUpload.
      63             :  *    The default Equalizer compressors in src/lib/compressor may be used as a
      64             :  *    template.
      65             :  *  - Put the library in the plugin search path (see
      66             :  *    eq::Global::getPluginDirectories(), defaults to EQ_PLUGIN_PATH or
      67             :  *    "/usr/local/share/Equalizer/plugins;.eqPlugins;$HOME/.eqPlugins;$PWD;$LD_LIBRARY_PATH".
      68             :  *  - Run the image unit test (tests/image) to verify your plugin.
      69             :  *  - Set the compression ratio and speed according to the output of the
      70             :  *    image unit test. Use the Equalizer RLE compressor as baseline.
      71             :  *  - Request official names for your compressors.
      72             :  *
      73             :  * @sa plugins/compressorTypes.h, plugins/compressorTokens.h
      74             :  *
      75             :  * <h2>Changes</h2>
      76             :  * Version 4
      77             :  *  - Added support for asynchronous downloads
      78             :  *    - Added functions: EqCompressorStartDownload, EqCompressorFinishDownload
      79             :  *    - Added flag: EQ_COMPRESSOR_USE_ASYNC_DOWNLOAD
      80             :  *
      81             :  * Version 3
      82             :  *  - Added GPU-based compression during upload and download:
      83             :  *    - Added functions: EqCompressorIsCompatible, EqCompressorDownload,
      84             :  *      EqCompressorUpload
      85             :  *    - Added members in EqCompressorInfo: outputTokenType, outputTokenSize
      86             :  *    - Added flags: EQ_COMPRESSOR_CPU, EQ_COMPRESSOR_TRANSFER,
      87             :  *      EQ_COMPRESSOR_USE_TEXTURE_2D, EQ_COMPRESSOR_USE_TEXTURE_RECT,
      88             :  *      EQ_COMPRESSOR_USE_FRAMEBUFFER
      89             :  *    - Added data types: EQ_COMPRESSOR_DATATYPE_INVALID,
      90             :  *      EQ_COMPRESSOR_DATATYPE_RGBA_UNSIGNED_BYTE,
      91             :  *      EQ_COMPRESSOR_DATATYPE_RGBA_UNSIGNED_INT_8_8_8_8_REV,
      92             :  *      EQ_COMPRESSOR_DATATYPE_RGBA_UNSIGNED_INT_10_10_10_2,
      93             :  *      EQ_COMPRESSOR_DATATYPE_RGBA_HALF_FLOAT,
      94             :  *      EQ_COMPRESSOR_DATATYPE_RGBA_FLOAT,
      95             :  *      EQ_COMPRESSOR_DATATYPE_BGRA_UNSIGNED_BYTE,
      96             :  *      EQ_COMPRESSOR_DATATYPE_BGRA_UNSIGNED_INT_8_8_8_8_REV,
      97             :  *      EQ_COMPRESSOR_DATATYPE_BGRA_UNSIGNED_INT_10_10_10_2,
      98             :  *      EQ_COMPRESSOR_DATATYPE_BGRA_HALF_FLOAT,
      99             :  *      EQ_COMPRESSOR_DATATYPE_BGRA_FLOAT,
     100             :  *      EQ_COMPRESSOR_DATATYPE_DEPTH_UNSIGNED_FLOAT,
     101             :  *      EQ_COMPRESSOR_DATATYPE_DEPTH_UNSIGNED_INT,
     102             :  *      EQ_COMPRESSOR_DATATYPE_DEPTH_UNSIGNED_INT_24_8_NV,
     103             :  *      EQ_COMPRESSOR_DATATYPE_RGB_UNSIGNED_BYTE,
     104             :  *      EQ_COMPRESSOR_DATATYPE_RGB_HALF_FLOAT, EQ_COMPRESSOR_DATATYPE_RGB_FLOAT,
     105             :  *      EQ_COMPRESSOR_DATATYPE_BGR_UNSIGNED_BYTE,
     106             :  *      EQ_COMPRESSOR_DATATYPE_BGR_HALF_FLOAT, EQ_COMPRESSOR_DATATYPE_BGR_FLOAT
     107             :  *    - Added compressor type names: EQ_COMPRESSOR_DIFF_RLE_YUVA_50P,
     108             :  *      EQ_COMPRESSOR_RLE_YUVA_50P, EQ_COMPRESSOR_TRANSFER_RGBA_TO_RGBA,
     109             :  *      EQ_COMPRESSOR_TRANSFER_RGBA_TO_BGRA,
     110             :  *      EQ_COMPRESSOR_TRANSFER_RGBA_TO_RGBA_UINT_8_8_8_8_REV,
     111             :  *      EQ_COMPRESSOR_TRANSFER_RGBA_TO_BGRA_UINT_8_8_8_8_REV,
     112             :  *      EQ_COMPRESSOR_TRANSFER_RGB10A2_TO_RGB10A2,
     113             :  *      EQ_COMPRESSOR_TRANSFER_RGB10A2_TO_BGR10A2,
     114             :  *      EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_RGBA16F,
     115             :  *      EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_BGRA16F,
     116             :  *      EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_RGBA32F,
     117             :  *      EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_BGRA32F,
     118             :  *      EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_BGRA_25P,
     119             :  *      EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_RGBA_25P,
     120             :  *      EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_BGRA16F_50P,
     121             :  *      EQ_COMPRESSOR_TRANSFER_RGBA32F_TO_RGBA16F_50P,
     122             :  *      EQ_COMPRESSOR_TRANSFER_RGBA_TO_YUVA_50P,
     123             :  *      EQ_COMPRESSOR_TRANSFER_RGB_TO_RGB, EQ_COMPRESSOR_TRANSFER_RGB_TO_BGR,
     124             :  *      EQ_COMPRESSOR_TRANSFER_RGB16F_TO_RGB16F,
     125             :  *      EQ_COMPRESSOR_TRANSFER_RGB16F_TO_BGR16F,
     126             :  *      EQ_COMPRESSOR_TRANSFER_RGB32F_TO_RGB32F,
     127             :  *      EQ_COMPRESSOR_TRANSFER_RGB32F_TO_BGR32F,
     128             :  *      EQ_COMPRESSOR_TRANSFER_RGB32F_TO_RGB_25P,
     129             :  *      EQ_COMPRESSOR_TRANSFER_RGB32F_TO_BGR_25P,
     130             :  *      EQ_COMPRESSOR_TRANSFER_RGB32F_TO_BGR16F_50P,
     131             :  *      EQ_COMPRESSOR_TRANSFER_RGB32F_TO_RGB16F_50P,
     132             :  *      EQ_COMPRESSOR_TRANSFER_RGB16F_TO_RGB_50P,
     133             :  *      EQ_COMPRESSOR_TRANSFER_RGB16F_TO_BGR_50P,
     134             :  *      EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_RGBA_50P,
     135             :  *      EQ_COMPRESSOR_TRANSFER_RGBA16F_TO_BGRA_50P,
     136             :  *      EQ_COMPRESSOR_TRANSFER_DEPTH_TO_DEPTH_UNSIGNED_INT,
     137             :  *      EQ_COMPRESSOR_DIFF_RLE_RGBA, EQ_COMPRESSOR_DIFF_RLE_BGRA,
     138             :  *      EQ_COMPRESSOR_DIFF_RLE_RGBA_UINT_8_8_8_8_REV,
     139             :  *      EQ_COMPRESSOR_DIFF_RLE_BGRA_UINT_8_8_8_8_REV,
     140             :  *      EQ_COMPRESSOR_DIFF_RLE_RGB10_A2, EQ_COMPRESSOR_DIFF_RLE_BGR10_A2,
     141             :  *      EQ_COMPRESSOR_DIFF_RLE_RGB, EQ_COMPRESSOR_DIFF_RLE_BGR,
     142             :  *      EQ_COMPRESSOR_DIFF_RLE_DEPTH_UNSIGNED_INT, EQ_COMPRESSOR_RLE_RGBA16F,
     143             :  *      EQ_COMPRESSOR_RLE_BGRA16F, EQ_COMPRESSOR_DIFF_RLE_RGBA16F,
     144             :  *      EQ_COMPRESSOR_DIFF_RLE_BGRA16F, EQ_COMPRESSOR_DIFF_RLE_565_RGBA,
     145             :  *      EQ_COMPRESSOR_DIFF_RLE_565_BGRA,
     146             :  *      EQ_COMPRESSOR_DIFF_RLE_565_RGBA_UINT_8_8_8_8_REV,
     147             :  *      EQ_COMPRESSOR_DIFF_RLE_565_BGRA_UINT_8_8_8_8_REV,
     148             :  *      EQ_COMPRESSOR_DIFF_RLE_565_RGB10_A2,
     149             :  *      EQ_COMPRESSOR_DIFF_RLE_565_BGR10_A2, EQ_COMPRESSOR_RLE_RGBA,
     150             :  *      EQ_COMPRESSOR_RLE_BGRA, EQ_COMPRESSOR_RLE_RGBA_UINT_8_8_8_8_REV,
     151             :  *      EQ_COMPRESSOR_RLE_BGRA_UINT_8_8_8_8_REV, EQ_COMPRESSOR_RLE_RGB10_A2,
     152             :  *      EQ_COMPRESSOR_RLE_BGR10_A2, EQ_COMPRESSOR_RLE_RGB,
     153             :  *      EQ_COMPRESSOR_RLE_BGR, EQ_COMPRESSOR_RLE_DEPTH_UNSIGNED_INT,
     154             :  *      EQ_COMPRESSOR_AG_RTT_JPEG_HQ,
     155             :  *      EQ_COMPRESSOR_AG_RTT_JPEG_MQ,
     156             :  *      EQ_COMPRESSOR_AG_RTT_JPEG_LQ
     157             :  *
     158             :  * Version 2
     159             :  *  - Added EQ_COMPRESSOR_DIFF_RLE_565 to type name registry
     160             :  *  - Added EQ_COMPRESSOR_DIFF_RLE_10A2 to type name registry
     161             :  *  - Added EQ_COMPRESSOR_DATATYPE_RGB10_A2 to token list
     162             :  *
     163             :  * Version 1
     164             :  *  - Initial Release
     165             :  */
     166             : 
     167             : #ifndef EQ_PLUGINS_COMPRESSOR
     168             : #define EQ_PLUGINS_COMPRESSOR
     169             : 
     170             : /** @cond IGNORE */
     171             : #include <sys/types.h>
     172             : struct GLEWContextStruct;
     173             : struct WGLEWContextStruct;
     174             : typedef struct GLEWContextStruct GLEWContext;
     175             : typedef struct WGLEWContextStruct WGLEWContext;
     176             : typedef unsigned long long eq_uint64_t;
     177             : 
     178             : #ifdef _MSC_VER
     179             : #  ifdef EQ_PLUGIN_BUILD
     180             : #    define EQ_PLUGIN_API __declspec(dllexport)
     181             : #  else
     182             : #    define EQ_PLUGIN_API __declspec(dllimport)
     183             : #  endif
     184             : #else // _WIN32
     185             : #  define EQ_PLUGIN_API __attribute__ ((visibility("default")))
     186             : #endif
     187             : /** @endcond */
     188             : 
     189             : /** @name Compressor Plugin API Versioning */
     190             : /*@{*/
     191             : /** The version of the Compressor API described by this header. */
     192             : #define EQ_COMPRESSOR_VERSION 4
     193             : /** At least version 1 of the Compressor API is described by this header. */
     194             : #define EQ_COMPRESSOR_VERSION_1 1
     195             : /**At least version 2 of the Compressor API is described by this header.*/
     196             : #define EQ_COMPRESSOR_VERSION_2 1
     197             : /**At least version 3 of the Compressor API is described by this header.*/
     198             : #define EQ_COMPRESSOR_VERSION_3 1
     199             : /**At least version 4 of the Compressor API is described by this header.*/
     200             : #define EQ_COMPRESSOR_VERSION_4 1
     201             : /*@}*/
     202             : 
     203             : #include "compressorTokens.h"
     204             : #include "compressorTypes.h"
     205             : 
     206             : #ifdef __cplusplus
     207             : #include <iostream>
     208             : extern "C"
     209             : {
     210             : #endif
     211             :     /**
     212             :      * @name Compressor capability flags
     213             :      *
     214             :      * Capability flags define what special features a compressor supports. They
     215             :      * are queried from the DSO, and passed as input to certain functions to
     216             :      * select a given capability of the plugin.
     217             :      */
     218             :     /*@{*/
     219             :     /**
     220             :      * The compressor can (query time) or should (compress) write the compressed
     221             :      * data in the same place as the uncompressed data.
     222             :      */
     223             :     #define EQ_COMPRESSOR_INPLACE    0x1
     224             : 
     225             :     /**
     226             :      * The compressor can handle linear data (query time), or the input data is
     227             :      * linear (compress, decompress). Typically used for binary data.
     228             :      */
     229             :     #define EQ_COMPRESSOR_DATA_1D    0x2
     230             : 
     231             :     /**
     232             :      * The compressor can handle two-dimensional data (query time), or the input
     233             :      * data is two-dimensional (compress, decompress). Typically used for image
     234             :      * data.
     235             :      */
     236             :     #define EQ_COMPRESSOR_DATA_2D    0x4
     237             : 
     238             :     /**
     239             :      * The compressor can, does or should drop the alpha channel.
     240             :      *
     241             :      * The plugin sets this flag during information time to indicate that it
     242             :      * will drop the alpha channel (transfer plugins) or can drop the alpha
     243             :      * channel (compressor plugins).
     244             :      *
     245             :      * During download, the flag will always be set if it was set at query
     246             :      * time. During compression, it will be set only if the alpha channel should
     247             :      * be dropped. It will never be set for plugins which did not indicate this
     248             :      * capability.
     249             :      *
     250             :      * For compression plugins it is assumed that setting this flag improves the
     251             :      * compression ratio by 25 percent. For transfer plugins, it is assumed that
     252             :      * the ratio already includes the alpha reduction.
     253             :      */
     254             :     #define EQ_COMPRESSOR_IGNORE_ALPHA 0x8
     255             :     /** Deprecated */
     256             :     #define EQ_COMPRESSOR_IGNORE_MSE EQ_COMPRESSOR_IGNORE_ALPHA
     257             : 
     258             :     /**
     259             :      * The compressor is a CPU compressor.
     260             :      *
     261             :      * CPU compressors implement data compression and decompression of a block
     262             :      * of memory.
     263             :      */
     264             :     #define EQ_COMPRESSOR_CPU 0
     265             : 
     266             :     /**
     267             :      * The compressor is a CPU-GPU transfer engine.
     268             :      * GPU compressors implement the download from a GPU framebuffer or texture
     269             :      * to main memory, as well as the corresponding upload. During this
     270             :      * operation, compression might take place.
     271             :      */
     272             :     #define EQ_COMPRESSOR_TRANSFER 0x10
     273             : 
     274             :     /**
     275             :      * Capability to use a GL_TEXTURE_RECTANGLE_ARB texture as source or
     276             :      * destination. If set, the transfer engine can (query time) or shall
     277             :      * (compress time) use a rectangular texture as the source or destination
     278             :      * for its operations.
     279             :      */
     280             :     #define EQ_COMPRESSOR_USE_TEXTURE_RECT 0x20
     281             : 
     282             :     /**
     283             :      * Capability to use a GL_TEXTURE_2D texture as source or destination.
     284             :      * If set, the transfer engine can (query time) or shall (compress time) use
     285             :      * a 2D texture as the source or destination for its operations.
     286             :      */
     287             :     #define EQ_COMPRESSOR_USE_TEXTURE_2D 0x80
     288             : 
     289             :     /**
     290             :      * Capability to use the frame buffer as source or destination.
     291             :      * If set, the transfer engine can (query time) or shall (compress time) use
     292             :      * the frame buffer as the source or destination for its operations.
     293             :      */
     294             :     #define EQ_COMPRESSOR_USE_FRAMEBUFFER 0x40
     295             : 
     296             :     /**
     297             :      * Capability to use asynchronous downloads.
     298             :      * If set, the transfer engine will (query time) or shall (download time)
     299             :      * use asynchronous downloads.
     300             :      * @version 4
     301             :      */
     302             :     #define EQ_COMPRESSOR_USE_ASYNC_DOWNLOAD 0x100
     303             : 
     304             : #if 0 // Not implemented yet
     305             :     /**
     306             :      * Capability to use asynchronous uploads.
     307             :      * If set, the transfer engine will (query time) or shall (upload time)
     308             :      * use asynchronous uploads.
     309             :      * @version 4
     310             :      */
     311             :     #define EQ_COMPRESSOR_USE_ASYNC_UPLOAD 0x200
     312             : #endif
     313             :     /*@}*/
     314             : 
     315             :     /** @name DSO information interface. */
     316             :     /*@{*/
     317             :     /** Information about one compressor. */
     318          39 :     struct EqCompressorInfo
     319             :     {
     320             :         /**
     321             :          * The compressor API version used.
     322             :          *
     323             :          * Set on input to the API version used in Equalizer. Has to be set to
     324             :          * EQ_COMPRESSOR_VERSION on output to declare the API version used to
     325             :          * compile the DSO.
     326             :          * @version 1
     327             :          */
     328             :         unsigned version;
     329             : 
     330             :         /** The type name of the compressor. @version 1 */
     331             :         unsigned name;
     332             : 
     333             :         /**
     334             :          * The input token type supported by the compressor.
     335             :          *
     336             :          * The input token type describes the format of the input data for a
     337             :          * compressor or downloader and the format of the output data for the
     338             :          * decompressor or uploader of the same compressor.
     339             :          * @version 1
     340             :          */
     341             :         unsigned tokenType;
     342             : 
     343             :         /** Capabilities supported by the compressor. @version 1 */
     344             :         eq_uint64_t capabilities;
     345             : 
     346             :         /** Compression quality (1.0f: loss-less, <1.0f: lossy). @version 1 */
     347             :         float quality;
     348             : 
     349             :         /** Approximate compression ratio (sizeCompressed/sizeIn). @version 1 */
     350             :         float ratio;
     351             : 
     352             :         /** Approximate compression speed relative to BYTE_RLE. @version 1 */
     353             :         float speed;
     354             : 
     355             :         /**
     356             :          * The output token type of a plugin.
     357             :          *
     358             :          * The output token type describes the format of the data produced by a
     359             :          * downloader and consumed by the uploader of the same compressor.
     360             :          *
     361             :          * A CPU compressor might set the output token type if its decompressor
     362             :          * produces an output different from the input.
     363             :          *
     364             :          * If this parameter is set, outputTokenSize has to be set as well.
     365             :          * @version 3
     366             :          */
     367             :         unsigned outputTokenType;
     368             : 
     369             :         /** The size of one output token in bytes. @version 3 */
     370             :         unsigned outputTokenSize;
     371             :     };
     372             : 
     373             :     /** @return the number of compressors implemented in the DSO. @version 1 */
     374             :     EQ_PLUGIN_API size_t EqCompressorGetNumCompressors();
     375             : 
     376             :     /**
     377             :      * Query information of the nth compressor in the DSO.
     378             :      *
     379             :      * Plugins aiming to be backward-compatible, i.e., usable in older version
     380             :      * than the one compiled against, have to carefully check the provided
     381             :      * runtime version in info. If they implement features incompatible with
     382             :      * older Equalizer versions, e.g., a CPU compressor with an outputTokenType
     383             :      * different from tokenType, they either have to implement a compatibility
     384             :      * code path or to disable the compressor by setting the tokenType to
     385             :      * EQ_COMPRESSOR_DATATYPE_INVALID.
     386             :      *
     387             :      * @version 1
     388             :      */
     389             :     EQ_PLUGIN_API void EqCompressorGetInfo( const size_t n,
     390             :                                             EqCompressorInfo* const info );
     391             :     /*@}*/
     392             : 
     393             :     /** @name Compressor lifecycle management. */
     394             :     /*@{*/
     395             :     /**
     396             :      * Instantiate a new compressor or a new downloader.
     397             :      *
     398             :      * This function has to create a new instance of the given compressor
     399             :      * type. Multiple instances might be used concurrently. One given instance
     400             :      * is always used from one thread at any given time.
     401             :      *
     402             :      * For one given name, there can only be one given implementation of a
     403             :      * compressor or downloader. This type has been given by the plugin during
     404             :      * getInfo.
     405             :      *
     406             :      * @param name the type name of the compressor.
     407             :      * @return an opaque pointer to the compressor instance.
     408             :      * @version 1
     409             :      */
     410             :     EQ_PLUGIN_API void* EqCompressorNewCompressor( const unsigned name );
     411             : 
     412             :     /**
     413             :      * Release a compressor or downloader instance.
     414             :      *
     415             :      * @param compressor the compressor instance to free.
     416             :      * @version 1
     417             :      */
     418             :     EQ_PLUGIN_API void EqCompressorDeleteCompressor( void* const compressor );
     419             : 
     420             :     /**
     421             :      * Instantiate a new decompressor or a new uploader.
     422             :      *
     423             :      * This function might create a new instance of the given decompressor
     424             :      * type. Multiple instances might be used concurrently. One given instance
     425             :      * is always used from one thread at any given time. State-less
     426             :      * decompressors might return 0.
     427             :      *
     428             :      * @param name the type name of the decompressor.
     429             :      * @return an opaque pointer to the decompressor instance, or 0 if no
     430             :      *         instance is needed by the implementation.
     431             :      * @version 1
     432             :      */
     433             :     EQ_PLUGIN_API void* EqCompressorNewDecompressor( const unsigned name );
     434             : 
     435             :     /**
     436             :      * Release a decompressor instance.
     437             :      *
     438             :      * @param decompressor the decompressor instance to free.
     439             :      * @version 1
     440             :      */
     441             :     EQ_PLUGIN_API void EqCompressorDeleteDecompressor(void* const decompressor);
     442             :     /*@}*/
     443             : 
     444             :     /** @name CPU Compressor worker functions */
     445             :     /*@{*/
     446             :     /**
     447             :      * Compress data.
     448             :      *
     449             :      * The number of dimensions in the input and output data is given as a
     450             :      * flag. The input dimensions give an offset and a size for each dimension
     451             :      * in the format <code>dim0_offset, dim0_size, dim1_offset, ...,
     452             :      * dimN_size</code>. The offset does not apply to the input pointer, it is
     453             :      * merely a hint on where the data is positioned, e.g., where a 2D image is
     454             :      * positioned in a virtual framebuffer. The size of the input data is
     455             :      * <code>mul( inDims[1,3,...,n] ) * sizeof( info->dataType )</code>.<br>
     456             :      *
     457             :      * The compressor has to store the results internally in its instance data.
     458             :      * The result of the compression run will be queried later. Results of
     459             :      * previous compression do not have to be retained, i.e., they can be
     460             :      * overwritten on subsequent compression runs.
     461             :      *
     462             :      * @param compressor the compressor instance.
     463             :      * @param name the type name of the compressor.
     464             :      * @param in the pointer to the input data.
     465             :      * @param inDims the dimensions of the input data.
     466             :      * @param flags capability flags for the compression.
     467             :      * @version 1
     468             :      */
     469             :     EQ_PLUGIN_API void EqCompressorCompress( void* const compressor,
     470             :                                              const unsigned name,
     471             :                                              void* const in,
     472             :                                              const eq_uint64_t* inDims,
     473             :                                              const eq_uint64_t flags );
     474             : 
     475             :     /**
     476             :      * Return the number of results produced by the last compression.
     477             :      *
     478             :      * A compressor might generate multiple output stream, e.g., when operating
     479             :      * on structured data or using parallel compression routines.
     480             :      *
     481             :      * @param compressor the compressor instance.
     482             :      * @param name the type name of the compressor.
     483             :      * @return the number of output results.
     484             :      * @version 1
     485             :      */
     486             :     EQ_PLUGIN_API unsigned EqCompressorGetNumResults( void* const compressor,
     487             :                                                       const unsigned name );
     488             : 
     489             :     /**
     490             :      * Return the ith result of the last compression.
     491             :      *
     492             :      * @param compressor the compressor instance.
     493             :      * @param name the type name of the compressor.
     494             :      * @param i the result index to return.
     495             :      * @param out the return value to store the result pointer.
     496             :      * @param outSize the return value to store the result size in bytes.
     497             :      * @version 1
     498             :      */
     499             :     EQ_PLUGIN_API void EqCompressorGetResult( void* const compressor,
     500             :                                               const unsigned name,
     501             :                                               const unsigned i,
     502             :                                               void** const out,
     503             :                                               eq_uint64_t* const outSize );
     504             : 
     505             :     /**
     506             :      * Decompress data.
     507             :      *
     508             :      * The decompressor gets all result pointers as produced by the compressor
     509             :      * as input. The routine should use the output buffer fully. For dimensions
     510             :      * and output size see EqCompressorCompress.
     511             :      *
     512             :      * @param decompressor the decompressor instance, can be 0.
     513             :      * @param name the type name of the decompressor.
     514             :      * @param in the pointer to an array of input data pointers.
     515             :      * @param inSizes the array of input data sizes in bytes.
     516             :      * @param numInputs the number of input data elements.
     517             :      * @param out the pointer to a pre-allocated buffer for the uncompressed
     518             :      *            output result.
     519             :      * @param outDims the dimensions of the output data.
     520             :      * @param flags capability flags for the decompression.
     521             :      * @sa EqCompressorCompress
     522             :      * @version 1
     523             :      * @note outDims should be const, which was an oversight
     524             :      */
     525             :     EQ_PLUGIN_API void EqCompressorDecompress( void* const decompressor,
     526             :                                                const unsigned name,
     527             :                                                const void* const* in,
     528             :                                                const eq_uint64_t* const inSizes,
     529             :                                                const unsigned numInputs,
     530             :                                                void* const out,
     531             :                                                eq_uint64_t* const outDims,
     532             :                                                const eq_uint64_t flags );
     533             :     /*@}*/
     534             : 
     535             :     /** @name Transfer engine worker functions */
     536             :     /*@{*/
     537             :     /**
     538             :      * Check if the compressor may be used with the current OpenGL context.
     539             :      *
     540             :      * The OpenGL context is current, and has not be modified by this
     541             :      * function. The given glewContext is an initialized GLEWContext
     542             :      * corresponding to the OpenGL context. Typically this function checks for a
     543             :      * given OpenGL version and/or extension required by the transfer engine.
     544             :      *
     545             :      * @param name the type name of the compressor.
     546             :      * @param glewContext the initialized GLEW context describing corresponding
     547             :      *                    to the current OpenGL context.
     548             :      * @return true if the compressor is compatible with the environment.
     549             :      * @version 3
     550             :      */
     551             :     EQ_PLUGIN_API bool EqCompressorIsCompatible( const unsigned name,
     552             :                                                const GLEWContext* glewContext );
     553             : 
     554             :     /**
     555             :      * Transfer frame buffer data into main memory.
     556             :      *
     557             :      * This function has to transfer the specified frame buffer region or
     558             :      * texture from the GPU memory into main memory. In the process, a
     559             :      * transformation (including compression) of the data may take place. The
     560             :      * result buffer has to be allocated by the compressor. The buffer has to be
     561             :      * valied until the next call to this function or the destruction of this
     562             :      * instance.
     563             :      *
     564             :      * The correct SystemWindow is current, e.g., the OpenGL context is current
     565             :      * and the frame buffer is bound correctly. The format and type of the input
     566             :      * frame buffer are determined indirectly by the information provided by the
     567             :      * plugin for the given compressor name, that is, the plugin has
     568             :      * pre-declared the frame buffer type it processes during
     569             :      * EqCompressorGetInfo().
     570             :      *
     571             :      * The OpenGL context has been setup using Compositor::setupAssemblyState()
     572             :      * using the channel's pvp. If the OpenGL state is modified by this
     573             :      * function, it has to reset it before leaving.
     574             :      *
     575             :      * The pointer and data size is returned using the out parameters. The
     576             :      * outDims parameter has the format <code>x, w, y, h</code>. If the
     577             :      * compressor produces an image (structured data), the outDims should be set
     578             :      * to a multiple of inDims. For unstructured data the values should be set
     579             :      * to <code>x = 0, w = num_elements, y = 0, h = 1</code>. The output pointer
     580             :      * has to be valid until the next call to this function using the same
     581             :      * compressor instance.
     582             :      *
     583             :      * Flags will always contain EQ_COMPRESSOR_DATA_2D, and may contain:
     584             :      *  - EQ_COMPRESSOR_IGNORE_ALPHA if the alpha value of a color buffer may
     585             :      *    be dropped during download
     586             :      *  - EQ_COMPRESSOR_USE_TEXTURE_2D if the source is a 2D texture ID
     587             :      *  - EQ_COMPRESSOR_USE_TEXTURE_RECT if the source is a rectangle texture ID
     588             :      *  - EQ_COMPRESSOR_USE_FRAMEBUFFER if the source is an OpenGL frame buffer
     589             :      *
     590             :      * @param compressor the compressor instance.
     591             :      * @param name the type name of the compressor.
     592             :      * @param glewContext the initialized GLEW context describing corresponding
     593             :      *                    to the current OpenGL context.
     594             :      * @param inDims the dimensions of the input data (x, w, y, h).
     595             :      * @param source texture name, if EQ_COMPRESSOR_USE_TEXTURE_2D or
     596             :      *               EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
     597             :      * @param flags capability flags for the compression (see description).
     598             :      * @param outDims the dimensions of the output data (see description).
     599             :      * @param out the pointer to the output data.
     600             :      * @version 3
     601             :      */
     602             :     EQ_PLUGIN_API void EqCompressorDownload( void* const        compressor,
     603             :                                              const unsigned     name,
     604             :                                              const GLEWContext* glewContext,
     605             :                                              const eq_uint64_t  inDims[4],
     606             :                                              const unsigned     source,
     607             :                                              const eq_uint64_t  flags,
     608             :                                              eq_uint64_t        outDims[4],
     609             :                                              void**             out );
     610             : 
     611             :     /**
     612             :      * Start transferring frame buffer data into main memory.
     613             :      *
     614             :      * When a plugin indicates that it supports asynchronous downloads during
     615             :      * query time, this function will be set by Equalizer versions supporting
     616             :      * async downloads. This function should then initiate the download using
     617             :      * the given input parameters, which behave exactly as described in
     618             :      * EqCompressorDownload. The operation will be completed from another thread
     619             :      * using EqCompressorFinishDownload().
     620             :      *
     621             :      * Older Equalizer versions will call EqCompressorDownload(), which should
     622             :      * also be implemented by plugins using EqCompressorStartDownload() and
     623             :      * EqCompressorFinishDownload() to perform a synchronous readback.
     624             :      *
     625             :      * @param compressor the compressor instance.
     626             :      * @param name the type name of the compressor.
     627             :      * @param glewContext the initialized GLEW context describing corresponding
     628             :      *                    to the current OpenGL context.
     629             :      * @param inDims the dimensions of the input data (x, w, y, h).
     630             :      * @param source texture name, if EQ_COMPRESSOR_USE_TEXTURE_2D or
     631             :      *               EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
     632             :      * @param flags capability flags for the compression (see description).
     633             :      * @version 4
     634             :      */
     635             :     EQ_PLUGIN_API void EqCompressorStartDownload( void* const        compressor,
     636             :                                                   const unsigned     name,
     637             :                                                  const GLEWContext* glewContext,
     638             :                                                   const eq_uint64_t  inDims[4],
     639             :                                                   const unsigned     source,
     640             :                                                   const eq_uint64_t  flags );
     641             : 
     642             :     /**
     643             :      * Finish transferring frame buffer data into main memory.
     644             :      *
     645             :      * Finish an operation started using EqCompressorStartDownload(). The
     646             :      * correct SystemWindow is current, e.g., a shared OpenGL context is current
     647             :      * and the frame buffer is bound correctly. No OpenGL context setup is done.
     648             :      *
     649             :      * @param compressor the compressor instance.
     650             :      * @param name the type name of the compressor.
     651             :      * @param glewContext the initialized GLEW context describing corresponding
     652             :      *                    to the current OpenGL context.
     653             :      * @param inDims the dimensions of the input data (x, w, y, h).
     654             :      * @param flags capability flags for the compression (see description).
     655             :      * @param outDims the dimensions of the output data (see description).
     656             :      * @param out the pointer to the output data.
     657             :      * @version 4
     658             :      */
     659             :     EQ_PLUGIN_API void EqCompressorFinishDownload( void* const compressor,
     660             :                                                    const unsigned     name,
     661             :                                                  const GLEWContext* glewContext,
     662             :                                                    const eq_uint64_t  inDims[4],
     663             :                                                    const eq_uint64_t  flags,
     664             :                                                    eq_uint64_t outDims[4],
     665             :                                                    void**             out );
     666             : 
     667             :     /**
     668             :      * Transfer data from main memory into GPU memory.
     669             :      *
     670             :      * This function applies the inverse operation of EqCompressorDownload, that
     671             :      * is, it transfers the specified buffer into the GPU. It may apply a
     672             :      * transformation, including decompression, during its operation. At the
     673             :      * end, the result must be located in the frame buffer or the provided
     674             :      * texture.
     675             :      *
     676             :      * The correct OpenGL context is current. The texture is initialized to the
     677             :      * size provided by inDims and it is not bound. The OpenGL context has been
     678             :      * setup using Compositor::setupAssemblyState() using the channel pvp. If
     679             :      * the OpenGL state is modified by this function, it has to reset it before
     680             :      * leaving.
     681             :      *
     682             :      * The parameters buffer, inDims, flags will contain the same values as the
     683             :      * parameters out, outDims, flags of the corresponding
     684             :      * EqCompressorDownload() call. Please refer to the documentation of this
     685             :      * function for further information.
     686             :      *
     687             :      * Flags will always contain EQ_COMPRESSOR_DATA_2D, and may contain:
     688             :      *  - EQ_COMPRESSOR_IGNORE_ALPHA if the alpha value of a color buffer may
     689             :      *     be dropped during upload
     690             :      *  - EQ_COMPRESSOR_USE_TEXTURE_2D if the destination is a 2D texture ID
     691             :      *  - EQ_COMPRESSOR_USE_TEXTURE_RECT if the destination is a rectancle
     692             :      *    texture ID
     693             :      *  - EQ_COMPRESSOR_USE_FRAMEBUFFER if the destination is an OpenGL frame
     694             :      *     buffer
     695             :      *
     696             :      * @param decompressor the compressor instance.
     697             :      * @param name the type name of the compressor.
     698             :      * @param glewContext the initialized GLEW context corresponding to the
     699             :      *                    current OpenGL context.
     700             :      * @param buffer the input data.
     701             :      * @param inDims the dimension of the input data.
     702             :      * @param flags capability flags for the compression.
     703             :      * @param outDims the result data size in the frame buffer.
     704             :      * @param destination the destination texture name if
     705             :      *                    EQ_COMPRESSOR_USE_TEXTURE_2D or
     706             :      *                    EQ_COMPRESSOR_USE_TEXTURE_RECT is set.
     707             :      * @version 3
     708             :      */
     709             :     EQ_PLUGIN_API void EqCompressorUpload( void* const        decompressor,
     710             :                                            const unsigned     name,
     711             :                                            const GLEWContext* glewContext,
     712             :                                            const void*        buffer,
     713             :                                            const eq_uint64_t  inDims[4],
     714             :                                            const eq_uint64_t  flags,
     715             :                                            const eq_uint64_t  outDims[4],
     716             :                                            const unsigned     destination );
     717             : #if 0
     718             :     // TODO: add EqCompressorStart/FinishUpload and document operations and
     719             :     // parameters
     720             : #endif
     721             :     /*@}*/
     722             : #ifdef __cplusplus
     723             : } // extern "C"
     724             : 
     725           0 : inline std::ostream& operator << ( std::ostream& os,
     726             :                                    const EqCompressorInfo& info )
     727             : {
     728           0 :     return os << std::hex << "name 0x" << info.name << " in 0x"
     729           0 :               << info.tokenType << " out 0x" << info.outputTokenType
     730           0 :               << " cap 0x" << info.capabilities << std::dec << " quality "
     731           0 :               << info.quality <<" ratio " << info.ratio << " speed "
     732           0 :               << info.speed << " v" << info.version;
     733             : }
     734             : #endif
     735             : #endif // EQ_PLUGINS_COMPRESSOR

Generated by: LCOV version 1.10