Equalizer  1.13.0
Parallel Rendering Framework
eq::Image Class Reference

A holder for pixel data. More...

#include <image.h>

+ Collaboration diagram for eq::Image:

Public Member Functions

EQ_API Image ()
 Construct a new Image. More...
 
virtual EQ_API ~Image ()
 Destruct the Image. More...
 
Image parameters
EQ_API void setInternalFormat (const Frame::Buffer buffer, const uint32_t internalFormat)
 Set the internal format for the given buffer. More...
 
EQ_API uint32_t getInternalFormat (const Frame::Buffer buffer) const
 
EQ_API uint32_t getExternalFormat (const Frame::Buffer buffer) const
 Get the external format of the given buffer. More...
 
EQ_API uint32_t getPixelSize (const Frame::Buffer buffer) const
 Get the size, in bytes, of one pixel in the external pixel data. More...
 
EQ_API bool hasAlpha () const
 
EQ_API void setStorageType (const Frame::Type type)
 Set the frame pixel storage type. More...
 
EQ_API Frame::Type getStorageType () const
 
EQ_API void setPixelViewport (const PixelViewport &pvp)
 Set the internal pixel viewport of the image. More...
 
EQ_API const PixelViewport & getPixelViewport () const
 
EQ_API void setZoom (const Zoom &zoom)
 Sets the zoom factor to be used for compositing. More...
 
EQ_API const Zoom & getZoom () const
 
EQ_API void setContext (const RenderContext &context)
 Set the render context producing this image. More...
 
EQ_API const RenderContext & getContext () const
 
EQ_API void useCompressor (Frame::Buffer buffer, uint32_t name)
 Set a compressor to be used during transmission of the image. More...
 
EQ_API void reset ()
 Reset the image to its default state. More...
 
EQ_API void flush ()
 Free all cached data of this image. More...
 
EQ_API void deleteGLObjects (util::ObjectManager &om)
 Delete all OpenGL objects allocated from the given object manager. More...
 
EQ_API void resetPlugins ()
 Deallocate all transfer and compression plugins. More...
 
Pixel Data Access
EQ_API const uint8_t * getPixelPointer (const Frame::Buffer buffer) const
 
EQ_API uint8_t * getPixelPointer (const Frame::Buffer buffer)
 
EQ_API uint32_t getPixelDataSize (const Frame::Buffer buffer) const
 
EQ_API const PixelDatagetPixelData (const Frame::Buffer) const
 
EQ_API const PixelDatacompressPixelData (const Frame::Buffer)
 
EQ_API bool hasPixelData (const Frame::Buffer buffer) const
 
EQ_API bool hasAsyncReadback (const Frame::Buffer buffer) const
 
EQ_API bool hasAsyncReadback () const
 
EQ_API void clearPixelData (const Frame::Buffer buffer)
 Clear and validate an image buffer. More...
 
EQ_API void validatePixelData (const Frame::Buffer buffer)
 Allocate an image buffer without initialization. More...
 
EQ_API void setPixelData (const Frame::Buffer buffer, const PixelData &data)
 Set the pixel data of the given image buffer. More...
 
EQ_API void setAlphaUsage (const bool enabled)
 Set alpha data preservation during download and compression. More...
 
EQ_API bool getAlphaUsage () const
 
EQ_API void setQuality (const Frame::Buffer buffer, const float quality)
 Set the minimum quality after a full download-compression path. More...
 
EQ_API float getQuality (const Frame::Buffer buffer) const
 
Texture Data Access
EQ_API const util::TexturegetTexture (const Frame::Buffer buffer) const
 Get the texture of this image. More...
 
EQ_API bool hasTextureData (const Frame::Buffer buffer) const
 
Operations
EQ_API bool startReadback (const uint32_t buffers, const PixelViewport &pvp, const RenderContext &context, const Zoom &zoom, util::ObjectManager &glObjects)
 Start reading back an image from the frame buffer. More...
 
bool startReadback (const Frame::Buffer buffer, const util::Texture *texture, const GLEWContext *glewContext)
 
EQ_API void finishReadback (const GLEWContext *glewContext)
 Finish an asynchronous readback. More...
 
EQ_API bool upload (const Frame::Buffer buffer, util::Texture *texture, const Vector2i &position, util::ObjectManager &glObjects) const
 Upload this image to the frame buffer or a texture. More...
 
EQ_API bool writeImage (const std::string &filename, const Frame::Buffer buffer) const
 Write the pixel data as rgb image file. More...
 
EQ_API bool writeImages (const std::string &filenameTemplate) const
 Write all valid pixel data as separate images. More...
 
EQ_API bool readImage (const std::string &filename, const Frame::Buffer buffer)
 Read pixel data from an uncompressed rgb image file. More...
 
void setOffset (int32_t x, int32_t y)
 
Internal
EQ_API std::vector< uint32_t > findCompressors (const Frame::Buffer buffer) const
 
EQ_API std::vector< uint32_t > findTransferers (const Frame::Buffer buffer, const GLEWContext *gl) const
 
EQ_API bool allocCompressor (const Frame::Buffer buffer, const uint32_t name)
 
EQ_API bool allocDownloader (const Frame::Buffer buffer, const uint32_t name, const GLEWContext *glewContext)
 
EQ_API uint32_t getDownloaderName (const Frame::Buffer buffer) const
 

Detailed Description

A holder for pixel data.

An image holds color and depth information for one rectangular region.

Definition at line 36 of file image.h.

Constructor & Destructor Documentation

EQ_API eq::Image::Image ( )

Construct a new Image.

Version
1.0
virtual EQ_API eq::Image::~Image ( )
virtual

Destruct the Image.

Version
1.0

Member Function Documentation

EQ_API void eq::Image::clearPixelData ( const Frame::Buffer  buffer)

Clear and validate an image buffer.

RGBA and BGRA buffers are initialized with (0,0,0,255). DEPTH_UNSIGNED_INT buffers are initialized with 255. All other buffers are zero-initialized. Validates the buffer.

Parameters
bufferthe image buffer to clear.
Version
1.0
EQ_API const PixelData& eq::Image::compressPixelData ( const Frame::Buffer  )
Returns
the pixel data, compressing it if needed.
Version
1.0
EQ_API void eq::Image::deleteGLObjects ( util::ObjectManager om)

Delete all OpenGL objects allocated from the given object manager.

Requires the appropriate OpenGL context to be current.

Version
1.3.2
EQ_API void eq::Image::finishReadback ( const GLEWContext *  glewContext)

Finish an asynchronous readback.

Parameters
glewContextthe OpenGL function table.
Version
1.7.1
EQ_API void eq::Image::flush ( )

Free all cached data of this image.

Version
1.0
EQ_API bool eq::Image::getAlphaUsage ( ) const
Returns
true if alpha data can not be ignored.
Version
1.0
EQ_API const RenderContext& eq::Image::getContext ( ) const
Returns
the rendering context which created this image, or a default.
EQ_API uint32_t eq::Image::getExternalFormat ( const Frame::Buffer  buffer) const

Get the external format of the given buffer.

The external format describes the layout of the pixel data in main memory. It is determined by the plugin used during download. The external format also determines the pixel size and alpha availability.

Parameters
bufferthe frame buffer attachment.
Returns
the external format of the pixel data.
Version
1.0
EQ_API uint32_t eq::Image::getInternalFormat ( const Frame::Buffer  buffer) const
Returns
the internal format of the pixel data.
Version
1.0
EQ_API const PixelData& eq::Image::getPixelData ( const Frame::Buffer  ) const
Returns
the pixel data.
Version
1.0
EQ_API uint32_t eq::Image::getPixelDataSize ( const Frame::Buffer  buffer) const
Returns
the total size of the pixel data in bytes.
Version
1.0
EQ_API const uint8_t* eq::Image::getPixelPointer ( const Frame::Buffer  buffer) const
Returns
a pointer to the raw pixel data.
Version
1.0
EQ_API uint8_t* eq::Image::getPixelPointer ( const Frame::Buffer  buffer)
Returns
a pointer to the raw pixel data.
Version
1.0
EQ_API uint32_t eq::Image::getPixelSize ( const Frame::Buffer  buffer) const

Get the size, in bytes, of one pixel in the external pixel data.

Parameters
bufferthe frame buffer attachment.
See also
getExternalFormat()
Version
1.0
EQ_API const PixelViewport& eq::Image::getPixelViewport ( ) const
Returns
the internal pixel viewport.
Version
1.0
EQ_API float eq::Image::getQuality ( const Frame::Buffer  buffer) const
Returns
the minimum quality.
Version
1.0
EQ_API Frame::Type eq::Image::getStorageType ( ) const
Returns
the pixel data storage type.
Version
1.0
EQ_API const util::Texture& eq::Image::getTexture ( const Frame::Buffer  buffer) const

Get the texture of this image.

Version
1.0
EQ_API const Zoom& eq::Image::getZoom ( ) const
Returns
zoom factor to be used for compositing.
EQ_API bool eq::Image::hasAlpha ( ) const
Returns
true if the image has a color buffer with alpha values.
See also
getExternalFormat()
Version
1.0
EQ_API bool eq::Image::hasAsyncReadback ( const Frame::Buffer  buffer) const
Returns
true if an async readback for a buffer is in progress.
Version
1.3.2
EQ_API bool eq::Image::hasAsyncReadback ( ) const
Returns
true if an async readback for any buffer is in progress.
Version
1.3.2
EQ_API bool eq::Image::hasPixelData ( const Frame::Buffer  buffer) const
Returns
true if the image has valid pixel data for the buffer.
Version
1.0
EQ_API bool eq::Image::hasTextureData ( const Frame::Buffer  buffer) const
Returns
true if the image has texture data for the buffer.
Version
1.0
EQ_API bool eq::Image::readImage ( const std::string &  filename,
const Frame::Buffer  buffer 
)

Read pixel data from an uncompressed rgb image file.

Version
1.0
EQ_API void eq::Image::reset ( )

Reset the image to its default state.

This method does not free allocated memory or plugins. Invalidates all pixel data.

See also
flush()
Version
1.0
EQ_API void eq::Image::resetPlugins ( )

Deallocate all transfer and compression plugins.

Requires the OpenGL context used during readback to be current.

Version
1.3.2
EQ_API void eq::Image::setAlphaUsage ( const bool  enabled)

Set alpha data preservation during download and compression.

Version
1.0
EQ_API void eq::Image::setContext ( const RenderContext &  context)

Set the render context producing this image.

EQ_API void eq::Image::setInternalFormat ( const Frame::Buffer  buffer,
const uint32_t  internalFormat 
)

Set the internal format for the given buffer.

The internal format descibes the format of the pixel data source, typically an OpenGL frame buffer or texture. The internal formats used by Equalizer use the same numerical value as their OpenGL counterpart.

Parameters
bufferthe frame buffer attachment.
internalFormatthe internal format.
Version
1.0
EQ_API void eq::Image::setPixelData ( const Frame::Buffer  buffer,
const PixelData data 
)

Set the pixel data of the given image buffer.

Previous data for the buffer is overwritten. Validates the buffer. Depending on the given PixelData parameters, the pixel data is copied, decompressed or cleared.

Parameters
bufferthe image buffer to set.
datathe pixel data.
Version
1.0
EQ_API void eq::Image::setPixelViewport ( const PixelViewport &  pvp)

Set the internal pixel viewport of the image.

The image pixel data and textures will be invalidated. The pixel data describes the size of the image on the destination (GPU). Each downloaded buffer has its own size, which is potentially different from the image PVP.

Parameters
pvpthe pixel viewport.
Version
1.0
EQ_API void eq::Image::setQuality ( const Frame::Buffer  buffer,
const float  quality 
)

Set the minimum quality after a full download-compression path.

The automatic selection of a download and compression plugin will never always choose plugins which maintain at least the given quality. A quality of 1.0 enables a lossless transmission path, and a quality of 0.0 disables all quality quarantees.

Parameters
bufferthe frame buffer attachment.
qualitythe minimum quality to maintain.
Version
1.0
EQ_API void eq::Image::setStorageType ( const Frame::Type  type)

Set the frame pixel storage type.

Images of storage type TYPE_MEMORY are read back from the frame buffer into main memory using a transfer plugin. The data can be accessed through the PixelData.

Image of storage type TYPE_TEXTURE read frame buffer data into a texture, which can be accessed using getTexture().

Version
1.0
EQ_API void eq::Image::setZoom ( const Zoom &  zoom)

Sets the zoom factor to be used for compositing.

EQ_API bool eq::Image::startReadback ( const uint32_t  buffers,
const PixelViewport &  pvp,
const RenderContext &  context,
const Zoom &  zoom,
util::ObjectManager glObjects 
)

Start reading back an image from the frame buffer.

Parameters
buffersbit-wise combination of the Frame::Buffer components.
pvpthe area of the frame buffer wrt the drawable.
contextthe render context producing the pixel data.
zoomthe scale factor to apply during readback.
glObjectsthe GL object manager for the current GL context.
Returns
true when the operation requires a finishReadback().
Version
1.3.2
EQ_API bool eq::Image::upload ( const Frame::Buffer  buffer,
util::Texture texture,
const Vector2i &  position,
util::ObjectManager glObjects 
) const

Upload this image to the frame buffer or a texture.

If a texture is given, the upload is performed to it. Otherwise the pixel data is uploaded to the frame buffer. The texture will be initialized using the parameters corresponding to the requested buffer.

Parameters
bufferthe buffer type.
texturethe target texture, or 0 for frame buffer upload.
positionthe destination offset wrt current GL viewport.
glObjectsthe OpenGL object manager for the current context.
Returns
true on success, false on error.
Version
1.0
EQ_API void eq::Image::useCompressor ( Frame::Buffer  buffer,
uint32_t  name 
)

Set a compressor to be used during transmission of the image.

The default compressor is EQ_COMPRESSOR_AUTO which selects the most suitable compressor based on the current image and buffer parameters.

Parameters
bufferthe frame buffer attachment.
namethe compressor name
EQ_API void eq::Image::validatePixelData ( const Frame::Buffer  buffer)

Allocate an image buffer without initialization.

Version
1.0
EQ_API bool eq::Image::writeImage ( const std::string &  filename,
const Frame::Buffer  buffer 
) const

Write the pixel data as rgb image file.

Since version 1.9 (if build with OpenSceneGraph) this function can write images according to supported plugins, see http://trac.openscenegraph.org/projects/osg/wiki/Support/UserGuides/Plugins

Version
1.0
EQ_API bool eq::Image::writeImages ( const std::string &  filenameTemplate) const

Write all valid pixel data as separate images.

Version
1.0

The documentation for this class was generated from the following file: