kmLoadTexture

Loads texture data.


KMSTATUS KMAPI
kmLoadTexture(
IN PKMSURFACEDESC pSurfaceDesc,
IN PKMDWORD pTexture
)

Description:

This function loads the texture on main memory specified by pTexture into the texture memory area allocated by kmCreateTextureSurface/kmCreateCombinedTextureSurface/kmCreateContiguousTextureSurface/ kmCreateFixedTextureArea. The format and size of the texture to be read are identified by the surface descriptor specified by pSurfaceDesc. If the actual format and size of the texture are different from the contents of the surface descriptor specified by pSurfaceDesc, the display is illegal.

If the start address of texture data in system memory is aligned with 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 in 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.)

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). If this address is not on a 32-byte boundary, DMA transfer cannot be used, resulting in the processing being slow.

Return values:

ValueExplanation
KMSTATUS_SUCCESS Read successfully.
KMSTATUS_INVALID_ADDRESS The specified area (Surface) is not allocated.
KMSTATUS_INVALID_TEXTURE_TYPE Invalid texture type specified.

  kmLoadTexture