pvr_misc.h

Go to the documentation of this file.

/* KallistiOS ##version##
 
   dc/pvr/pvr_misc.h
   Copyright (C) 2002 Megan Potter
   Copyright (C) 2014 Lawrence Sebald
   Copyright (C) 2023 Ruslan Rostovtsev
   Copyright (C) 2024 Falco Girgis
*/
 
/** \file       dc/pvr/pvr_misc.h
    \brief      Miscellaneous utilities for the PVR API
    \ingroup    pvr
 
    \author Megan Potter
    \author Roger Cattermole
    \author Paul Boese
    \author Brian Paul
    \author Lawrence Sebald
    \author Benoit Miller
    \author Ruslan Rostovtsev
    \author Falco Girgis
*/
 
#ifndef __DC_PVR_PVR_MISC_H
#define __DC_PVR_PVR_MISC_H
 
#include <stdint.h>
 
#include <kos/cdefs.h>
__BEGIN_DECLS
 
 
/** \brief   Pack four floating point color values into a 32-bit integer form.
 
    All of the color values should be between 0 and 1.
 
    \param  a               Alpha value
    \param  r               Red value
    \param  g               Green value
    \param  b               Blue value
    \return                 The packed color value
*/
#define PVR_PACK_COLOR(a, r, g, b) ( \
        ( ((uint8_t)( (a) * 255 ) ) << 24 ) | \
        ( ((uint8_t)( (r) * 255 ) ) << 16 ) | \
        ( ((uint8_t)( (g) * 255 ) ) <<  8 ) | \
        ( ((uint8_t)( (b) * 255 ) ) <<  0 ) )
 
/** \brief   Pack two floating point coordinates into one 32-bit value,
             truncating them to 16-bits each.
 
    \param  u               First coordinate to pack
    \param  v               Second coordinate to pack
    \return                 The packed coordinates
*/
static inline uint32_t PVR_PACK_16BIT_UV(float u, float v) {
    union {
        float f;
        uint32_t i;
    } u2, v2;
 
    u2.f = u;
    v2.f = v;
 
    return (u2.i & 0xFFFF0000) | (v2.i >> 16);
}
 
 
/** \defgroup pvr_global Global State
    \brief               PowerVR functionality which is managed globally
    \ingroup             pvr
 
    These are miscellaneous parameters you can set which affect the
    rendering process.
*/
 
/** \brief   Set the background plane color.
    \ingroup pvr_global
 
    This function sets the color of the area of the screen not covered by any
    other polygons.
 
    \param  r               Red component of the color to set
    \param  g               Green component of the color to set
    \param  b               Blue component of the color to set
*/
void pvr_set_bg_color(float r, float g, float b);
 
/** \brief   Set cheap shadow parameters.
    \ingroup pvr_global
 
    This function sets up the PVR cheap shadow parameters for use. You can only
    specify one scale value per frame, so the effect that you can get from this
    is somewhat limited, but if you want simple shadows, this is the easiest way
    to do it.
 
    Polygons affected by a shadow modifier volume will effectively multiply
    their final color by the scale value set here when shadows are enabled and
    the polygon is inside the modifier (or outside for exclusion volumes).
 
    \param  enable          Set to true to enable cheap shadow mode.
    \param  scale_value     Floating point value (between 0 and 1) representing
                            how colors of polygons affected by and inside the
                            volume will be modified by the shadow volume.
*/
void pvr_set_shadow_scale(bool enable, float scale_value);
 
/** \brief   Set Z clipping depth.
    \ingroup pvr_global
 
    This function sets the Z clipping depth. The default value for this is
    0.0001.
 
    \param  zc              The new value to set the z clip parameter to.
*/
void pvr_set_zclip(float zc);
 
/** \brief   Set the vertical scale factor.
    \ingroup pvr_global
 
    This function sets the vertical scale factor used when the PVR scene is
    rendered to the framebuffer. Generally you want 1.0f or near-1.0f values
    here. The default used by the PVR driver is 1.0f when using VGA, and 0.999f
    otherwise. Having a value slightly below 1.0f gives the image a pleasant
    smoothing.
 
    \retval 0               On success
    \retval -1              On invalid factor value
*/
int pvr_set_vertical_scale(float factor);
 
/** \brief   Set the translucent polygon sort mode for the next frame.
    \ingroup pvr_scene_mgmt
 
    This function sets the translucent polygon sort mode for the next frame of
    output, potentially switching between autosort and presort mode.
 
    For most programs, you'll probably want to set this at initialization time
    (with the autosort_disabled field in the pvr_init_params_t structure) and
    not mess with it per-frame. It is recommended that if you do use this
    function to change the mode that you should set it each frame to ensure that
    the mode is set properly.
 
    \param  presort         Set to true to set the presort mode for translucent
                            polygons, set to false to use autosort mode.
*/
void pvr_set_presort_mode(bool presort);
 
/** \brief   Retrieve the current VBlank count.
    \ingroup pvr_stats
 
    This function retrieves the number of VBlank interrupts that have occurred
    since the PVR was initialized.
 
    \return                 The number of VBlanks since init
*/
int pvr_get_vbl_count(void);
 
/** \defgroup pvr_stats         Profiling
    \brief                      Rendering stats and metrics for profiling
    \ingroup                    pvr
*/
 
/** \brief   PVR statistics structure.
    \ingroup pvr_stats
 
    This structure is used to hold various statistics about the operation of the
    PVR since initialization.
*/
typedef struct pvr_stats {
    uint64_t frame_last_time;     /**< \brief Ready-to-Ready length for the last frame in nanoseconds */
    uint64_t reg_last_time;       /**< \brief Registration time for the last frame in nanoseconds */
    uint64_t rnd_last_time;       /**< \brief Rendering time for the last frame in nanoseconds */
    uint64_t buf_last_time;       /**< \brief DMA buffer file time for the last frame in nanoseconds */
    size_t   frame_count;         /**< \brief Total number of rendered/viewed frames */
    size_t   vbl_count;           /**< \brief VBlank count */
    size_t   vtx_buffer_used;     /**< \brief Number of bytes used in the vertex buffer for the last frame */
    size_t   vtx_buffer_used_max; /**< \brief Number of bytes used in the vertex buffer for the largest frame */
    float    frame_rate;          /**< \brief Current frame rate (per second) */
    uint32_t enabled_list_mask;   /**< \brief Which lists are enabled? */
    /* ... more later as it's implemented ... */
} pvr_stats_t;
 
/** \brief   Get the current statistics from the PVR.
    \ingroup pvr_stats
 
    This function fills in the pvr_stats_t structure passed in with the current
    statistics of the system.
 
    \param  stat            The statistics structure to fill in. Must not be
                            NULL
    \retval 0               On success
    \retval -1              If the PVR is not initialized
*/
int pvr_get_stats(pvr_stats_t *stat);
 
__END_DECLS
 
#endif /* __DC_PVR_PVR_MISC_H */