kmLoadTexturePart

Loads part of texture data.


KMSTATUS KMAPI
kmLoadTexturePart(
IN PKMSURFACEDESC pSurfaceDesc,
IN PKMDWORD pTexture,
IN KMUINT32 nOffset,
IN KMUINT32 nSize
)

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:

ValueExplanation
KMSTATUS_SUCCESS Success
KMSTATUS_INVALID_ADDRESS nOffset greater than the texture size.
KMSTATUS_INVALID_TEXTURE_TYPE Invalid texture type specified.

  kmLoadTexturePart