A3DGraphPictureData

Fields

`A3DEPictureDataFormat`	`m_eFormat`
`A3DUns32`	`m_uiSize`
`A3DUns8` *	`m_pucBinaryData`
`A3DUns32`	`m_uiPixelWidth`
`A3DUns32`	`m_uiPixelHeight`

Detailed Description

struct A3DGraphPictureData

A description of a two-dimensional picture.

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.

Version: 2.0

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

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

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 following code describes an RGB 255x100 image with a color fading from red to green:

A3DGraphPictureData picture;
A3D_INITIALIZE_DATA(A3DGraphPictureData, picture);
picture.m_eFormat = kA3DPictureBitmapRgbByte;
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;
}

See also

A3DGlobalGetGraphPictureData

See also

A3DGlobalInsertGraphPicture

See also

A3DGraphTextureDefinitionData

See also

A3DGlobalInsertGraphTextureDefinition

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.

Public Members

A3DEPictureDataFormat m_eFormat: Image format specifier.

A3DUns32 m_uiSize: The size of m_pucBinaryData in bytes.

A3DUns8 *m_pucBinaryData: Image binary data.

A3DUns32 m_uiPixelWidth: Image width in pixels. If picture dimension is part of m_pucBinaryData, this field is 0.

A3DUns32 m_uiPixelHeight: Image height in pixels. If picture dimension is part of m_pucBinaryData, this field is 0.