KMSTRIPCONTEXT/KMTWOVOLUMESTRIPCONTEXT structure

In the previous version of Kamui, the KMVERTEXCONTEXT structure was used for the rendering
parameter settings.  Although Kamui2 permits the use of the KMVERTEXCONTEXT structure for
compatibility, Kamui2 also provides the KMSTRIPCONTEXT/KMTWOVOLUMESTRIPCONTEXT structures for
faster and more efficient processing.
In Kamui2, we strongly recommend using the KMSTRIPCONTEXT/KMTWOVOLUMESTRIPCONTEXT structure.

In Kamui2, the rendering parameters that can be set for each vertex (strip) are centralized
in the KMSTRIPCONTEXT/KMTWOVOLUMESTRIPCONTEXT structure.
Which structure is used depends on the VertexType:
  - When using VertextType00 to 08, 15 to 17:  Use KMSTRIPCONTEXT structure.
  - When using VertextType09 to 14:            Use the KMTWOVOLUMESTRIPCONTEXT structure.

Initially, the application allocates the KMSTRIPHEAD structure and the
KMSTRIPCONTEXT/KMTWOVOLUMESTRIPCONTEXT structure, and sets the values for the necessary members
in the KMSTRIPCONTEXT/KMTWOVOLUMESTRIPCONTEXT structure.  Which members are necessary depends on
the VertexType that is being used.
Next, complete KMSTRIPHEAD with kmGenerateStripHeadXX (00 to 17: VertexType to be used).
The kmChangeStripXxxxxx API can be used to change some members in a KMSTRIPHEAD structure that has
already been completed.

The members that are to be set are indicated below.


[KMSTRIPCONTROL]
typedef struct _tagKMSTRIPCONTROL
{
    KMLISTTYPE          nListType;
    KMUSERCLIPMODE      nUserClipMode;
    KMSHADOWMODE        nShadowMode;
    KMCOLORTYPE         nIntensityMode;
    KMBOOLEAN           bOffset;
    KMBOOLEAN           bGouraud;
}KMSTRIPCONTROL,*PKMSTRIPCONTROL;

- nListType (corresponding VertexType: 00 to 17)
    This sets the list type in which the vertex data is to be stored.
        - In the case of VertexType 00 to 16, select the PolygonType as indicated below.
            KM_OPAQUE_POLYGON           Sets opaque polygon for the ListType.
            KM_TRANS_POLYGON            Sets translucent polygon for the ListType.
            KM_PUNCHTHROUGH_POLYGON     Sets punch-through polygon for the ListType.
        - In the case of VertexType 17, select the ModifierType as indicated below.
            KM_OPAQUE_MODIFIER          Sets opaque modifier volume for the ListType.
            KM_TRANS_MODIFIER           Sets translucent modifier for the ListType.

- nUserClipMode (corresponding VertexType: 00 to 17)
    This sets the effect of the clipping area set by kmSetUserClipping.
            KM_USERCLIP_DISABLE         Disables user clipping.
                                        (User clipping has no effect.)
            KM_USERCLIP_INSIDE          Enables the inside of the specified clipping area.
                                        (The outside is clipped.)
            KM_USERCLIP_OUTSIDE         Enables the outside of the specified clipping area.
                                        (The inside is clipped.)

- nShadowMode (corresponding VertextType: 00 to 08, 15, 16)
    This sets the effect of kmSetCheapShadowMode.
            KM_NORMAL_POLYGON           CheapShadow has no effect.
            KM_CHEAPSHADOW_POLYGON      CheapShadow has effect.

- nIntensityMode (corresponding VertexType: 02, 07, 08, 10, 13, 14)
    This sets IntensityMode.
            KM_INTENSITY                Sets FaceColor and uses IntensityColor.
            KM_INTENSITY_PREV_FACE_COL  Uses the last FaceColor that was specified in the
                                        last Intensity format that was registered.
                                        When using this type of polygon, a KM_INTENSITY type
                                        polygon must have been used at least once previously
                                        within the same scene.

- bOffset (compatible VertexType: 03 to 08, 11 to 14, 16)
    This sets the offset color.
    When using BUMP mapping, set bOffset to KM_TRUE.
            KM_TRUE                     Uses offset color.
            KM_FALSE                    Does not use offset color.

- bGouraud (compatible VertexType: 00 to 14)
    This sets the shading mode.
    When KM_FALSE 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.)
            KM_TRUE                     Uses gouraud shading.
            KM_FALSE                    Does not use gouraud shading.




[KMOBJECTCONTROL]
typedef struct _tagKMOBJECTCONTROL
{
    KMDEPTHMODE             nDepthCompare;
    KMCULLINGMODE           nCullingMode;
    KMBOOLEAN               bZWriteDisable;
    KMBOOLEAN               bDCalcControl;
    KMDWORD                 dwModifierInstruction;
}KMOBJECTCONTROL,*PKMOBJECTCONTROL;

- nDepthCompare (compatible VertexType: 00 to 16)
    This sets the Z value comparison mode.
            KM_IGNORE           
            KM_LESS             
            KM_EQUAL            
            KM_LESSEQUAL        
            KM_GREATER          
            KM_NOTEQUAL         
            KM_GREATEREQUAL     
            KM_ALWAYS           

- nCullingMode (corresponding VertexType: 00 to 17)
    This sets the culling mode.
    In order to enable culling, 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.
            KM_NOCULLING                No culling is performed.
            KM_CULLSMALL                Performs small polygon culling.
            KM_CULLCCW                  Performs culling in the counterclockwise direction.
            KM_CULLCW                   Performs culling in the clockwise direction.

- bZWriteDisable (corresponding VertexType: 00 to 16)
    This sets the Z value operation.
            KM_TRUE                     Disables Z value updating.
            KM_FALSE                    Enables Z value updating.

- bDCalcExact (corresponding VertexType: 03 to 08, 11 to 14, 16)
    This sets the calculation precision for the D parameter that is used in mipmapping.
    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.
            KM_TRUE                     Calculates the D parameter with precision.
            KM_FALSE                    Does not calculate the D parameter with precision.

- ModifierInstruction (corresponding VertexType: 17)
    When registering a modifier volume, this sets 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.


[KMIMAGECONTROL]
typedef struct _tagKMIMAGECONTROL
{
    KMBLENDINGMODE          nSRCBlendingMode;
    KMBLENDINGMODE          nDSTBlendingMode;
    KMBOOLEAN               bSRCSelect;
    KMBOOLEAN               bDSTSelect;
    KMFOGMODE               nFogMode;
    KMBOOLEAN               bColorClamp;
    KMBOOLEAN               bUseAlpha;
    KMBOOLEAN               bIgnoreTextureAlpha;
    KMFLIPMODE              nFlipUV;
    KMCLAMPMODE             nClampUV;
    KMFILTERMODE            nFilterMode;
    KMBOOLEAN               bSuperSampleMode;
    KMDWORD                 dwMipmapAdjust;
    KMTEXTURESHADINGMODE    nTextureShadingMode;
    KMDWORD                 dwPaletteBank;
    PKMSURFACEDESC          pTextureSurfaceDesc;
}KMIMAGECONTROL,*PKMIMAGECONTROL;

- nSRCBlendingMode (corresponding VertexType: [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
- nDSTBlendingMode (corresponding VertexType: [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
    This sets 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 KMSTRIPCONTEXT for the background plane,
               set KM_ZERO for DSTBlendingMode.
               (Refer to the description of kmSetBackGroundRenderState.)

- bSRCSel (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
    This selects usage for the source color.
            KM_TRUE         Uses the second accumulation buffer as the source color.
            KM_FALSE        Does not use the second accumulation buffer as the source color.

- bDSTSel (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
    This selects usage for the destination color.
            KM_TRUE           Uses the second accumulation buffer as the destination color.
            KM_FALSE          Does not use the second accumulation buffer as the destination color.

- nFogMode (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
    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 [alpha] value of OffsetColor as the Fog [alpha] value.
                            Enable OffsetColor when using this setting.  If OffsetColor is disabled,
                            this setting has the same effect as KM_NOFOG.
            KM_NOFOG        Does not perform fog processing.

- bColorClamp (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
    This sets the color clamp.
    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.

- bUseAlpha (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 00 to 16,
  [When KM_IMAGE_PARAM2 is specified] 09 to 14)
    This sets vertex [alpha].
    Even in the case of TransPolygon, an object does not become translucent if this setting is KM_FALSE.
            KM_TRUE         Enables vertex [alpha].
            KM_FALSE        Disables vertex [alpha] (opaque).

- bIgnoreTextureAlpha (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08,
  11 to 14, 16, [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets texture [alpha].
    If KM_TRUE is specified, the [alpha] bit in texture data is ignored.  The hardware ignores
    transparency information that is included in textures.
            KM_TRUE         Ignores the [alpha] bit within texture data.
            KM_FALSE        Enables the [alpha] bit within texture data.

- nFlipUV (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08, 11 to 14, 16,
 [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets texture flipping.
            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.

- nClampUV (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08, 11 to 14, 16,
  [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets texture clamping.
     When ClampUV is enabled, FlipUV setting becomes invalid.
            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 (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08, 11 to 14, 16,
  [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets the texture filter mode.
            KM_POINT_SAMPLE Uses the point sampling filter.
            KM_BILINEAR     Uses the bilinear filter.
            KM_TRILINEAR_A  Uses the trilinear filter (1st pass).
            KM_TRILINEAR_B  Uses the trilinear filter (2nd and later passes).

- bSuperSample (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08, 11 to 14, 16,
  [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets the 4x super sampling filter (anisotoropic filter).
    Using this setting improves the quality of texture mapping, but at a some loss of performance.
            KM_TRUE         Enables the 4x super sampling filter (anisotoropic filter).
            KM_FALSE        Disables the 4x super sampling filter (anisotoropic filter).

- dwMipMapAdjust (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08, 11 to 14, 16,
  [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets the coefficient for calculating the D parameter for mipmap level selection.
    Normally, set KM_MIPMAP_D_ADJUST_1_00 (D = 1.0).
            KM_MIPMAP_D_ADJUST_0_25     Sets the coefficient to D = 0.25.
            KM_MIPMAP_D_ADJUST_0_50     Sets the coefficient to D = 0.50.
            KM_MIPMAP_D_ADJUST_0_75     Sets the coefficient to D = 0.75.
            KM_MIPMAP_D_ADJUST_1_00     Sets the coefficient to D = 1.00.
            KM_MIPMAP_D_ADJUST_1_25     Sets the coefficient to D = 1.25.
            KM_MIPMAP_D_ADJUST_1_50     Sets the coefficient to D = 1.50.
            KM_MIPMAP_D_ADJUST_1_75     Sets the coefficient to D = 1.75.
            KM_MIPMAP_D_ADJUST_2_00     Sets the coefficient to D = 2.00.
            KM_MIPMAP_D_ADJUST_2_25     Sets the coefficient to D = 2.25.
            KM_MIPMAP_D_ADJUST_2_50     Sets the coefficient to D = 2.50.
            KM_MIPMAP_D_ADJUST_2_75     Sets the coefficient to D = 2.75.
            KM_MIPMAP_D_ADJUST_3_00     Sets the coefficient to D = 3.00.
            KM_MIPMAP_D_ADJUST_3_25     Sets the coefficient to D = 3.25.
            KM_MIPMAP_D_ADJUST_3_50     Sets the coefficient to D = 3.50.
            KM_MIPMAP_D_ADJUST_3_75     Sets the coefficient to D = 3.75.
 
- nTextureShadingMode (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08,
  11 to 14, 16, [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets 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ƒ¿) + {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]

- dwPaletteBank (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08, 11 to 14, 16,
  [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets the palette bank number.
    This value is valid only when a palettized texture has been specified as the texture.
    If a palettized texture is not used, this value does not need to be set even if a corresponding
    VertextType is being used.  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 (corresponding VertexType:  [When KM_IMAGE_PARAM1 is specified] 03 to 08,
  11 to 14, 16, [When KM_IMAGE_PARAM2 is specified] 11 to 14)
    This sets the pointer for the texture surface Surface structure.



[KMSTRIPCONTEXT]
typedef struct _tagKMSTRIPCONTEXT
{
    KMSTRIPCONTROL  StripControl;           /* StripControl */
    KMOBJECTCONTROL ObjectControl;          /* ObjectControl*/
    union
    {
        struct {
            KMFLOATCOLOR    Face[2];
        }intensity;
        struct {
            KMPACKEDARGB    Base;
            KMPACKEDARGB    Offset;
        }splite;
    }type;

    KMIMAGECONTROL  ImageControl[2];        /* ImageControl */

}KMSTRIPCONTEXT,*PKMSTRIPCONTEXT;

[KMTWOVOLUMESTRIPCONTEXT]
typedef struct _tagKMTWOVOLUMESTRIPCONTEXT
{
	KMINT32			nSize;
	KMSTRIPCONTROL	StripControl;			/* StripControl */
	KMOBJECTCONTROL	ObjectControl;			/* ObjectControl*/

	union
	{
		struct {
			KMFLOATCOLOR	Face[2];
		}intensity;
		struct {
		    KMPACKEDARGB	Base;
		    KMPACKEDARGB	Offset;
		}splite;
	}type;

	KMIMAGECONTROL	ImageControl[2];		/* ImageControl	*/

}KMTWOVOLUMESTRIPCONTEXT,*PKMTWOVOLUMESTRIPCONTEXT;

- Face (corresponding VertexType: see below)
    This sets FaceColor.
        Face[KM_INTENSITY_BASE]     (corresponding VertexType: 02, 07, 08, 10, 13, 14)
        Face[KM_INTENSITY_OFFSET]   (corresponding VertexType: 07, 08)
        Face[KM_INTENSITY_BASE_2ND] (corresponding VertexType: 10, 13, 14)

- Base (corresponding VertexType: 15, 16)
    This sets the Sprite BaseColor.

- Offset (corresponding VertexType: 16)
    This sets the Sprite OffsetColor.