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_STAT_CODE_SUCCESS	and memory for the requested data is allocated within the store associated with store_in, and the requested data is copied into that memory (which is pointed to by data_out_ptr), if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and *data_out_ptr is unaffected, if data_out_ptr was NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and *data_out_ptr is set to NULL, if image is not a handle to a valid, active (i.e., unfreed) <Image> instance.
SE_STAT_CODE_UNRESOLVED_OBJECT	and *data_out_ptr is set to NULL, if image is an unresolved object (see SE_Object's comments for details on how this condition occurs).
SE_STAT_CODE_INVALID_OR_NULL_STORE	and *data_out_ptr is set to NULL, if store_in is not a handle to a valid SE_Store created by SE_CreateStore().
SE_STAT_CODE_FAILURE	and *data_out_ptr is set to NULL, if no image data has yet been specified for image, or mip_level is invalid for image, or image's level_count is zero or its mip_extents_array is NULL, or any of the start or stop texels were invalid for image, or the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time.

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.

Prev: SE_GetIDForObject. Next: SE_GetImplementationIdentifier. Up:Index.

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