Definition

Copy (rearranging and sampling as necessary) the selected texels from the selected area of interest of the given Image into a space in memory that the user has already allocated to hold this data.

An <Image> is a set of 2- or 3-dimensional collections of texel values. The number of MIP levels for the <Image> defines the number of 2- or 3- dimensional collections in the <Image>. The definition of the <Image> will define the number of texels in each MIP level and the number of bits (not just bytes, but bits) for each texel.

NOTE: The first 8 parameters are identical to those of the Level 0 Read API SE_GetImageData() function.

Returns

SE_STAT_CODE_SUCCESS	and image's texels are retrieved and copied into data_out_ptr in the specified manner, if valid parameters were passed in and all operations succeeded. (The original texels of image itself are unaffected.)
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and no changes are made, if data_out_ptr or desired_image_parameters_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *data_out_ptr is left unaltered, if image was not a handle to a valid, active (i.e., unfreed), saved <Image>> instance.
SE_STAT_CODE_UNRESOLVED_OBJECT	and *data_out_ptr is left unaltered, if image is unresolved.
SE_STAT_CODE_OUT_OF_MEMORY	and *data_out_ptr is left unchanged, if memory allocation failed during an intermediate operation.
SE_STAT_CODE_FAILURE	*data_out_ptr is not affected, if no image data has yet been specified for the image, if level_count or mip_extents_array are NULL in the image, the image's fields are otherwise invalid or cannot be retrieved, mip_level is out of range for the image, or any start or stop texels were invalid for the image, or desired_image_parameters_ptr is invalid, the size of the mip_level of the image cannot be computed the texels of the image cannot be retrieved, the byte_count is not correct for the given extents and the texels of this image.

Parameters Notes

image

 the <Image> instance

start_texel_horizontal

 the starting texel index (horizontal) of the
    <Image> data to be retrieved; must be less than or equal to
    stop_texel_horizontal, and must be valid for the specified MIP level
    of the <Image>.

start_texel_vertical

 the starting texel index (vertical) of the
    <Image> data to be retrieved; must be less than or equal to
    stop_texel_vertical, and must be valid for the specified MIP level
    of the <Image>.

start_texel_z

 the starting texel index (z) of the <Image> data to be
    retrieved; must be less than or equal to stop_texel_z. For a 2-D
    <Image>, start_texel_z will be ignored; otherwise, it must be valid for
    the specified MIP level of the <Image>.

stop_texel_horizontal

 the stopping texel index (horizontal) of the
    <Image> data to be retrieved; must be greater than or equal to
    start_texel_horizontal, and must be valid for the specified MIP level
    of the <Image>.

stop_texel_vertical

 the stopping texel index (vertical) of the
    <Image> data to be retrieved; must be greater than or equal to
    start_texel_vertical, and must be valid for the specified MIP level
    of the <Image>.

stop_texel_z

 the stopping texel index (z) of the <Image> data to be
    retrieved; must be greater than or equal to start_texel_z. For a 2-D
    <Image>, stop_texel_z will be ignored; otherwise, it must be valid for
    the specified MIP level of the <Image>.

mip_level

 the MIP level of the <Image> from which the data will be
    returned.  Each <Image> has at least one MIP level.  Many <Images> have
    multiple MIP levels.  Data can only be retrieved from one MIP level
    at a time (only one MIP level per SE_GetImageData() call).

desired_image_parameters_ptr

 a pointer to a structure containing the
    "rearranging" parameters that the user must supply to rearrange the data
    of the <Image> object which was passed in.

byte_count

 the amount of memory that will be occupied by the <Image>
    data requested (i.e., the number of bytes to which data_out_ptr is
    pointing).  The number of texels is determined by the above start
    and stop indices.  The number of bits per texel is defined by the user's
    requests.  The user must calculate and pass in the appropriate byte
    count as a safe-guard in an attempt to ensure that the user allocated
    the correct amount of memory for the data_out_ptr pointer.

data_out_ptr

 a pointer to byte_count bytes of memory, already allocated
    in the user's memory space, which will be filled by this function with
    the appropriate values.  This memory space is entirely under the user's
    control.  The only time the API accesses this memory is when the API
    copies data into the memory during this function call.

Prev: SE_GetGeometrySameAsID. Next: SE_GetSizeOfDataTableData. Up:Index.

Last updated: May 15, 2003 Copyright © 2003 SEDRIS™