gl.GetTexImageRaw(target, level, format, type, pixels)
gl.GetTexImageRaw()
writes the pixels of a texture image to pixels
. This must be a memory
buffer allocated by Hollywood's AllocMem()
function and returned by GetMemPointer()
. To determine the
required size of pixels
, use gl.GetTexLevelParameter() to determine
the dimensions of the internal texture image, then scale the required number of pixels by the storage
required for each pixel, based on format
and type
. Be sure to take the pixel storage parameters into
account, especially #GL_PACK_ALIGNMENT
.
The supported values for format
are #GL_RED
, #GL_GREEN
, #GL_BLUE
, #GL_ALPHA
, #GL_RGB
, #GL_RGBA
, #GL_LUMINANCE
,
and #GL_LUMINANCE_ALPHA
.
Supported data types for type
are #GL_UNSIGNED_BYTE
, #GL_BYTE
, #GL_UNSIGNED_SHORT
, #GL_SHORT
, #GL_UNSIGNED_INT
,
#GL_INT
, and #GL_FLOAT
.
The pixels are written to the memory buffer as values of type type
. target
specifies whether the
desired texture image is one specified by gl.TexImage1D() (#GL_TEXTURE_1D
) or
gl.TexImage2D() (#GL_TEXTURE_2D
). level
specifies the level-of-detail number
of the desired image. format
specifies the format of the desired image array.
See gl.TexImage2D for a description of the acceptable values for the format parameter.
To understand the operation of gl.GetTexImageRaw()
, consider the selected internal four-component texture
image to be an RGBA color buffer the size of the image. The semantics of gl.GetTexImageRaw()
are then
identical to those of gl.ReadPixels(), with the exception that no pixel
transfer operations are performed, when called with the same format and type, with x and y set to 0,
width set to the width of the texture image (including border if one was specified), and height set
to 1 for 1D images, or to the height of the texture image (including border if one was specified) for
2D images. Because the internal texture image is an RGBA image, pixel formats #GL_COLOR_INDEX
, #GL_STENCIL_INDEX
,
and #GL_DEPTH_COMPONENT
are not accepted, and pixel type #GL_BITMAP
is not accepted.
If the selected texture image does not contain four components, the following mappings are applied. Single-component textures are treated as RGBA buffers with red set to the single-component value, green set to 0, blue set to 0, and alpha set to 1. Two-component textures are treated as RGBA buffers with red set to the value of component zero, alpha set to the value of component one, and green and blue set to 0. Finally, three-component textures are treated as RGBA buffers with red set to component zero, green set to component one, blue set to component two, and alpha set to 1.
If you want to have the pixels returned in a table instead of a memory buffer, you can use the gl.GetTexImage() function instead. See Working with pointers for details on how to use memory pointers with Hollywood.
Please consult an OpenGL reference manual for more information.
#GL_TEXTURE_1D
or #GL_TEXTURE_2D
)#GL_INVALID_ENUM
is generated if target
, type
or format
is not an accepted value.
#GL_INVALID_VALUE
is generated if level
is less than zero or greater than ld(max), where max
is the returned value of #GL_MAX_TEXTURE_SIZE
.
#GL_INVALID_OPERATION
is generated if gl.GetTexImageRaw()
is called between a call to glBegin and the corresponding call to glEnd.
#GL_TEXTURE_WIDTH
gl.GetTexLevelParameter() with argument #GL_TEXTURE_HEIGHT
gl.GetTexLevelParameter() with argument #GL_TEXTURE_BORDER
gl.GetTexLevelParameter() with argument #GL_TEXTURE_COMPONENTS
gl.Get() with arguments #GL_PACK_ALIGNMENT
and others