KMVERTEXCONTEXT structure (for Compatibility with Previous Version)

KMVERTEXCONTEXT is provided for the sake of compatibility with the previous version of Kamui.
In Kamui2, KMSTRIPCONTEXT is newly defined, and makes faster and more efficient processing possible.
Using KMSTRIPCONTEXT in Kamui2 is recommended.

In Kamui, the rendering parameters that can be set for each vertex (strip) are centralized
in the KMVERTEXCONTEXT structure.  An application may have several of these structures,
and can switch among them.  First, the application allocates a KMVERTEXCONTEXT structure,
and sets the value for each member.  Next, the application completes KMVERTEXCONTEXT by executing
kmProcessVertexRenderState.  Finally, the application registers the structure in the system
by executing kmSetVertexRenderState.  Switching among completed structures is possible only
by executing kmSetVertexRenderState.  To change some of the members in a previously completed
KMVERTEXCONTEXT structure, it is necessary to execute kmProcessVertexRenderState and
kmSetVertexRenderState again.

For a (two-parameter) polygon that is affected by modifier volumes, two KMVERTEXCONTEXT structures
are required, one for the inside of modifier volumes and one for the outside of modifier volumes.
The application allocates these two KMVERTEXCONTEXT structures and then sets the parameters
for the inside of modifier volumes and for the outside of modifier volumes, respectively.
The parameters for the outside of modifier volumes are registered in the system through
kmProcessVertexRenderState and kmSetVertexRenderState.  The parameters for the inside of
modifier volumes are registered in the system through kmProcessVertexRenderState and
kmSetModifierRenderState.

When first using VERTEXCONTEXT in kmProcessVertexRenderState, it is necessary to specify all members.
Set all of the flags in RenderState, and define all parameters.  Operation is not guaranteed if there
are any undefined bits.

[KMVERTEXCONTEXT structure]
This structure contains all of the parameters that can be set for each vertex (strip), and has the
following members.

typedef struct tagKMVERTEXCONTEXT
{
    KMDWORD                 RenderState;            /* Render Context               */

    /* 
     *for Global Parameter
     */
    KMPARAMTYPE             ParamType;              /* Parameter Type               */
    KMLISTTYPE              ListType;               /* List Type                    */
    KMCOLORTYPE             ColorType;              /* Color Type                   */
    KMUVFORMAT              UVFormat;               /* UV Format                    */

    /*
     * for ISP/TSP Instruction Word 
     */
    KMDEPTHMODE             DepthMode;              /* DepthMode                    */
    KMCULLINGMODE           CullingMode;            /* Culling Mode                 */
    KMDWORD                 reserved00;
    KMSHADINGMODE           ShadingMode;            /* Shading Mode                 */
    KMMODIFIER              SelectModifier;         /* Modifier Volume Valiant      */
    KMBOOLEAN               bZWriteDisable;         /* Z Write Disable              */

    /*
     * for TSP Control Word 
     */
    KMBLENDINGMODE          SRCBlendingMode;        /* Source Blending Mode         */
    KMBLENDINGMODE          DSTBlendingMode;        /* Desitination Blending Mode   */
    KMBOOLEAN               bSRCSel;                /* Source Select                */
    KMBOOLEAN               bDSTSel;                /* Distination Select           */
    KMFOGMODE               FogMode;                /* Fogging                      */
    KMBOOLEAN               bUseSpecular;           /* Specular Highlight           */
    KMBOOLEAN               bUseAlpha;              /* Alpha                        */
    KMBOOLEAN               bIgnoreTextureAlpha;    /* Ignore Texture Alpha         */
    KMCLAMPMODE             ClampUV;                /* Clamp                        */
    KMFLIPMODE              FlipUV;                 /* Flip                         */
    KMFILTERMODE            FilterMode;             /* Texture Filter               */
    KMBOOLEAN               bSuperSample;           /* Anisotoropic Filter          */
    KMDWORD                 MipMapAdjust;           /* Mipmap D Adjust              */
    KMTEXTURESHADINGMODE    TextureShadingMode;     /* Texture Shading Mode         */
    KMBOOLEAN               bColorClamp;            /* ColorClamp Mode              */
    KMDWORD                 PaletteBank;            /* Bank of Palette              */

    /*
     * for Texture Control Bit/Address 
     */
    PKMSURFACEDESC          pTextureSurfaceDesc;    /* Texture Handle               */

    /*
     *  for Intensity FaceColor
     */
    KMFLOAT                 fFaceColorAlpha;        /* Face Color Alpha             */
    KMFLOAT                 fFaceColorRed;          /* Face Color Red               */
    KMFLOAT                 fFaceColorGreen;        /* Face Color Green             */
    KMFLOAT                 fFaceColorBlue;         /* Face Color Blue              */

    /*
     * for Intensity Specular Highlight
     */
    KMFLOAT                 fOffsetColorAlpha;      /* Specular Color Alpha         */
    KMFLOAT                 fOffsetColorRed;        /* Specular Color Red           */
    KMFLOAT                 fOffsetColorGreen;      /* Specular Color Green         */
    KMFLOAT                 fOffsetColorBlue;       /* Specular Color Blue          */

    /*
     * Internal use values.
     */
    KMDWORD                 GLOBALPARAMBUFFER;      /*  Grobal Parameter Buffer     */
    KMDWORD                 ISPPARAMBUFFER;         /*  ISP Parameter Buffer        */
    KMDWORD                 TSPPARAMBUFFER;         /*  TSP Parameter Buffer        */
    KMDWORD                 TexturePARAMBUFFER;     /*  Texture Parameter Buffer    */

    /*
     * for ModifierInstruction 
     */
    KMDWORD                 ModifierInstruction;    /* ModifierInstruction          */
    KMFLOAT                 reserved01;
    KMFLOAT                 reserved02;
    KMFLOAT                 reserved03;
    KMFLOAT                 reserved04;

    KMBOOLEAN               bDCalcExact;            /* D Calc Exact                 */
    KMDWORD                 reserved05;
    KMUSERCLIPMODE          UserClipMode;           /* UserClip Mode                */

} KMVERTEXCONTEXT, *PKMVERTEXCONTEXT, **PPKMVERTEXCONTEXT;

In order to change some or all of the members, use the following status flags to set the
new type of member that is to be written in RenderState in the structure before executing
kmProcessVertexRenderState.

The following status flags can be set in RenderState.
    KM_PARAMTYPE
    KM_LISTTYPE
    KM_USERCLIPMODE
    KM_COLORTYPE
    KM_UVFORMAT
    KM_DEPTHMODE
    KM_CULLINGMODE
    KM_SHADINGMODE
    KM_MODIFIER
    KM_ZWRITEDISABLE
    KM_SRCBLENDINGMODE
    KM_DSTBLENDINGMODE
    KM_SRCSELECT
    KM_DSTSELECT
    KM_FOGMODE
    KM_USESPECULAR
    KM_USEALPHA
    KM_IGNORETEXTUREALPHA
    KM_FLIPUV
    KM_CLAMPUV
    KM_FILTERMODE
    KM_SUPERSAMPLE
    KM_MIPMAPDADJUST
    KM_TEXTURESHADINGMODE
    KM_COLORCLAMP
    KM_PALETTEBANK
    KM_DCALCEXACT

The following values can be set for each member.
[ParamType]
This specifies the vertex data type.
One of the following types can be selected.
    KM_POLYGON              Normal polygon
    KM_MODIFIERVOLUME       ModifierVolume
    KM_SPRITE               Sprite

[ListType]
This specifies the type of list in which vertex data is to be stored.
    KM_OPAQUE_POLYGON       Opaque polygon
    KM_OPAQUE_MODIFIER      Opaque modifier volume
    KM_TRANS_POLYGON        Translucent polygon
    KM_TRANS_MODIFIER       Translucent modifier
    KM_PUNCHTHROUGH_POLYGON Punch-through polygon

[UserClipMode]
This specifies the effect of the clipping area set by kmSetUserClipping.
    KM_USERCLIP_DISABLE     Disables user clipping.
    KM_USERCLIP_INSIDE      Enables the inside of the specified clipping area.
    KM_USERCLIP_OUTSIDE     Enables the outside of the specified clipping area.

[ColorType]
This specifies the vertex color format.
    KM_PACKEDCOLOR              32bit ARGB packed color format
    KM_FLOATINGCOLOR            32bit x 4 floating color format
    KM_INTENSITY                Intensity format
    KM_INTENSITY_PREV_FACE_COL  Intensity format (See below.)

    KM_INTENSITY_PREV_FACE_COL
        Uses the last Intensity format that was registered for FaceColor.  When using this type of
        polygon, a KM_INTENSITY type polygon must have been used at least once previously within
        the same scene.  In the case of a sprite polygon, specify KM_PACKEDCOLOR for ColorType.

[UVFormat]
This specifies the format for the U and V coordinate parameters that are included in the vertex data.
In 32-bit UV format, the U and V coordinates are expressed in IEEE754 32-bit floating point format.
In 16-bit UV format, the lower 16 bits of the 32-bit UV format are deleted, resulting in lower
accuracy.
    KM_32BITUV      32bit KMFLOAT format
    KM_16BITUV      16bit KMFLOAT format
In the case of a sprite polygon, specify KM_16BITUV for UVFormat.

[DepthMode]
This specifies the Z value comparison mode.
    KMDEPTHMODE
    KM_IGNORE
    KM_LESS
    KM_EQUAL
    KM_LESSEQUAL
    KM_GREATER
    KM_NOTEQUAL
    KM_GREATEREQUAL
    KM_ALWAYS

[CullingMode]
This permits selection of one of four parameters: no culling, clockwise culling, counterclockwise
culling, and small polygon culling.
    KM_NOCULLING    No culling
    KM_CULLSMALL    Small polygon culling
    KM_CULLCCW      Counterclockwise culling
    KM_CULLCW       Clockwise culling
If KM_CULLSMALL is set, it is necessary to execute kmSetCullingRegister in the global settings.
If KM_CULLCCW or KM_CULLCW are specified, small polygon culling is also performed simultaneously.

[bDCalcExact]
    KM_TRUE         Calculates the D parameter with precision.
    KM_FALSE        Does not calculate the D parameter with precision.

If KM_TRUE is set, D parameter calculations are performed with precision.  However, this calculation
consumes more time, so the speed of operation may slow down.

[ShadingMode]
This selects the shading mode.  There are four possible combinations of texture/no texture,
and flat/gouraud.
    KM_NOTEXTUREFLAT        No texture, flat shading
    KM_NOTEXTUREGOURAUD     No texture, gouraud shading
    KM_TEXTUREFLAT          Texture, flat shading
    KM_TEXTUREGOURAUD       Texture, gouraud shading
When KM_TEXTUREFLAT has been set, the color data for the first and second vertices in the vertex
strip become invalid.  (The data for the third vertex is valid.)
In the case of a sprite polygon, specify either KM_NOTEXTUREFLAT or KM_TEXTUREFLAT.

[SelectModifier]
This specifies whether a polygon is to be affected by modifier volumes (for example, a two-parameter
polygon or a polygon to which cheap shadow effects are to be applied) or not.  If modifier volume
effects are enabled, the vertex data structure for two-parameter polygons must be used.
However, in the case of cheap shadow mode (when kmSetCheapShadowMode has been executed), use the
vertex data structure for one-parameter polygons.
    KM_NOMODIFIER           Does not use modifier volumes.
    KM_MODIFIER_A           Modifier volumes have effect.

[bZWriteDisable]
    KM_TRUE                 Disables Z value updating.
    KM_FALSE                Enables Z value updating.

[SRCBlendingMode, DSTBlendingMode]
This specifies the Blending mode.
    KM_BOTHINVSRCALPHA      Uses (1-[alpha]s, 1-[alpha]s, 1-[alpha]s, 1-[alpha]s) as the source
                            blending parameters and ([alpha]s, [alpha]s, [alpha]s, [alpha]s) as
                            the destination blending parameters.
                            When SRCBlendingMode has been set, the DSTBlendingMode is overridden,
                            and vice versa.
    KM_BOTHSRCALPHA         Uses ([alpha]s, [alpha]s, [alpha]s, [alpha]s) as the source blending
                            parameters and (1-[alpha]s, 1-[alpha]s, 1-[alpha]s, 1-[alpha]s) as
                            the destination blending parameters.
                            When SRCBlendingMode has been set, the DSTBlendingMode is overridden,
                            and vice versa.
    KM_DESTALPHA            Uses ([alpha]d, [alpha]d, [alpha]d, [alpha]d) as the blending parameters.
    KM_DESTCOLOR            Uses ([alpha]d, Rd, Gd, Bd) as the blending parameters.
    KM_INVDESTALPHA         Uses (1-[alpha]d, 1-[alpha]d, 1-[alpha]d, 1-[alpha]d) as the blending
                            parameters.
    KM_INVDESTCOLOR         Uses (1-[alpha]d, 1-Rd, 1-Gd, 1-Bd) as the blending parameters.
    KM_INVSRCALPHA          Uses (1-[alpha]s, 1-[alpha]s, 1-[alpha]s, 1-[alpha]s) as the blending
                            parameters.
    KM_INVSRCCOLOR          Uses (1-[alpha]s, 1-Rs, 1-Gs, 1-Bs) as the blending parameters.
    KM_SRCALPHA             Uses ([alpha]s, [alpha]s, [alpha]s, [alpha]s) as the blending parameters.
    KM_SRCCOLOR             Uses ([alpha]s, Rs, Gs, Bs) as the blending parameters.
    KM_ONE                  Uses (1, 1, 1, 1) as the blending parameters.
    KM_ZERO                 Uses (0, 0, 0, 0) as the blending parameters.

    Note) ([alpha]s, Rs, Gs, Bs) indicate the source colors, and ([alpha]d, Rd, Gd, Bd) indicate
          the destination colors.  In VERTEXCONTEXT for the background plane, set zero for
          DSTBlendingMode.  (Refer to the description of kmSetBackGroundRenderState.)

[bSRCSel]
    KM_TRUE         Uses the contents of the second accumulation buffer as the source color.
    KM_FALSE        Does not use the contents of the second accumulation buffer as the source color.

[bDSTSel]
    KM_TRUE         Uses the contents of the second accumulation buffer as the destination color.
    KM_FALSE        Does not use the contents of the second accumulation buffer as the
                    destination color.

[FogMode]
This sets the fog mode.
    KM_FOGTABLE     Generates the fog [alpha] value through linear interpolation based on the table
                    data corresponding to the depth value.
    KM_FOGTABLE_2   Substitutes the polygon color for the fog color, and the polygon [alpha] value
                    for the fog [alpha] value.
    KM_FOGVERTEX    Uses the OffsetColor [alpha] value as the Fog [alpha] value.
    KM_NOFOG        Does not perform fog processing.

[bUseSpecular]
Specifies whether to use Specular Highlight (offset color).
    KM_TRUE         Uses the offset color.
    KM_FALSE        Does not use the offset color.
When using BUMP mapping, specify KM_TRUE for bUseSpecular.

[bUseAlpha]
    KM_TRUE         Enables the [alpha] bit within shading colors.
    KM_FALSE        Disables the [alpha] bit within shading colors.

[bIgnoreTextureAlpha]
    KM_TRUE         Ignores the [alpha] bit within texture data.
    KM_FALSE        Enables the [alpha] bit within texture data.
If KM_TRUE is specified, the [alpha] bit in texture data is ignored.  The hardware ignores transparency
information that is included in textures.
 
[FlipUV] 
This specifies whether or not to flip patterns when repeatedly mapping textures.
One of the following values can be specified.
    KM_NOFLIP       No flipping.
    KM_FLIP_V       Flips in the V coordinate direction.
    KM_FLIP_U       Flips in the U coordinate direction.
    KM_FLIP_UV      Flips in the U and V coordinate directions.

[ClampUV]
This specifies texture clamping.
One of the following values can be specified.  If ClampUV is enabled, the FlipUV specification is
ignored.
    KM_NOCLAMP      No clamping.
    KM_CLAMP_V      Clamps in the V coordinate direction.
    KM_CLAMP_U      Clamps in the U coordinate direction.
    KM_CLAMP_UV     Clamps in the U and V coordinate directions.

[FilterMode] 
This sets the texture filter mode.
    KM_POINT_SAMPLE Point sampling filter
    KM_BILINEAR     Bilinear filter
    KM_TRILINEAR_A  Trilinear filter (1st pass)
    KM_TRILINEAR_B  Trilinear filter (2nd and later passes)

[bSuperSample]
    KM_TRUE         Enables the 4x super sampling filter (anisotoropic filter).
    KM_FALSE        Disables the 4x super sampling filter (anisotoropic filter).
Using this setting improves the quality of texture mapping, but at a some loss of performance.

[MipMapAdjust]
This sets the coefficient for calculating the D parameter for mipmap level selection.  The aliasing
adjustment can be made through this parameter.
The lower four bits of these values are valid; the data is fixed-point data, with two bits
representing the integer portion, and two bits representing the decimal portion.
    KM_MIPMAP_D_ADJUST_0_25     /* D=0.25 */
    KM_MIPMAP_D_ADJUST_0_50     /* D=0.50 */
    KM_MIPMAP_D_ADJUST_0_75     /* D=0.75 */
    KM_MIPMAP_D_ADJUST_1_00     /* D=1.00 */
    KM_MIPMAP_D_ADJUST_1_25     /* D=1.25 */
    KM_MIPMAP_D_ADJUST_1_50     /* D=1.50 */
    KM_MIPMAP_D_ADJUST_1_75     /* D=1.75 */
    KM_MIPMAP_D_ADJUST_2_00     /* D=2.00 */
    KM_MIPMAP_D_ADJUST_2_25     /* D=2.25 */
    KM_MIPMAP_D_ADJUST_2_50     /* D=2.50 */
    KM_MIPMAP_D_ADJUST_2_75     /* D=2.75 */
    KM_MIPMAP_D_ADJUST_3_00     /* D=3.00 */
    KM_MIPMAP_D_ADJUST_3_25     /* D=3.25 */
    KM_MIPMAP_D_ADJUST_3_50     /* D=3.50 */
    KM_MIPMAP_D_ADJUST_3_75     /* D=3.75 */
Normally, set KM_MIPMAP_D_ADJUST_1_00 (1.0).
 
TextureShadingMode
This specifies the texture blending mode.
Specify one of the values shown below.
    KM_DECAL        Adds the offset value to the texture color.
                    Uses the [alpha] value of the texture as is.
                    Pixel Color = TextureRGB + OffsetRGB
                    Pixel [alpha] = Texture [alpha]

    KM_MODULATE     Applies the shading effect color to the texture color.
                    Replaces the texture [alpha] value with the shading color [alpha] value.
                    Pixel Color = ShadingRGB x TextureRGB + OffsetRGB
                    Pixel [alpha] = Texture [alpha]

    KM_DECAL_ALPHA  Blends the shading color with the texture color according to the texture
                    [alpha] value.
                    Pixel Color = (TextureRGB x Texture [alpha]) + {ShadingRGB x (1- Texture [alpha])}
                    + OffsetRGB
                    Pixel [alpha] = Shading [alpha]

    KM_MODULATE_ALPHA   Applies the shading color to the texture color.
                        Applies the shading color [alpha] value to the texture [alpha] value.
                        Pixel Color = (TextureRGB x ShadingRGB) + OffsetRGB
                        Pixel [alpha] = Shading [alpha] x Texture [alpha]

[bColorClamp]
This specifies whether to use color clamping or not.
The hardware clamps the pixel color to the clamp value set by kmSetColorClampValue.
    KM_TRUE         Enables the color clamp.
    KM_FALSE        Disables the color clamp.

[PaletteBank]
This value is valid only when a palettized texture has been specified as the texture. In palettized
4bpp mode, the range of values that can be set is from 0 to 63.  In palettized 8bpp mode, the values
also range from 0 to 63, but since only the upper two bits of the 6 bits are valid, the four values
that can actually be used are 0 (0 to 15), 16 (16 to 31), 32 (32 to 47), and 48 (48 to 63).
(For details, refer to kmSetPaletteData.)

[pTextureSurfaceDesc]
This specifies the pointer for the texture surface Surface structure.
To change just a texture without changing the other parameters in KMVERTEXCONTEXT, change just
the pTextureSurfaceDesc member and then call kmProcessVertexRenderState and kmSetVertexRenderstate.
If KM_TEXTUREFLAT or KMTEXTUREGOURAUD is specified for ShadingMode, Kamui will load the information
in the pTextureSurfaceDesc member into the system each time that kmProcessVertexRenderState is called.
In addition, if NULL is specified for the pTextureSurfaceDesc member, then Kamui will not load the
texture address even if KM_TEXTUREFLAT or KMTEXTUREGOURAUD is specified for ShadingMode.
If the texture is undefined and you simply want to set a different parameter first, specify NULL
for the pTextureSurfaceDesc member.

[ModifierInstruction]
When registering a modifier volume, this specifies the type of polygon data that is to be registered.
    KM_MODIFIER_INCLUDE_FIRST_POLY      Indicates that the data is for the first polygon of an
                                        Inclusion modifier volume.
    KM_MODIFIER_EXCLUDE_FIRST_POLY      Indicates that the data is for the first polygon of an
                                        Exclusion modifier volume.
    KM_MODIFIER_INCLUDE_LAST_POLY       Indicates that the data is for the last polygon of an
                                        Inclusion modifier volume.
    KM_MODIFIER_EXCLUDE_LAST_POLY       Indicates that the data is for the last polygon of an
                                        Exclusion modifier volume.
    KM_MODIFIER_NORMAL_POLY             Indicates that the data is for a polygon that is neither
                                        the first nor the last polygon of a modifier volume.
This member does not need to be specified except for a modifier volume.