Definition

Copies the selected texels from a buffer into the selected area of interest of the given <Image>.

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.

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

Returns

SE_STAT_CODE_SUCCESS	and the texels of image are created as specified, if valid parameters were passed in and all operations succeeded.
SE_STAT_CODE_NULL_REQUIRED_PARAMETER	and image is unaffected, if data_in_ptr is NULL.
SE_STAT_CODE_INVALID_OR_NULL_OBJECT	and image is unaffected, if image is not a handle to a valid, active (i.e., unfreed), saved <Image>.
SE_STAT_CODE_UNRESOLVED_OBJECT	and image is unaffected, if image is not a currently resolved object (see SE_Object's comments for details on how this condition occurs).
SE_STAT_CODE_INVALID_ACCESS_MODE	and image is unaffected, if image belongs to a transmittal that was opened in read-only mode.
SE_STAT_CODE_FAILURE	and image is unaffected, 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 ($$$ not yet supported).

Parameters Notes

image

 the <Image> object whose texels are being created.

start_texel_horizontal

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

byte_count

 the amount of memory occupied by the <Image> data being
    written.  The number of texels is determined by the above start and
    stop indices.  The number of bits per texel, and the number of bits
    needed to pad each row of texels, if any, is defined by the definition
    of the <Image>.  The user must calculate and pass in the appropriate
    byte count as a safeguard in an attempt to ensure that the user
    allocated the correct amount of memory for the data_in_ptr pointer.

data_in_ptr

 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.

Prev: SE_PutFields. Next: SE_PutPackedDataTable. Up:Index.

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