kmLoadVQCodebook

Re-reads the code book portion of VQ texture.


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

Description:

This function reads only the code book portion of the VQ or small VQ texture in main memory as specified by pTexture to the VQ or small VQ texture surface specified by pSurfaceDesc. It is used to rewrite only the code book of the VQ or small VQ texture already loaded and use the color palette effect.

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 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.)

Parameters:

pSurfaceDesc(input)
Texture surface allocated by kmCreateTextureSurface/kmCreateCombinedTextureSurface/ kmCreateContiguousTextureSurface/kmCreateFixedTextureArea. This parameter is a pointer to KMSURFACEDESC-type structure. The category of this surface must be one of the following types:

KM_TEXTURE_VQ
KM_TEXTURE_VQ_MM
KM_TEXTURE_SMALLVQ
KM_TEXTURE_SMALLVQ_MM


pTexture(input)
This parameter is a pointer indicating a texture (code book) in main memory. Specify an address aligned with a 32-byte boundary. This does not have to be in the complete VQ or small VQ texture format, but a code book (its size in bytes is indicated below) must be included in the beginning.

The following table lists the relationships between the texture size and code book size.
Texture Type/Size Codebook Size (byte)
VQ / VQ mipmap 0x800
16x16 small VQ 0x80
16x16 small VQ mipmap 0x80
32x32 small VQ 0x100
32x32 small VQ mipmap 0x200
64x64 small VQ 0x400

Return values:

ValueExplanation
KMSTATUS_SUCCESS Success
KMSTATUS_INVALID_TEXTURE_TYPE Invalid texture surface specified

  kmLoadVQCodebook