A3DGraphPictureData Struct Reference

A description of a two-dimensional picture. More...

Data Fields

A3DEPictureDataFormat m_eFormat
 Image format specifier.
 
A3DUns8m_pucBinaryData
 Image binary data.
 
A3DUns32 m_uiPixelHeight
 Image height in pixels. If picture dimension is part of m_pucBinaryData, this field is 0.
 
A3DUns32 m_uiPixelWidth
 Image width in pixels. If picture dimension is part of m_pucBinaryData, this field is 0.
 
A3DUns32 m_uiSize
 The size of m_pucBinaryData in bytes.
 

Detailed Description

A description of a two-dimensional picture.

Version
2.0

A picture is a set of color information organised according to a specific memory layout known as format. HOOPS supports various layouts such as RGB or grayscale.

Pictures are mainly used within textures descriptions. To known how to read or define texture information within Exchange, see A3DGraphTextureDefinitionData.

Encoding
Raw picture data are written into m_pucBinaryData. Description for the actual content depends on the picture format selected into m_eFormat. When dimensions of the picture is not encoded within the data, image width and height are written into m_uiPixelWidth and m_uiPixelHeight respectively, in pixels.
Raw color data
m_pucBinaryData can hold a raw pixel array where each byte describes a component for one pixel. According to the value for m_eFormat:
  • kA3DPictureBitmapGreyByte: Each pixel is encoded within one byte with a value of the range [0 ; 255]. This format is generally used for grayscale images.
  • kA3DPictureBitmapGreyaByte: Same as kA3DPictureBitmapGreyByte but each value is followed by a second pixel information, generally used for alpha (transparency) channel.
  • kA3DPictureBitmapRgbByte: Each pixel is encoded within a triplet of bytes which descriped the red, green and blue components of the pixel in memory order.
  • kA3DPictureBitmapRgbaByte: Same as kA3DPictureBitmapRgbByte but a fourth byte is added at the end of each triplet, generally for alpha (transparency) information.

The pixel array is describes row-major, where the origin is at the topleft corner of the image.

The following code describes an RGB 255x100 image with a color fading from red to green:

picture.m_uiPixelWidth = 255;
picture.m_uiPixelHeight = 100;
picture.m_uiSize = picture.m_uiPixelWidth * picture.m_uiPixelHeight * 3;
picture.m_pucBinaryData = malloc(picture.m_uiSize);
for (A3DUns32 row = 0 ; row < picture.m_uiPixelHeight ; ++row) {
for (A3DUns32 column = 0 ; column < picture.m_uiPixelHeight ; ++column) {
A3DUns32 red_i = (picture.m_uiPixelWidth * row + column) * 3;
A3DUns32 green_i = red_i + 1;
A3DUns32 blue_i = green_i + 1;
picture.m_pucBinaryData[red_i] = 255 - row;
picture.m_pucBinaryData[green_i] = row;
picture.m_pucBinaryData[blue] = 0;
}
}

The following function is an example on how to use [OpenGL 4 glTexImage2D] with HOOPS picture data:

A3DStatus picture_data_to_gl_texture(const A3DGraphPictureData* picture)
{
assert(picture);
GLenum target = GL_TEXTURE_2D;
GLenum level = 0;
GLsizei width = picture->m_uiPixelWidth;
GLsizei height = picture->m_uiPixelHeight;
GLint border = 0;
GLenum type = GL_UNSIGNED_BYTE;
GLint internalformat;
GLenum format;
switch(picture->m_eFormat) {
case kA3DPictureBitmapGreyByte: internalformat = GL_RED; format = GL_RED_INTEGER; break;
case kA3DPictureBitmapGreyaByte: internalformat = GL_RG; format = GL_RG_INTEGER; break;
case kA3DPictureBitmapRgbByte: internalformat = GL_RGB; format = GL_RGB_INTEGER; break;
case kA3DPictureBitmapRgbaByte: internalformat = GL_RGBA; format = GL_RGBA_INTEGER; break;
default: return A3D_ERROR;
}
glTexImage2D(target, level, internalformat,
width, height, border,
format, type, picture->m_pucBinaryData
);
return A3D_SUCCESS;
}
Complex format
m_pucBinaryData can contains encoded BMP, PNG or JPEG data accoring to the value of m_eFormat. In those cases, the dimension of the picture is part of the data. Thus m_uiPixelWidth and m_uiPixelHeight are set to 0.
Memory management
The content of m_pucBinaryData is allocated from the heap. When creating a picture instance, you are responsible for the management of its memory. When inserting a new A3DGraphPictureData instance into the global state using #A3DGlobalInsertGraphPicture, the content of m_pucBinaryData is cloned for internal use.
See also
A3DGlobalGetGraphPictureData
A3DGlobalInsertGraphPicture
A3DGraphTextureDefinitionData
A3DGlobalInsertGraphTextureDefinition
#define A3D_INITIALIZE_DATA(MAC_TYPE, MAC_VALUE)
Definition: A3DSDKInitializeFunctions.h:31
@ A3D_ERROR
Definition: A3DSDKErrorCodes.h:86
A3DUns8 * m_pucBinaryData
Image binary data.
Definition: A3DSDKGraphics.h:957
@ kA3DPictureBitmapRgbByte
Definition: A3DSDKEnums.h:2420
A3DEPictureDataFormat m_eFormat
Image format specifier.
Definition: A3DSDKGraphics.h:955
A3DUns32 m_uiSize
The size of m_pucBinaryData in bytes.
Definition: A3DSDKGraphics.h:956
@ kA3DPictureBitmapGreyaByte
Definition: A3DSDKEnums.h:2423
A3DUns32 m_uiPixelHeight
Image height in pixels. If picture dimension is part of m_pucBinaryData, this field is 0.
Definition: A3DSDKGraphics.h:959
@ kA3DPictureBitmapGreyByte
Definition: A3DSDKEnums.h:2422
@ kA3DPictureBitmapRgbaByte
Definition: A3DSDKEnums.h:2421
unsigned int A3DUns32
Definition: A3DSDKTypes.h:47
@ A3D_SUCCESS
Definition: A3DSDKErrorCodes.h:85
A3DStatus
Error Codes.
Definition: A3DSDKErrorCodes.h:71
A description of a two-dimensional picture.
Definition: A3DSDKGraphics.h:952
A3DUns32 m_uiPixelWidth
Image width in pixels. If picture dimension is part of m_pucBinaryData, this field is 0.
Definition: A3DSDKGraphics.h:958