kmLoadTextureBlock

Loads texture data blocks.


KMSTATUS KMAPI
kmLoadTextureBlock(
IN PKMSURFACEDESC pSurfaceDesc,
IN PKMDWORD pTexture,
IN KMUINT32 nBlockNum,
IN KMUINT32 nBlockSize
)

Description:

This function loads texture blocks from a main memory area specified by pTexture into a texture memory area allocated using kmCreateTextureSurface/kmCreateCombinedTextureSurface/ kmCreateContiguousTextureSurface/kmCreateFixedTextureArea.

Texture data is divided into blocks before it is loaded. It makes it possible to load large texture data without allocating a large work area in main memory.
To load texture data by dividing it in BUFFSIZE*32 byte units, for example, code the following:

i = 0;
Load the first BUFFSIZE*32 byte block into pTexture;
while(KMSTATUS_SUCCESS == kmLoadTextureBlock(
	&TexSurfaceDesc,
	pTexture,
	i++,
	BUFFSIZE
	)) {
		Load the next BUFFSIZE*32 byte block into pTexture;
	}


Even if the size of the whole texture data is not an integer multiple of the block size, loading is performed normally. It is impossible to change the BUFFSIZE value in a loop in which one set of texture blocks is being loaded. If the value is changed, the texture display becomes illegal.

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

nBlockNum(input)
Specify a texture block number from 0 to n (n varies with the format and size).

nBlockSize(input)
Specify the size of a texture block in 32-byte units, that is, an actual block size (in bytes) divided by 32. Even if the size of the entire texture block is not an integer multiple of the block size, loading is performed normally.

Return values:

ValueExplanation
KMSTATUS_SUCCESS Read successfully.
KMSTATUS_INVALID_BLOCKNUMBER Illegal block number.
KMSTATUS_INVALID_ADDRESS Specified area (Surface) not allocated.
KMSTATUS_INVALID_TEXTURE_TYPE Invalid texture type specified.

  kmLoadTextureBlock