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 40 : 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
|
