SE PutImageData

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

extern SE_Return_Code
SE_PutImageData
(
	SE_Object		image,	¹
const	SE_Image_Texel_Location_3D	*	start_texel,	²
const	SE_Image_Texel_Location_3D	*	stop_texel,	³
	SE_Short_Integer_Unsigned		mip_level,	⁴
const	SE_Image_Data	*	data_in_ptr	⁵
);

Definition

This function copies the selected texels from a buffer into the selected area of interest of the given <Image> instance.

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.

The transmittal whose object is to be edited must be explicitly opened in UPDATE mode for this operation to succeed.

Returns

SE_RETCOD_SUCCESS	and the data is stored in the tranmittal.
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 is not a currently resolved object (see SE_Object's comments for details on how this condition occurs).
SE_STATCODE_INVALID_ACCESS_MODE	set if image belongs to a transmittal that was opened in read-only mode.
SE_STATCODE_INACTIONABLE_FAILURE	set if any of the following conditions are encountered: image does not belong to an open transmittal, mip_level is out of range for image's level_count, image's mip_extents_array is NULL, the start and stop extents are out of range for the specified mip_level, or stop > start for any of the extents, the API implementation specified does not provide this function in its shared library, and dynamic binding is specified at compile time, a partial image is specified.

Parameters Notes

¹ the <Image> object whose texels are being created.

² 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 the <Image> to which the data will be written. Each <Image> has at least one MIP level. Many <Image>s have multiple MIP levels. Data can only be written to one mip level at a time (only one MIP level per SE_PutImageData() call).

⁵ a pointer to byte_count bytes of memory, allocated in the user's memory space, containing the values to be output. 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 it during this function call.