kmReLoadMipmap

Reloads a particular mipmap texture.


KMSTATUS KMAPI
kmReLoadMipmap(
IN PKMSURFACEDESC pSurfaceDesc,
IN PKMVOID pTexture
IN KMINT32 nMipmapCount
)

Description:

This function overwrites the mipmap texture on main memory specified by pTexture and loads it into the texture memory area allocated by kmCreateTextureSurface/ kmCreateCombinedTextureSurface/kmCreateContiguousTextureSurface/kmCreateFixedTextureArea. The type of the texture (surface) that can be specified is one of the following types:

KM_TEXTURE_TWIDDLED_MM
KM_TEXTURE_VQ_MM
KM_TEXTURE_PALETTIZE4_MM
KM_TEXTURE_PALETTIZE8_MM
KM_TEXTURE_SMALLVQ_MM


The format and size of the texture to be read are identified by the surface descriptor specified by pSurfaceDesc.

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

Since no DMA transfer can be used, this function is slower than kmLoadTexture. This is because, in texture data transfer by the function, the address of the data transfer source and destination areas is not necessarily on a 32-byte boundary.

The correct picture is not displayed if the code book at the reloading destination and that at the reloading source coincide when reloading VQ- Mipmap. Nothing is performed if 1 x 1 Mipmap is specified when reloading VQ-Mipmap.

The correct picture is not displayed if the texture palette data at the reloading destination and that at the reloading source coincide when reloading Palettized-Mipmap.

[Reference]
Offset from the beginning of Twiddled mipmap file in KAMUI texture format to each mipmap level and the number of bytes of each mipmap level (except 16 bytes of header section)
SIZE OFFSET BYTES
1x1 6 2
2x2 8 8
4x4 16(10h) 32(20h)
8x8 48(30h) 128(80h)
16x16 176(B0h) 512(200h)
32x32 688(2B0h) 2048(800h)
64x64 2736(AB0h) 8192(2000h)
128x128 10928(2AB0h) 32768(8000h)
256x256 43696(AAB0h) 131072(20000h)
512x512 174768(2AAB0h) 524288(80000h)
1024x1024 699056(AAAB0h) 2097152(200000h)

Offset from the beginning of VQ mipmap file in KAMUI texture format to each mipmap level and the number of bytes of each mipmap level (except 16 bytes of header section)
SIZE OFFSET BYTES
1x1 -- --
2x2 2048 + 1 1
4x4 2048 + 2 4
8x8 2048 + 6 16(10h)
16x16 2048 + 22(16h) 64(40h)
32x32 2048 + 86(56h) 256(100h)
64x64 2048 + 342(156h) 1024(400h)
128x128 2048 + 1366(556h) 4096(1000h)
256x256 2048 + 5462(1556h) 16384(4000h)
512x512 2048 + 21846(5556h) 65536(10000h)
1024x1024 2048 + 87382(15556h) 262144(40000h)

Offset from the beginning of the palettized 4-bpp mipmap file in KAMUI texture format to each mipmap level and the number of bytes of each mipmap level (except 16 bytes of the header section)
SIZE OFFSET BYTES
1x1 1 0.5
2x2 2 2
4x4 4 8
8x8 12(0Ch) 32(20h)
16x16 44(2Ch) 128(80h)
32x32 172(ACh) 512(200h)
64x64 684(2ACh) 2048(800h)
128x128 2732(AACh) 8192(2000h)
256x256 10924(2AACh) 32768(8000h)
512x512 43692(AAACh) 131072(20000h)
1024x1024 174764(2AAACh) 524288(80000h)

Offset from the beginning of the palettized 8-bpp mipmap file in KAMUI texture format to each mipmap level and the number of bytes of each mipmap level (except 16 bytes of the header section)
SIZE OFFSET BYTES
1x1 3 1
2x2 4 4
4x4 8 16(10h)
8x8 24(18h) 64(40h)
16x16 88(58h) 256(100h)
32x32 344(158h) 1024(400h)
64x64 1368(558h) 4096(1000h)
128x128 5464(1558h) 16384(4000h)
256x256 21848(5558h) 65536(10000h)
512x512 87384(15558h) 262144(40000h)
1024x1024 349528(55558h) 1048576(100000h)

Parameters:

pSurfaceDesc(input)
Texture surface allocated by kmCreateTextureSurface/kmCreateCombinedTextureSurface/ kmCreateContiguousTextureSurface/kmCreateFixedTextureArea. This parameter is a pointer to KMSURFACEDESC-type structure. (Reload destination)

pTexture(input)
This parameter is a pointer indicating the pixel data portion of the texture in main memory. Indicates the beginning of the texture data of the mipmap level specified by nMipmapCount. (Reload source)

nMipmapCount(input)
Specify the level of the mipmap texture to be read. One of the following enum values can be specified.
nMipmapCount Texture Size
KM_MAPSIZE_1 1x1
KM_MAPSIZE_2 2x2
KM_MAPSIZE_4 4x4
KM_MAPSIZE_8 8x8
KM_MAPSIZE_16 16x16
KM_MAPSIZE_32 32x32
KM_MAPSIZE_64 64x64
KM_MAPSIZE_128 128x128
KM_MAPSIZE_256 256x256
KM_MAPSIZE_512 512x512
KM_MAPSIZE_1024 1024x1024

Return values:

ValueExplanation
KMSTATUS_SUCCESS Success
KMSTATUS_INVALID_PARAMETER Invalid parameter
KMSTATUS_INVALID_TEXTURE_TYPE Invalid texture specified

  kmReLoadMipmap