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:

> Value | Explanation
> --- | ---
> KMSTATUS_SUCCESS | Success
> KMSTATUS_INVALID_PARAMETER | Invalid parameter
> KMSTATUS_INVALID_TEXTURE_TYPE | Invalid texture specified

kmReLoadMipmap