kmLoadTexturePart
Loads part of texture data.
Description:
This function loads texture portions from a main memory area specified by pTexture into
a texture memory area allocated using kmCreateTextureSurface/kmCreateCombinedTextureSurface/
kmCreateContiguousTextureSurface/kmCreateFixedTextureArea.
Texture data is divided into portions before it is loaded. This makes it possible to load a
large amount of texture data without allocating a large work area in main memory.
Unlike kmLoadTextureBlock, kmLoadTexturePart can load one texture data item
by dividing it into portions of different sizes. The user is responsible for managing the size
(offset from the beginning of the texture data) of each texture portion that has already been
loaded.
Example:
nOffset = 0; nSize = ***; Load the first nSize byte portion of texture data into an area specified by pTexture; while(KMSTATUS_SUCCESS == kmLoadTexturePart(...)) { nOffset = nOffset + nSize; nSize = ????; Load the next nSize byte portion into an area specified by pTexture; }
The format and size of the texture data to be loaded are identified by the surface descriptor
specified by pSurfaceDesc. If the actual format and size of the texture data are different
from the contents of the surface descriptor specified by pSurfaceDesc, the display
becomes illegal.
If the start address of texture data in system memory is on a 32-byte boundary, and its size is
a multiple of 32 bytes, the DMA mode is used to transfer the texture data to texture memory,
so that high-speed transfer becomes 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 does not support texture data of Small VQ format. If pSurfaceDesc of Small VQ format is specified, KMSTATUS_INVALID_TEXTURE_TYPE is returned.
Parameters:
pSurfaceDesc(input)
Texture surface allocated 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. The address specified for
this pointer is the first address of the texture file of KAMUI texture format + 16. Specify an
address aligned with a 32-byte boundary (16 bytes of the header portion of KAMUI are
skipped).
nOffset(input)
Specify the size of the texture data portion that has already been loaded (the offset from the
beginning of the entire texture data) in byte units. This size must be an integer multiple of 4,
because it is used to obtain the address of the transfer destination texture area in frame buffer
memory.
nSize(input)
Specify the size of the texture data portion to be loaded, in byte units. This size must be an
integer multiple of 4. If nSize is greater than the size of the remaining texture portion (=
texture size - nOffset), texture data loading is completed by loading only the rest of the
texture data.
Return values:
Value | Explanation |
---|---|
KMSTATUS_SUCCESS | Success |
KMSTATUS_INVALID_ADDRESS | nOffset greater than the texture size. |
KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture type specified. |
kmLoadTexturePart