Controls buffers (Vertex/Frame/Native) used in Kamui2.

Prototype declaration:

> `

>     KMSTATUS KMAPI
>     kmSetSystemConfiguration(
>             IN OUT  PKMSYSTEMCONFIGSTRUCT   pSystemConfigStruct
>     );

> `

Description:

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

Parameters:

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

Return values:

> Value | Explanation
> KMSTATUS_SUCCESS | System configuration set up successfully.
> KMSTATUS_NOT_ENOUGH_MEMORY | Insufficient memory capacity for native data and frame buffers.