DevKit7/citro3d
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: inital base documentation

Browse Source
This commit is contained in:
oreo639 2024-01-16 18:31:31 -08:00
parent 33e7995673
commit d0c51f6f0c
1 changed files with 116 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
include/c3d/base.h
View File

@ -1,41 +1,152 @@
/**
* @file base.h
* @brief Base citro3d functions
*/
#pragma once
#include "buffers.h"
#include "maths.h"
/// Default command buffer size
#define C3D_DEFAULT_CMDBUF_SIZE 0x40000
/**
* @brief Data type of indices for use with \ref C3D_DrawElements().
*/
enum
{
C3D_UNSIGNED_BYTE = 0,
C3D_UNSIGNED_SHORT = 1,
C3D_UNSIGNED_BYTE = 0, ///< Unsigned 8-bit integer
C3D_UNSIGNED_SHORT = 1, ///< Unsigned 16-bit integer
};
/**
* @brief Initializes citro3d.
* @param[in] cmdBufSize Desired size of GPU command buffer. \ref C3D_DEFAULT_CMDBUF_SIZE should generally be used here.
* @note If you have a particularly complex scene you might need to specify a larger \p cmdBufSize.
* Conversely, you may want to decrease it if you're particularly concerned about memory consumption.
* @return true if library was initialized successfully, false if there was an error.
*/
bool C3D_Init(size_t cmdBufSize);
/**
* @brief Deinitializes citro3d
* @sa C3D_Init()
*/
void C3D_Fini(void);
/**
* @brief Retrieves the current command buffer usage.
* @return Fraction of command buffer used. (0.0f to 1.0f)
*/
float C3D_GetCmdBufUsage(void);
/**
* @brief Binds a shader program to the current rendering state.
* @param[in] program Specifies the pointer to a shader program object whose executables are to be used
* as part of the current rendering state.
*/
void C3D_BindProgram(shaderProgram_s* program);
/**
* @brief Sets the viewport for the current framebuffer.
* @note This function is called by \ref C3D_FrameDrawOn(). (using values specified by \ref C3D_RenderTargetCreate())
* @note When using this with a rendertarget intended for display, keep in mind the orientation of the screens.
* @param[in] x X offset from the origin of the viewport in pixels.
* @param[in] y Y offset from the origin of the viewport in pixels.
* @param[in] w Width of the viewport in pixels.
* @param[in] h Height of the viewport in pixels.
*/
void C3D_SetViewport(u32 x, u32 y, u32 w, u32 h);
/**
* @brief Defines the scissor box.
* @note When using this with a rendertarget intended for display, keep in mind the orientation of the screens.
* @param[in] mode Specifies scissoring mode.
* @param[in] left Leftmost boundary in pixels.
* @param[in] top Topmost boundary in pixels.
* @param[in] right Rightmost boundary in pixels.
* @param[in] bottom Bottommost boundary in pixels.
*/
void C3D_SetScissor(GPU_SCISSORMODE mode, u32 left, u32 top, u32 right, u32 bottom);
/**
* @brief Renders primitives from current vertex array buffer.
* @param[in] primitive Specifies what kind of primitives to render.
* @param[in] first Specifies the starting index in the current buffers.
* @param[in] size Specifies the number of indices to be rendered.
*/
void C3D_DrawArrays(GPU_Primitive_t primitive, int first, int size);
/**
* @brief Renders primitives from current vertex array buffer in a manually specified order.
* @param[in] primitive Specifies what kind of primitives to render.
* @param[in] count Specifies the number of indices to be rendered.
* @param[in] type Specifies the data type of the indices.
* May be \ref C3D_UNSIGNED_BYTE or \ref C3D_UNSIGNED_SHORT.
* @param[in] indices Specifies a pointer to where the indices are stored.
*/
void C3D_DrawElements(GPU_Primitive_t primitive, int count, int type, const void* indices);
// Immediate-mode vertex submission
/**
* @name Immediate-mode vertex submission
* @{
*/
/**
* @brief Delimits the vertices of a primitive or a group of like primitives.
* @param[in] primitive Specifies type of primitive or primitives that will be created
* using the vertices specified between \ref C3D_ImmDrawBegin() and \ref C3D_ImmDrawEnd().
*/
void C3D_ImmDrawBegin(GPU_Primitive_t primitive);
/**
* @brief Specifies an immediate attribute.
* @note Attributes must be specified in the same order they were specified using \ref AttrInfo_AddLoader().
* @param[in] x Specifies the X value of the current attribute.
* @param[in] y Specifies the Y value of the current attribute.
* @param[in] z Specifies the Z value of the current attribute.
* @param[in] w Specifies the W value of the current attribute.
*/
void C3D_ImmSendAttrib(float x, float y, float z, float w);
/**
* @brief Delimits the vertices of a primitive or a group of like primitives.
* @sa C3D_ImmDrawBegin()
*/
void C3D_ImmDrawEnd(void);
/**
* @brief Specifies the end of the previous strip/fan and the beginning of a new one.
* @sa C3D_ImmDrawBegin()
*/
static inline void C3D_ImmDrawRestartPrim(void)
{
GPUCMD_AddWrite(GPUREG_RESTART_PRIMITIVE, 1);
}
/** @} */
// Fixed vertex attributes
/**
* @name Fixed vertex attributes
* @{
*/
/**
* @brief Gets the pointer to the fixed attribute vector for the specified attribute index.
* @param[in] id Attribute index.
* @return Pointer to the fixed attribute vector for the current attribute.
* @sa C3D_FixedAttribSet()
*/
C3D_FVec* C3D_FixedAttribGetWritePtr(int id);
/**
* @brief Sets fixed attribute vector for the specified attribute index.
* @note The attribute index should be the same as returned by \ref AttrInfo_AddFixed().
* @param[in] id Attribute index.
* @param[in] x Specifies the X value of the attribute.
* @param[in] y Specifies the Y value of the attribute.
* @param[in] z Specifies the Z value of the attribute.
* @param[in] w Specifies the W value of the attribute.
*/
static inline void C3D_FixedAttribSet(int id, float x, float y, float z, float w)
{
C3D_FVec* ptr = C3D_FixedAttribGetWritePtr(id);
@ -44,3 +155,4 @@ static inline void C3D_FixedAttribSet(int id, float x, float y, float z, float w
ptr->z = z;
ptr->w = w;
}
/** @} */