Definition

This function copies the selected texels from the selected area of interest of the given <Image> instance 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 behaviour of stores.

An <Image> instance is a set of 2-D or 3-D collections of texel values. The number of MIP levels for the <Image> instance defines the number of 2- or 3-D collections in the <Image> instance. The definition of the <Image> instance 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_RET_CODE_SUCCESS	and the requested image data is returned
SE_RET_CODE_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RET_CODE_SUCCESS is returned:

SE_STAT_CODE_SUCCESS

set if valid parameters were passed in and all operations succeeded.

SE_Status_Code(s) when SE_RET_CODE_FAILURE is returned:

SE_STAT_CODE_UNRESOLVED_OUTPUT_OBJECT	set if image is an unresolved object (see SE_Object's comments for details on how this condition occurs).
SE_STAT_CODE_INACTIONABLE_FAILURE	set 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 call fails for any other reason.

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_GetFields. Next: SE_GetIterationLengthRemaining. Up:Index.

Last updated: July 16, 2004 Copyright © 2004 SEDRIS™