kmLoadVQCodebook
Re-reads the code book portion of VQ texture.
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:
Value | Explanation |
---|---|
KMSTATUS_SUCCESS | Success |
KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture surface specified |
kmLoadVQCodebook