Function Name: Get Size Of Image Data

Definition

Computes the number of bytes needed in order to store a sub-image of the given texel extents.

This function can be used to determine how much space to allocate for a call to the level 0 API function SE_GetImageData().

An Image is a set of 2 or 3 dimensional collections of texel values. The number of MIP levels for the <Image> defines the number of 2 or 3 dimensional 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 byte_count_out_ptr was NULL. In this case, *byte_count_out_ptr is not affected.

SE_INVALID_OR_NULL_OBJECT - if the image passed in is not a handle to a valid, active (i.e., unfreed) <Image>. In this case, *byte_count_out_ptr is set to zero (0).

SE_UNRESOLVED_OBJECT - if image is unresolved. In this case, *byte_count_out_ptr is set to zero (0).

SE_FAILURE - and *byte_count_out_ptr is set to zero (0), if

1. if level_count or mip_fields_array are NULL in the given <Image>,
2. the <Image>'s fields are otherwise invalid or cannot be retrieved,
3. mip_level is out of range for the given <Image>, or
4. any start or stop texels were invalid for the <Image>.

Prototype

Parameters Notes

image

 the <Image> object

start_texel_horizontal

 the starting extents (texel indices) of the <Image> data to be
 retrieved.  For a 2-dimensional <Image>, start_texel_z will be ignored.

stop_texel_horizontal

 the stopping extents (texel indices) of the <Image> data to be
 retrieved.  For a 2-dimensional <Image>, stop_texel_z will be ignored.

mip_level

 the MIP level of the <Image> from which the data size will be
 returned.  Each <Image> has at least one MIP level.  Many Images have
 multiple MIP levels.  Data sizes can only be retrieved from one MIP
 level at a time (only one MIP level per SE_GetSizeOfImageData() call).

byte_count_out_ptr

 a pointer to the variable in the user's memory space where the number
 of bytes needed to store the specified sub-image will be stored.