SE GetImageData

SEDRIS Reference Manual APPENDIX A - Transmittal Access Level 0 API Functions SE GetImageData

extern SE_Return_Code
SE_GetImageData
(
	SE_Object		image_object,	¹
const	SE_Image_Texel_Location_3D	*	start_texel,	²
const	SE_Image_Texel_Location_3D	*	stop_texel,	³
	SE_Short_Integer_Unsigned		mip_level,	⁴
	SE_Store		store,	⁵
	SE_Image_Data	*	image_data	⁶
);

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_RETCOD_SUCCESS	and the requested image data is returned
SE_RETCOD_FAILURE	and the status code is set appropriately if the call failed.

Status Codes

SE_Status_Code(s) when SE_RETCOD_SUCCESS is returned:

SE_STATCODE_SUCCESS

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

SE_Status_Code(s) when SE_RETCOD_FAILURE is returned:

SE_STATCODE_UNRESOLVED_OUTPUT_OBJECT	set if image_object is an unresolved object (see SE_Object's comments for details on how this condition occurs).
SE_STATCODE_C_STORE_INVALID	set if store is not a handle to a valid SE_Store.
SE_STATCODE_INACTIONABLE_FAILURE	set if no image data has yet been specified for image_object, or mip_level is invalid for image_object, or image_object's level_count is zero or its mip_extents_array is NULL, or start_texel or stop_texel was invalid for image_object, or the call fails for any other reason.

Parameters Notes

¹ the <Image> instance whose texels are being retrieved.

² the starting texel index of the <Image> instance data to be retrieved; must be less than or equal to stop_texel, and must be valid for the specified MIP level of image.

³ the stopping texel index of the <Image> instance data to be retrieved; must be greater than or equal to start_texel, and must be valid for the specified MIP level of image.

⁴ the MIP level of image from which the data will be returned. Each <Image> instance has at least one MIP level. Many <Image> instances have multiple MIP levels. Data can only be retrieved from one mip level at a time (only one MIP level per SE_GetImageData() call).

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

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