Function Name: Get Rearranged Image Data

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_NULL_REQUIRED_PARAMETER - if data_out_ptr or desired_image_parameters_ptr was NULL. In this case, *data_out_ptr is not affected.

SE_INVALID_OR_NULL_OBJECT - if image was not a handle to a valid, active (i.e., unfreed), saved <Image> object. In this case, *data_out_ptr is not affected.

SE_UNRESOLVED_OBJECT - if image is unresolved. In this case, *data_out_ptr is not affected.

SE_OUT_OF_MEMORY - if memory allocation failed during an intermediate operation. In this case, *data_out_ptr is not affected.

SE_FAILURE - *data_out_ptr is not affected, if

1. no image data has yet been specified for the given <Image>,
2. if level_count or mip_fields_array are NULL in the given <Image>,
3. the <Image>'s fields are otherwise invalid or cannot be retrieved,
4. mip_level is out of range for the given <Image>, or
5. any start or stop texels were invalid for the <Image>, or
6. desired_image_parameters_ptr is invalid,
7. the size of the mip_level of the <Image> cannot be computed
8. the texels of the <Image> cannot be retrieved,
9. the byte_count is not correct for the given extents and the texels of this <Image>.

Prototype

Parameters Notes

image

 the <Image> object

start_texel_horizontal

 the starting extents (texel indices) of the <Image> data to be retrieved.
     For a 2-dimensional <Image>, start_texel_z will be ignored.

stop_texel_horizontal

 the stopping extents (texel indices) of the <Image> data to be retrieved.
 For a 2-dimensional <Image>, stop_texel_z will be ignored.

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.