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.