Function Name: Get Image Data

Definition

Copies the selected texels from the selected area of interest of the given Image into a space in memory that the user has direct access to. All memory for the data is allocated within the store provided by the caller. See the comments for the function SE_CreateStore() for details on the function and behavior of stores.

An Image is a set of 2-D or 3-D collections of texel values. The number of MIP levels for the Image defines the number of 2- or 3-D 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.

Returns

SE_NULL_REQUIRED_PARAMETER - if data_out_ptr was NULL. In this case, *data_out_ptr is unaffected.

SE_INVALID_OR_NULL_OBJECT - if image is not a handle to a valid, active (i.e., unfreed) Image object. In this case, *data_out_ptr is set to NULL.

SE_UNRESOLVED_OBJECT - if image is an unresolved object (see SE_OBJECT's comments for details on how this condition occurs). In this case, *data_out_ptr is set to NULL.

SE_INVALID_OR_NULL_STORE - if store_in is not a handle to a valid SE_STORE created by SE_CreateStore(). In this case, *data_out_ptr is set to NULL.

SE_FAILURE - (*data_out_ptr is set to NULL) if

1. no image data has yet been specified for the given Image, or
2. if mip_level is invalid for the Image, or
3. if the Image's level_count is zero or its mip_fields_array is NULL, or
4. if any of the start or stop texels were invalid for the Image, or
5. the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

Prototype

Parameters Notes

image

 the <Image> object whose texels are being retrieved.

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

store_in

 a handle to a store. The API allocates memory for the requested
    data within this store.

data_out_ptr

 a pointer to a block of memory containing the returned
    data. The API allocates memory for the requested data and sets this
    parameter to point to it.