pvr_header.h

Go to the documentation of this file.

/* KallistiOS ##version##
 
   dc/pvr/pvr_header.h
   Copyright (C) 2025 Paul Cercueil
*/
 
/** \file       dc/pvr/pvr_header.h
    \brief      Polygon/Sprite header definitions
    \ingroup    pvr
 
  \author Paul Cercueil
*/
 
#ifndef __DC_PVR_PVR_HEADER_H
#define __DC_PVR_PVR_HEADER_H
 
#include <stdalign.h>
#include <stdint.h>
#include <stdio.h>
 
#include <sys/cdefs.h>
__BEGIN_DECLS
 
/** \defgroup pvr_primitives_headers Headers
    \brief                           Structs relative to PVR headers
    \ingroup pvr_primitives
    \headerfile dc/pvr/pvr_header.h
 
    @{
*/
 
/** \brief   Vertex color formats
 
    These control how colors are represented in polygon data.
*/
enum pvr_color_fmts {
    PVR_CLRFMT_ARGBPACKED,      /**< 32-bit integer ARGB */
    PVR_CLRFMT_4FLOATS,         /**< 4 floating point values */
    PVR_CLRFMT_INTENSITY,       /**< Intensity color */
    PVR_CLRFMT_INTENSITY_PREV,  /**< Use last intensity */
};
 
/** \brief   Primitive clipping modes
 
    These control how primitives are clipped against the user clipping area.
*/
enum pvr_clip_mode {
    PVR_USERCLIP_DISABLE = 0,   /**< Disable clipping */
    PVR_USERCLIP_INSIDE = 2,    /**< Enable clipping inside area */
    PVR_USERCLIP_OUTSIDE = 3,   /**< Enable clipping outside area */
};
 
/** \brief   PVR rendering lists
 
    Each primitive submitted to the PVR must be placed in one of these lists,
    depending on its characteristics.
*/
enum pvr_list_type {
    PVR_LIST_OP_POLY,           /**< Opaque polygon list */
    PVR_LIST_OP_MOD,            /**< Opaque modifier list */
    PVR_LIST_TR_POLY,           /**< Translucent polygon list */
    PVR_LIST_TR_MOD,            /**< Translucent modifier list*/
    PVR_LIST_PT_POLY,           /**< Punch-thru polygon list */
};
 
/** \brief   Primitive culling modes
 
    These culling modes can be set by polygons to determine when they are
    culled. They work pretty much as you'd expect them to if you've ever used
    any 3D hardware before.
*/
enum pvr_cull_mode {
    PVR_CULLING_NONE,           /**< Disable culling */
    PVR_CULLING_SMALL,          /**< Cull if small */
    PVR_CULLING_CCW,            /**< Cull if counterclockwise */
    PVR_CULLING_CW,             /**< Cull if clockwise */
};
 
/** \brief   Depth comparison modes
 
    These set the depth function used for comparisons.
*/
enum pvr_depthcmp_mode {
    PVR_DEPTHCMP_NEVER,         /**< Never pass */
    PVR_DEPTHCMP_LESS,          /**< Less than */
    PVR_DEPTHCMP_EQUAL,         /**< Equal to */
    PVR_DEPTHCMP_LEQUAL,        /**< Less than or equal to */
    PVR_DEPTHCMP_GREATER,       /**< Greater than */
    PVR_DEPTHCMP_NOTEQUAL,      /**< Not equal to */
    PVR_DEPTHCMP_GEQUAL,        /**< Greater than or equal to */
    PVR_DEPTHCMP_ALWAYS,        /**< Always pass */
};
 
/** \brief   Texture U/V size */
enum pvr_uv_size {
    PVR_UV_SIZE_8,
    PVR_UV_SIZE_16,
    PVR_UV_SIZE_32,
    PVR_UV_SIZE_64,
    PVR_UV_SIZE_128,
    PVR_UV_SIZE_256,
    PVR_UV_SIZE_512,
    PVR_UV_SIZE_1024,
};
 
/** \brief   Texture color calculation modes.
 
    The shading mode specifies how the pixel value used as the "foreground" or
    "source" for blending is computed.
 
    Here, "tex" represents the pixel value from the texture, and "col"
    represents the pixel value from the polygon's color.  RGB() represents the
    color channels, A() represents the alpha channel, and ARGB() represents the
    whole pixel (color + alpha).
 
    Note that the offset color (aka. oargb), if specular lighting is enabled,
    is added to the result. Its alpha channel is ignored.
*/
enum pvr_txr_shading_mode {
    PVR_TXRENV_REPLACE,         /**< px = ARGB(tex) */
    PVR_TXRENV_MODULATE,        /**< px = A(tex) + RGB(col) * RGB(tex) */
    PVR_TXRENV_DECAL,           /**< px = A(col) + RGB(tex) * A(tex) + RGB(col) * (1 - A(tex)) */
    PVR_TXRENV_MODULATEALPHA,   /**< px = ARGB(col) * ARGB(tex) */
};
 
/** \brief   Texture sampling modes */
enum pvr_filter_mode {
    PVR_FILTER_NEAREST,         /**< No filtering (point sample) */
    PVR_FILTER_BILINEAR,        /**< Bilinear interpolation */
    PVR_FILTER_TRILINEAR1,      /**< Trilinear interpolation pass 1 */
    PVR_FILTER_TRILINEAR2,      /**< Trilinear interpolation pass 2 */
    PVR_FILTER_NONE = PVR_FILTER_NEAREST,
};
 
/** \brief   Fog modes
 
    Each polygon can decide what fog type is used by specifying the fog mode
    in its header.
*/
enum pvr_fog_type {
    PVR_FOG_TABLE,              /**< Table fog */
    PVR_FOG_VERTEX,             /**< Vertex fog */
    PVR_FOG_DISABLE,            /**< Disable fog */
    PVR_FOG_TABLE2,             /**< Table fog mode 2 */
};
 
/** \brief   Blending modes
 
    These are all the blending modes that can be done with regard to alpha
    blending on the PVR.
*/
enum pvr_blend_mode {
    PVR_BLEND_ZERO,             /**< None of this color */
    PVR_BLEND_ONE,              /**< All of this color */
    PVR_BLEND_DESTCOLOR,        /**< Destination color */
    PVR_BLEND_INVDESTCOLOR,     /**< Inverse of destination color */
    PVR_BLEND_SRCALPHA,         /**< Blend with source alpha */
    PVR_BLEND_INVSRCALPHA,      /**< Blend with inverse source alpha */
    PVR_BLEND_DESTALPHA,        /**< Blend with destination alpha */
    PVR_BLEND_INVDESTALPHA,     /**< Blend with inverse destination alpha */
};
 
/** \brief   Texture formats
 
    These are the texture formats that the PVR supports.
*/
enum pvr_pixel_mode {
    PVR_PIXEL_MODE_ARGB1555,    /**< 16-bit ARGB1555 */
    PVR_PIXEL_MODE_RGB565,      /**< 16-bit RGB565 */
    PVR_PIXEL_MODE_ARGB4444,    /**< 16-bit ARGB4444 */
    PVR_PIXEL_MODE_YUV422,      /**< YUV422 format */
    PVR_PIXEL_MODE_BUMP,        /**< Bumpmap format */
    PVR_PIXEL_MODE_PAL_4BPP,    /**< 4BPP paletted format */
    PVR_PIXEL_MODE_PAL_8BPP,    /**< 8BPP paletted format */
};
 
/** \brief   Triangle strip length
 
    This sets the maximum length of a triangle strip, if not
    configured in auto mode.
*/
enum pvr_strip_len {
    PVR_STRIP_LEN_1,
    PVR_STRIP_LEN_2,
    PVR_STRIP_LEN_4,
    PVR_STRIP_LEN_6,
};
 
/** \brief   Polygon header type
 
    This enum contains the possible PVR header types.
*/
enum pvr_hdr_type {
    PVR_HDR_EOL = 0,
    PVR_HDR_USERCLIP = 1,
    PVR_HDR_OBJECT_LIST_SET = 2,
    PVR_HDR_POLY = 4,
    PVR_HDR_SPRITE = 5,
};
 
/** \brief   Texture address
 
    This type represents an address of a texture in VRAM,
    pre-processed to be used in headers.
*/
typedef uint32_t pvr_txr_ptr_t;
 
/** \brief   Get texture address from VRAM address
 
    This function can be used to get a texture address that can be used
    in a PVR header from the texture's VRAM address.
 
    \param  addr            The texture's address in VRAM
    \return                 The pre-processed texture address
*/
static inline pvr_txr_ptr_t to_pvr_txr_ptr(pvr_ptr_t addr) {
    return ((uint32_t)addr & 0x00fffff8) >> 3;
}
 
/** \brief   PVR header command
 
    This structure contains all the fields for the command of PVR headers.
*/
struct pvr_poly_hdr_cmd {
    bool uvfmt_f16                      :1; /* 0 */     /**< Use 16-bit floating-point U/Vs */
    bool gouraud                        :1; /* 1 */     /**< Enable gouraud shading */
    bool oargb_en                       :1; /* 2 */     /**< Enable specular lighting */
    bool txr_en                         :1; /* 3 */     /**< Enable texturing */
    enum pvr_color_fmts color_fmt       :2; /* 5-4 */   /**< Select color encoding */
    bool mod_normal                     :1; /* 6 */     /**< true: normal, false: cheap shadow */
    bool modifier_en                    :1; /* 7 */     /**< Enable modifier effects */
    uint32_t __pad0                     :8; /* 15-8 */
    enum pvr_clip_mode clip_mode        :2; /* 17-16 */ /**< Clipping mode */
    enum pvr_strip_len strip_len        :2; /* 19-18 */ /**< Triangle strips length (if non-auto) */
    uint32_t __pad1                     :3; /* 22-20 */
    bool auto_strip_len                 :1; /* 23 */    /**< Auto select triangle strips length */
 
    enum pvr_list_type list_type        :3; /* 26-24 */ /**< Render list to use */
    uint32_t __pad2                     :1; /* 27 */
    bool strip_end                      :1; /* 28 */    /**< Mark an end-of-strip */
    enum pvr_hdr_type hdr_type          :3; /* 31-29 */ /**< Header type */
};
 
/** \brief   PVR header mode1
 
    This structure contains all the fields for the mode1 parameter of
    PVR headers.
*/
struct pvr_poly_hdr_mode1 {
    uint32_t __pad3                     :25; /* 24-0 */
    bool txr_en                         :1; /* 25 */    /**< Enable texturing (2nd bit) */
    bool depth_write_dis                :1; /* 26 */    /**< Disable depth writes */
    enum pvr_cull_mode culling          :2; /* 28-27 */ /**< Culling mode */
    enum pvr_depthcmp_mode depth_cmp    :3; /* 31-29 */ /**< Depth comparison mode */
};
 
/** \brief   PVR header mode2
 
    This structure contains all the fields for the mode2 parameter of
    PVR headers.
*/
struct pvr_poly_hdr_mode2 {
    enum pvr_uv_size v_size             :3; /* 2-0 */   /**< Texture height */
    enum pvr_uv_size u_size             :3; /* 5-3 */   /**< Texture width */
    enum pvr_txr_shading_mode shading   :2; /* 7-6 */   /**< Shading mode */
    uint32_t mip_bias                   :4; /* 11-8 */  /**< Bias for mipmaps */
    bool supersampling                  :1; /* 12 */    /**< Enable texture supersampling */
    enum pvr_filter_mode filter_mode    :2; /* 14-13 */ /**< Texture filtering mode */
    bool v_clamp                        :1; /* 15 */    /**< Clamp V to 1.0 */
    bool u_clamp                        :1; /* 16 */    /**< Clamp U to 1.0 */
    bool v_flip                         :1; /* 17 */    /**< Flip V after 1.0 */
    bool u_flip                         :1; /* 18 */    /**< Flip U after 1.0 */
    bool txralpha_dis                   :1; /* 19 */    /**< Disable alpha channel in textures */
    bool alpha                          :1; /* 20 */    /**< Enable alpha channel in vertex colors */
    bool fog_clamp                      :1; /* 21 */    /**< Enable fog clamping */
    enum pvr_fog_type fog_type          :2; /* 23-22 */ /**< Select fog type */
    bool blend_dst_acc2                 :1; /* 24 */    /**< Blend to the 2nd accumulation buffer */
    bool blend_src_acc2                 :1; /* 25 */    /**< Blend from the 2nd accumulation buffer */
    enum pvr_blend_mode blend_dst       :3; /* 28-26 */ /**< Blend mode for the background */
    enum pvr_blend_mode blend_src       :3; /* 31-29 */ /**< Blend mode for the foreground */
};
 
/** \brief   PVR header mode3
 
    This structure contains all the fields for the mode3 parameter of
    PVR headers.
*/
struct pvr_poly_hdr_mode3 {
    pvr_txr_ptr_t txr_base              :25; /* 24-0 */ /**< Pre-processed texture address */
    bool x32stride                      :1; /* 25 */    /**< Set if texture stride is multiple of 32 */
    bool nontwiddled                    :1; /* 26 */    /**< Set if texture is not twiddled */
    enum pvr_pixel_mode pixel_mode      :3; /* 29-27 */ /**< Select the texture's pixel format */
    bool vq_en                          :1; /* 30 */    /**< Set if the texture is VQ encoded */
    bool mipmap_en                      :1; /* 31 */    /**< Enable mipmaps */
};
 
/** \brief   PVR polygon header.
 
    This structure contains information about how the following polygons should
    be rendered.
*/
typedef __attribute__((aligned(32))) struct pvr_poly_hdr {
    union {
        uint32_t cmd;                                   /**< Raw access to cmd param */
        struct pvr_poly_hdr_cmd m0;                     /**< command parameters */
    };
    union {
        uint32_t mode1;                                 /**< Raw access to mode1 param */
        struct pvr_poly_hdr_mode1 m1;                   /**< mode1 parameters */
    };
    union {
        uint32_t mode2;                                 /**< Raw access to mode2 param */
        uint32_t mode2_0;                               /**< Legacy name */
        uint32_t d5;                                    /**< Dummy value 5 */
        struct pvr_poly_hdr_mode2 m2;                   /**< mode2 parameters (modifiers: outside volume) */
    };
    union {
        uint32_t mode3;                                 /**< Raw access to mode3 param */
        uint32_t mode3_0;                               /**< Legacy name */
        uint32_t d6;                                    /**< Dummy value 6 */
        struct pvr_poly_hdr_mode3 m3;                   /**< mode3 parameters (modifiers: outside volume) */
    };
    union {
        struct {
            uint32_t d1;                                /**< Dummy value 1 */
            uint32_t d2;                                /**< Dummy value 2 */
            uint32_t d3;                                /**< Dummy value 3 */
            uint32_t d4;                                /**< Dummy value 4 */
        };
        struct {
            /* Intensity color */
            float a;                                    /**< Intensity color alpha */
            float r;                                    /**< Intensity color red */
            float g;                                    /**< Intensity color green */
            float b;                                    /**< Intensity color blue */
        };
        struct {
            /* Modifier volume */
            union {
                struct {
                    uint32_t mode2_1;                   /**< Legacy name */
                    uint32_t mode3_1;                   /**< Legacy name */
                };
                struct {
                    struct pvr_poly_hdr_mode2 m2;       /**< mode2 parameters (modifiers: inside volume) */
                    struct pvr_poly_hdr_mode3 m3;       /**< mode3 parameters (modifiers: inside volume) */
                } modifier;
            };
            uint64_t __pad4;
        };
        struct {
            /* Sprite */
            uint32_t argb;                              /**< 32-bit ARGB vertex color for sprites */
            uint32_t oargb;                             /**< 32-bit ARGB specular color for sprites */
            uint64_t __pad5;
        };
    };
} pvr_poly_hdr_t;
 
_Static_assert(sizeof(pvr_poly_hdr_t) == 32, "Invalid header size");
 
/** @} */
 
__END_DECLS
#endif /* __DC_PVR_PVR_HEADER_H */