From 5a9f95de31c2f70b9e40c7b849cabdf65294ff26 Mon Sep 17 00:00:00 2001 From: oreo639 Date: Tue, 16 Jan 2024 18:31:31 -0800 Subject: [PATCH] docs: inital uniforms documentation --- include/c3d/uniforms.h | 72 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/include/c3d/uniforms.h b/include/c3d/uniforms.h index 9e50153..39e09ae 100644 --- a/include/c3d/uniforms.h +++ b/include/c3d/uniforms.h @@ -1,3 +1,7 @@ +/** + * @file uniforms.h + * @brief Write to shader uniforms + */ #pragma once #include "maths.h" @@ -12,6 +16,13 @@ extern bool C3D_FVUnifDirty[2][C3D_FVUNIF_COUNT]; extern bool C3D_IVUnifDirty[2][C3D_IVUNIF_COUNT]; extern bool C3D_BoolUnifsDirty[2]; +/** + * @brief Provides a writable pointer for a floating-point uniform. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] size Number of registers allocated for this uniform. + * @return Writable pointer. This should not be freed. + */ static inline C3D_FVec* C3D_FVUnifWritePtr(GPU_SHADER_TYPE type, int id, int size) { int i; @@ -20,6 +31,12 @@ static inline C3D_FVec* C3D_FVUnifWritePtr(GPU_SHADER_TYPE type, int id, int siz return &C3D_FVUnif[type][id]; } +/** + * @brief Provides a writable pointer for an integer uniform. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @return Writable pointer. This should not be freed. + */ static inline C3D_IVec* C3D_IVUnifWritePtr(GPU_SHADER_TYPE type, int id) { id -= 0x60; @@ -27,6 +44,14 @@ static inline C3D_IVec* C3D_IVUnifWritePtr(GPU_SHADER_TYPE type, int id) return &C3D_IVUnif[type][id]; } +/** + * @brief Writes an Nx4 matrix to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] mtx Matrix to be written. + * @param[in] num Row count of the matrix. + * @remark Usually, one should use the helper functions for 4x4, 3x4, and 2x4 matrices listed below. + */ static inline void C3D_FVUnifMtxNx4(GPU_SHADER_TYPE type, int id, const C3D_Mtx* mtx, int num) { int i; @@ -35,21 +60,48 @@ static inline void C3D_FVUnifMtxNx4(GPU_SHADER_TYPE type, int id, const C3D_Mtx* ptr[i] = mtx->r[i]; // Struct copy. } +/** + * @brief Writes a 4x4 matrix to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] mtx Matrix to be written. + */ static inline void C3D_FVUnifMtx4x4(GPU_SHADER_TYPE type, int id, const C3D_Mtx* mtx) { C3D_FVUnifMtxNx4(type, id, mtx, 4); } +/** + * @brief Writes a 3x4 matrix to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] mtx Matrix to be written. + */ static inline void C3D_FVUnifMtx3x4(GPU_SHADER_TYPE type, int id, const C3D_Mtx* mtx) { C3D_FVUnifMtxNx4(type, id, mtx, 3); } +/** + * @brief Writes a 2x4 matrix to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] mtx Matrix to be written. + */ static inline void C3D_FVUnifMtx2x4(GPU_SHADER_TYPE type, int id, const C3D_Mtx* mtx) { C3D_FVUnifMtxNx4(type, id, mtx, 2); } +/** + * @brief Writes a 4-component floating-point vector to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] x X component of the vector. + * @param[in] y Y component of the vector. + * @param[in] z Z component of the vector. + * @param[in] w W component of the vector. + */ static inline void C3D_FVUnifSet(GPU_SHADER_TYPE type, int id, float x, float y, float z, float w) { C3D_FVec* ptr = C3D_FVUnifWritePtr(type, id, 1); @@ -59,12 +111,27 @@ static inline void C3D_FVUnifSet(GPU_SHADER_TYPE type, int id, float x, float y, ptr->w = w; } +/** + * @brief Writes a 4-component integer vector to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] x X component of the vector. + * @param[in] y Y component of the vector. + * @param[in] z Z component of the vector. + * @param[in] w W component of the vector. + */ static inline void C3D_IVUnifSet(GPU_SHADER_TYPE type, int id, int x, int y, int z, int w) { C3D_IVec* ptr = C3D_IVUnifWritePtr(type, id); *ptr = IVec_Pack(x, y, z, w); } +/** + * @brief Writes a boolean value to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniform to be set. + * @param[in] id ID of the uniform (retrievable using libctru's \ref shaderInstanceGetUniformLocation()) + * @param[in] value Boolean value to write. + */ static inline void C3D_BoolUnifSet(GPU_SHADER_TYPE type, int id, bool value) { id -= 0x68; @@ -75,4 +142,9 @@ static inline void C3D_BoolUnifSet(GPU_SHADER_TYPE type, int id, bool value) C3D_BoolUnifs[type] &= ~BIT(id); } +/** + * @brief Flushes newly-updated uniforms to the uniform registers. + * @param[in] type \ref GPU_SHADER_TYPE of the uniforms to be flushed. + * @remark This is called internally, and generally does not need to be handled by the user. + */ void C3D_UpdateUniforms(GPU_SHADER_TYPE type);