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_STAT_CODE_SUCCESS	and the appropriate values are placed in *data_out_ptr, if valid parameters were passed in.
SE_STAT_CODE_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_STAT_CODE_FAILURE	and *data_out_ptr is not affected, if image_fields_ptr is invalid, if any start or stop texels were invalid for image_fields_ptr, desired_image_parameters_ptr is invalid, if data_out_byte_count does not equal the computed number of bytes in the output image, the source image signature (in image_fields_ptr) is invalid, or if the requested image is a floating-point image in which one of the texel components is computed to be neither SE_Float nor SE_Long_Float

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
    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 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
    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.

Prev: SE_PrintDesiredImageParameters. Next: SE_RemoveObjectAndLinks. Up:Index.

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