Prototype declaration:
KMSTATUS KMAPI kmSetSystemConfiguration( IN OUT PKMSYSTEMCONFIGSTRUCT pSystemConfigStruct );
Description:
Parameters:This function controls buffers (Vertex/Frame/Native) used in Kamui2. This function sets the KAMUI system configuration according to the parameters specified in the KMSYSTEMCONFIGSTRUCT type structure. A native data buffer (double buffer) and display frame buffer are allocated in frame buffer memory. The capacity of the native data buffer area is obtained as follows: Native data buffer capacity = whole frame buffer memory capacity - (size of the specified maximum texture + display frame buffer capacity) However, the total capacity of the native data buffer (double buffer) cannot be more than half of the total capacity of the frame buffer memory. If the result of the above calculation exceeds the requirement, only half of the total capacity of the frame buffer memory will be used as the native data buffer (double buffer).
Return values:pSystemConfigStruct(input/output) This parameter is a pointer to the KMSYSTEMCONFIGSTRUCT type structure, which is defined as follows: [KMSYSTEMCONFIGSTRUCT] typedef struct _tagKMSYSTEMCONFIGSTRUCT { KMDWORD dwSize; /* Size Of KMSYSTEMCONFIGSTRUCT */ KMDWORD flags; /* System Configuration Flags */ /* for Frame Buffer */ PPKMSURFACEDESC ppSurfaceDescArray; /* Array of SurfaceDesc Pointer */ union{ KMUINT32 nNumOfFrameBuffer; /* Number Of Frame Buffer */ KMUINT32 nStripBufferHeight; /* Height of Strip Buffer */ }fb; /* for Texture Memory */ KMUINT32 nTextureMemorySize; /* Texture Memory size */ KMUINT32 nNumOfTextureStruct; /* number of Texture Control Structure */ KMUINT32 nNumOfSmallVQStruct; /* number of SmallVQ Texture Control Structure */ PKMDWORD pTextureWork; /* Pointer to kamui work area */ /* for Vertex Buffer */ PKMVERTEXBUFFDESC pBufferDesc; /* pointer to KMVERTEXBUFFDESC */ KMUINT32 nNumOfVertexBank; /* Number of VertexBank */ PKMDWORD pVertexBuffer; /* VertexBuffer Pointer */ KMUINT32 nVertexBufferSize; /* VertexBuffer Size */ KMUINT32 nPassDepth; /* Path Depth */ KMPASSINFO Pass[KM_MAX_DISPLAY_LIST_PASS]; /* Pass Information */ /* Reserve Area */ KMDWORD reserved00; /* reserved for future use */ KMDWORD reserved01; /* reserved for future use */ KMDWORD reserved02; /* reserved for future use */ KMDWORD reserved03; /* reserved for future use */ KMDWORD reserved04; /* reserved for future use */ KMDWORD reserved05; /* reserved for future use */ KMDWORD reserved06; /* reserved for future use */ KMDWORD reserved07; /* reserved for future use */ } KMSYSTEMCONFIGSTRUCT, *PKMSYSTEMCONFIGSTRUCT; The setting of each member is explained below: [System configuration specification flag] dwSize(input) This parameter sets the size of the KMSYSTEMCONFIGSTRUCT structure in Sizeof(KMSYSTEMCONFIGSTRUCT). dwflags(input) This parameter specifies the types of data related to the system configuration. It is the result of ORing the following flags. If no flag is to be specified, the parameter shall be reset to zero. KM_CONFIGFLAG_ENABLE_CLEAR_FRAMEBUFFER This argument causes a frame buffer to be cleared when it is allocated. KM_CONFIGFLAG_ENABLE_STRIPBUFFER This argument causes a frame buffer to be created in StripBuffer format. The nWidth and nHeight members are enabled. KM_CONFIGFLAG_ENABLE_2V_LATENCY This argument causes KAMUI to operate in the 2V latency mode. If this argument is not entered, KAMUI operates in the 3V latency mode. KM_CONFIGFLAG_NOWAITVSYNC This argument causes a frame buffer surface to be displayed before a V-sync interrupt occurs. If this argument is not entered, the frame buffer surface is displayed after a V-sync interrupt has occurred. KM_CONFIGFLAG_SEPARATE_EACH_PASS VertexBuffer is allocated for each pass. The KMPASSINFO setting is valid. KM_CONFIGFLAG_NOWAIT_FINISH_TEXTUREDMA This argument causes the texture load function to be terminated before DMA transfer of a texture to frame buffer memory, started by the function, ends. If this argument is entered, the kmQueryFinishLastTextureDMA function can be used to check whether DMA transfer has been completed. Avoid accessing memory from which a DMA transfer is under way. [Parameters related to the frame buffer] ppSurfaceDescArray (output) This parameter specifies the pointer array for the KMSURFACEDESC structure for each frame buffer. Note that if KMSTATUS_NOT_ENOUGH_MEMORY is returned, the contents of this frame buffer structure are undefined. The application must set up the frame buffer structure area and the corresponding pointer array. EIn the case of non-strip buffer nNumOfFrameBuffer(input) This parameter specifies the number of frame buffer surfaces to be generated. ppSurfaceDescArray should be specified using nNumOfFrameBuffer, as follows: (Example) When there are two frame buffer surfaces KMSURFACEDESC Surface1; KMSURFACEDESC Surface2; PKMSURFACEDESC ppSurfaceArray[nNumOfFrameBuffer]; ppSurfaceArray[0] = &Surface1; ppSurfaceArray[1] = &Surface2; ppSurfaceDescArray = ppSurfaceArray; EIn the case of strip buffer nStripBufferHeight(input) This parameter sets the height of the strip buffer. Be sure to use multiples of 32. [Parameters related to the texture area] nTextureMemorySize(input) This parameter indicates the size of the largest texture. It is used to determine the capacity of the native data buffer. Note that the size must be multiples of 32 bytes. nNumOfTextureStruct(input) This parameter specifies the maximum number of texture management structures that Kamui will use for texture management. One texture/frame buffer surface and one empty area use up one management structure. Even if no textures will be used, a minimum of three structure areas are needed for the native data buffer, the frame buffer, and other empty areas. Note that this value can be calculated by using kmuCalculateKamuiWorkareaSize. nNumOfSmallVQStruct(input) This parameter specifies the maximum number of small VQ texture management structures that Kamui will use for texture management. Small VQ textures use one Small VQ texture management structure and one texture management structure for each of the blocks indicated below. SmallVQ size Number of blocks 8x8 16 8x8 mipmap 16 16x16 16 16x16 mipmap 16 32x32 8 32x32 mipmap 4 64x64 2 64x64 mipmap 1 If SmallVQ texture is not used at all, the maximum number of SmallVQ texture control structure can be set to zero. Also, the value can be determined by using the kmuCalculateKamuiWorkareaSize function. pTextureWork(input) This parameter gives the starting address of the Kamui work area. It is necessary to prepare system memory space of a size that is determined according to the number of rendering passes and frame buffers/textures used by the application. Note that this size can be calculated by using kmuCalculateKamuiWorkareaSize. [Vertex buffer-related parameters] PKMVERTEXBUFFDESC pBufferDesc; /* pointer to KMVERTEXBUFFDESC */ KMUINT32 nNumOfVertexBank; /* Number of VertexBank */ PKMDWORD pVertexBuffer; /* VertexBuffer Pointer */ KMUINT32 nVertexBufferSize; /* VertexBuffer Size */ KMUINT32 nPassDepth; /* Path Depth */ KMPASSINFO Pass[KM_MAX_DISPLAY_LIST_PASS]; /* Pass Information */ pBufferDesc(input) This parameter inputs the pointer for the KMVERTEXBUFFDESC vertex data buffer descriptor. The application must set up the area for this structure. This structure is referenced by kmStartVertexStrip and kmSetVertex. nNumOfVertexBank(input) This parameter specifies the number of banks of Vertex. pVertexBuffer(input) This parameter inputs a pointer to a vertex data buffer descriptor of KMVERTEXBUFFDESC type. The application program must prepare an area for this structure. nVertexBufferSize(input) This parameter specifies (in bytes) the size of the vertex data buffer allocated in system memory by the application. This size must be a multiple of 32 bytes. nPassDepth(input) This parameter specifies the number of bus splits of VertexBank. Pass[KM_MAX_PASS](input) This parameter sets the pass information. typedef struct _tagKMPASSINFO{ KMDWORD dwRegionArrayFlag; /* Region Array Flag */ PKMDWORD pVertexBuffer; /* VertexBuffer Pointer */ KMUINT32 nVertexBufferSize; /* VertexBuffer Size */ KMUINT32 nDirectTransferList; /* DirectTransfer List Type */ KMFLOAT fBufferSize[KM_MAX_DISPLAY_LIST]; /* Buffer size in percent */ KMDWORD dwOPBSize[KM_MAX_DISPLAY_LIST]; /* Object Ponter Block Size */ }KMPASSINFO,*PKMPASSINFO; dwRegionArrayFlag(input) This parameter makes various specifications concerning RegionArray. Set this value by ORing the following flags: KM_PASSINFO_AUTOSORT Set this flag to set the translucent polygon sort mode to "AutoSort" for the current rendering processing. KM_PASSINFO_PRESORT Set this flag to set the translucent polygon sort mode to "Presort" for the current rendering processing. KM_PASSINFO_USE_ANOTHERLIST Set this flag to enable the KM_PASSINFO_UA_XXXXX flags described below. KM_PASSINFO_UA_TRMOD_AS_OPMOD Set this flag to use the same list as "OpaqueModifier" for "TransModifier." This flag is invalid if KM_PASSINFO_USE_ANOTHERLIST is not set. KM_PASSINFO_UA_OPMOD_AS_TRMOD Set this flag to use the same list as "TransModifier" for "OpaqueModifier." This flag is invalid if KM_PASSINFO_USE_ANOTHERLIST is not set. KM_PASSINFO_UA_DISCADING_TRANSPOLY Set this flag to use "TransPolygon" as "PunchThroughPolygon." This flag is invalid if KM_PASSINFO_USE_ANOTHERLIST is not set. pVertexBuffer(input) This parameter sets the pointer for the vertex buffer that was allocated in system memory by the application. Kamui uses this value as the base address for the vertex buffer. (In order to avoid malloc within Kamui, the buffer must be set up by the application.) Note that this address must be aligned with a 32-byte boundary. This setting is valid when the flag KM_CONFIGFLAG_SEPARATE_EACH_PASS has been set. nVertexBufferSize(input) This parameter specifies, as a percentage the number of polygons used in one scene for each list types. These five list types are specified with a floating point value of between 0.0f and 100.0f. The total of the specified values must be 100.0f. If it exceeds 100.0f, KAMUI may not operate normally. KAMUI uses these values to assign a vertex data buffer to each polygon type. nDirectTransferList(input) This parameter specifies the ListType that is to be directly transferred in 2V_LATENCY mode. This setting is invalid in any mode other than 2V_LATENCY mode. KM_OPAQUE_POLYGON Directly transfer OpaquePolygon. KM_OPAQUE_MODIFIER Directly transfer OpaqueModifier. KM_TRANS_POLYGON Directly transfer TransPolygon. KM_TRANS_MODIFIER Directly transfer TransModifier. KM_PUNCHTHROUGH_POLYGON Directly transfer Punchthrough. fBufferSize[KM_MAX_DISPLAY_LIST](input) This parameter specifies, as a percentage, the amount of polygons of each list type used in each scene. For each list type, specify a floating-point value from 0.0f to 100.0f for each of the five types. These five values must total to 100.0f. Operation is not guaranteed if the total value exceeds 100.0f. Kamui allocates vertex data buffers for each polygon type on the basis of these values. This setting is valid if the KM_CONFIGFLAG_SEPARATE_EACH_PASS flag has been set. dwOPBMode[KM_MAX_DISPLAY_LIST](input) This parameter sets the OPB mode for each of the lists, as follows: dwOPBMode[0] OPB mode of OpaquePolygon dwOPBMode[1] OPB mode of OpaqueModifier dwOPBMode[2] OPB mode of TransPolygon dwOPBMode[3] OPB mode of TransModifier dwOPBMode[4] OPB mode of PunchThroughPolygon KM_OPB_ALLOCCTRL_NOLIST Use this setting when there is no list to register. KM_OPB_ALLOCCTRL_SMALL Use this setting when there is only a small number of lists to register. KM_OPB_ALLOCCTRL_NORMAL Normally use this setting when there are lists to register. KM_OPB_ALLOCCTRL_LARGE Use this setting when there are many lists to registered. reserved00 - reserved07 These are reserved for future expansion. Their contents are undefined.
Value Explanation KMSTATUS_SUCCESS System configuration set up successfully. KMSTATUS_NOT_ENOUGH_MEMORY Insufficient memory capacity for native data and frame buffers.