kmLoadRectangleTexturePart
Transfers rectangular area of texture data.
Description:
This function writes the rectangular area (partial) of texture data in the main memory specified by pTexture, to the rectangular texture area in the Rectangle/Stride format in the frame buffer memory secured by kmCreateTextureSurface/kmCreateCombinedTextureSurface/
kmCreateContiguousTextureSurface/kmCreateFixedTextureArea.
This allows part of the texture in the Rectangle/Stride format to be updated.
The rectangular area of the transfer destination is ( dst_X, dst_Y )-( dst_X + width, dst_Y + height ).
The rectangular area of the transfer source is ( src_X, src_Y )-( src_X + width, src_Y + height ).
(See the figure below.)
If src_U is set to zero, the size of the texture of the transfer source is regarded as same as the width and height of the rectangular area.
In this case, src_X and src_Y will be ignored.
(See the figure below.)
If the address of the left texel of the rectangular area data in the system memory has a 32-byte alignment and its size is multiple of 32 bytes, the data transfer will employ DMA. High-speed transfer will become possible.
If the DMA mode is used to transfer texture data, it is possible to select whether to wait until
the transfer ends. If kmSetSystemConfiguration sets the
KM_CONFIGFLAG_NOWAIT_FINISH_TEXTUREDMA flag, the function ends without
waiting for the completion of a DMA transfer. In this case, the
kmQueryFinishLastTextureDMA function can be used to check for the end of DMA
transfer.
If the CPU directly rewrites texture data into main memory before it is loaded, it is necessary
to purge the cache before executing the load function in order to maintain cache coherency.
(Specifically, execute the SH4 ocbwb instruction.)
This function supports only Rectangle/Stride format texture.
If pSurfaceDesc of any other format is specified, KMSTATUS_INVALID_TEXTURE_TYPE is returned.
The rectangular area must fall completely within the texture area of both transfer destination and transfer source.
If this is not the case, texture data including the one in the transfer destination may become corrupted.
Note that Kamui does not check for this problem.
Parameters:
pSurfaceDesc(input)
Texture surface in the Rectangle/Stride format secured by kmCreateTextureSurface/
kmCreateCombinedTextureSurface/kmCreateContiguousTextureSurface/kmCreateFixedTextureArea.
This parameter is a pointer to KMSURFACEDESC-type structure.
pTexture(input)
This parameter is a pointer to the pixel data portion of the texture in main memory.
width, height(input)
These parameters specify the width and height of the rectangular area to transfer, in number of texels.
dst_X, dst_Y(input)
The X- and Y-coordinates of the rectangular area of the texture in the transfer destination.
They are specified using relative number of texels from the lower left (leading) texel of the texture in the transfer destination.
src_X, src_Y(input)
The X- and Y-coordinates of the rectangular area of the texture in the transfer source. They are specified using relative number of texels from the lower left (leading) texel of the texture in the transfer source.
src_U(input)
Specifies the width of the texture in the transfer source, in number of texels.
If it is zero, the size of the texture of the transfer source is regarded as same as the width and height of the rectangular area.
In this case, src_X and src_Y will be ignored (regarded as zero).
Return values:
Value | Explanation |
---|---|
KMSTATUS_SUCCESS | Success |
KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture specified. |
kmLoadRectangleTexturePart