Function Name: Rearrange Image Data

Definition

Used by SE_GetRearrangedImageData() to rearrange the image data as specified by the SE_DESIRED_IMAGE_PARAMETERS structure. It is exposed to the user so that image data previously obtained by a call to SE_GetRearrangedImageData() or SE_GetImageData() (or even user-created image data) can be rearranged without a new call to the functions mentioned above.

This function requires information about how the image data passed in is arranged. Consequently, the user must fill and pass in an appropriate SE_IMAGE_FIELDS structure by either an explicit allocation or by obtaining one from an Image object (this last is what the function SE_GetRearrangedImageData does).

This function only rearranges the specified mip_level.

Returns

SE_NULL_REQUIRED_PARAMETER - and *data_out_ptr is not affected, if image_fields_ptr, data_in_ptr, data_out_ptr, or desired_image_parameters_ptr is NULL.

SE_FAILURE - and *data_out_ptr is not affected,

1. if image_fields_ptr is invalid,
2. if any start or stop texels were invalid for image_fields_ptr,
3. desired_image_parameters_ptr is invalid,
4. if data_out_byte_count does not equal the computed number of bytes in the output image,
5. the source image signature (in image_fields_ptr) is invalid, or
6. if the requested image is a floating-point image in which one of the texel components is computed to be neither SE_FLOAT32 nor SE_FLOAT64

Prototype

Parameters Notes

image_fields_ptr

 the fields of the <Image> whose data is pointed to by data_in_ptr;
 this structure describes how the data pointed to by the data_in_ptr
 is organized.

data_in_byte_count

 the amount of memory in bytes to which data_in_ptr is pointing.
 The user must pass in this argument as a safe-guard in an attempt
 to ensure that the image data pointed to by the data_in_ptr is
 compatible with the fields of the image data.

data_in_ptr

   the source image data (possibly obtained from SE_GetImageData()); a
     pointer to data_in_byte_count bytes of memory, already allocated in the
     user's memory space, which contain the image data to be rearranged. This
     memory space is entirely under the user's control.  The only time the
     API accesses this memory is when the API reads the image data during
     this function call.

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_z

 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 image data that was passed in.

data_out_byte_count

 the amount of memory, in bytes, to which data_out_ptr is pointing,
 which will be occupied by the image data requested.  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

  the results; a pointer to data_out_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.