From 43b2d51bf7744f3fa19691dea794d8e9eb40c91d Mon Sep 17 00:00:00 2001 From: Jerboa-app Date: Sun, 24 Nov 2024 13:52:42 +0000 Subject: [PATCH] docs --- include/jGL/OpenGL/Shader/glShader.h | 73 ++++++++++++++++++++-------- include/jGL/shader.h | 70 ++++++++++++++++++++++---- 2 files changed, 112 insertions(+), 31 deletions(-) diff --git a/include/jGL/OpenGL/Shader/glShader.h b/include/jGL/OpenGL/Shader/glShader.h index df394e3f..c7546e12 100644 --- a/include/jGL/OpenGL/Shader/glShader.h +++ b/include/jGL/OpenGL/Shader/glShader.h @@ -4,52 +4,83 @@ #include #include -/* - - Create a shader like so - - Shader s(vs, fs) # for std::strings vs and fs - - Uniforms are auto scraped in the form "uniform TYPE NAME;" - - Get and Set like so - - s.getUniform("anInteger"); - s.setUniform("projection",myMat4Variable); - - Use, compile and release - - s.compile() # compiles code, creates a program if its not one - s.use(); # glUseProgram - s.release(); # glDeleteProgram - -*/ - namespace jGL::GL { + /** + * @brief An OpenGL implementation of Shader. + * + */ struct glShader : public Shader { + /** + * @brief Construct a glShader from a vertex and fragment source. + * + * @param v vertex shader source. + * @param f fragment shader source. + */ glShader(const char * v, const char * f) : Shader(v, f), program(0), compiled(false), used(false) {} + /** + * @brief Construct an empty glShader. + */ glShader() : Shader(), program(0), compiled(false), used(false) {} + /** + * @brief Construct a glShader from source given by paths. + * + * @param path path the .vs and .fs shader sources. + * @param name name of sources in path: name.vs and name.fs + */ glShader(std::string path, std::string name) : Shader(path, name), program(0), compiled(false), used(false) {} ~glShader(){if(isProgram()){release();}} + /** + * @brief Create the shader program. + * + */ void create(); + + /** + * @brief Destroy the shader program. + * + */ void release(); + + /** + * @brief Compile the shader program. + * @remark If not a program, call glShader::create. + */ void compile(); + + /** + * @brief Use the shader program (and compile if required). + * @remark If not compiled call glShader::compile. + */ void use(); + + /** + * @brief Checks if the glShader is compiled. + * + * @return true it is compiled. + * @return false it is not compiled. + */ bool isCompiled(){return compiled;} + + /** + * @brief Checks if an OpenGL program is created. + * + * @return true a program has been created. + * @return false a program has not been created. + */ bool isProgram(){return glIsProgram(program);} private: diff --git a/include/jGL/shader.h b/include/jGL/shader.h index c2a0a11a..8bb8d9df 100644 --- a/include/jGL/shader.h +++ b/include/jGL/shader.h @@ -35,28 +35,38 @@ namespace jGL const std::regex UNIFORM_DATA_REGEX = std::regex("uniform(\\slowp\\s|\\shighp\\s|\\smediump\\s|\\s)sampler2D (\\S+);"); + /** + * @brief Generic shader program with vertex and fragment shader. + * @remark Uniforms are automatically detected. + * + */ struct Shader { - - /* - - A generic Shader object that can read vertex and fragment shaders from - file or from const char *'s - - Uniforms are detected within the shader program - - */ - + /** + * @brief Construct a Shader from a vertex and fragment source. + * + * @param v vertex shader source. + * @param f fragment shader source. + */ Shader(const char * v, const char * f) : vertex(v), fragment(f) { parseUniforms(); } + /** + * @brief Construct an empty Shader. + */ Shader() : vertex(""),fragment("") {} + /** + * @brief Construct a Shader from source given by paths. + * + * @param path path the .vs and .fs shader sources. + * @param name name of sources in path: name.vs and name.fs + */ Shader(std::string path, std::string name); virtual ~Shader() = default; @@ -66,8 +76,21 @@ namespace jGL return this->vertex == s.vertex && this->fragment == s.fragment; } + /** + * @brief Check for common shader errors. + * + * @return true linting passes. + * @return false linting fails. + */ bool lint(); + /** + * @brief Set a Uniform to a value. + * + * @tparam T the type of uniform. + * @param name the name of the uniform. + * @param value the value of type T. + */ template void setUniform(std::string name, T value) { @@ -92,6 +115,13 @@ namespace jGL const std::string & getVertex() const { return vertex; } const std::string & getFragment() const { return fragment; } + /** + * @brief Get a Uniform by name. + * + * @tparam T the type of the uniform. + * @param name the name of the uniform to get. + * @return jGLUniform the uniform found. + */ template jGLUniform getUniform(std::string name) { @@ -113,6 +143,11 @@ namespace jGL return NULL_UNIFORM; } + /** + * @brief Get all the parsed uniforms in the Shader. + * + * @return std::vector the available uniform names. + */ std::vector getUniformNames() { std::vector v; @@ -123,9 +158,24 @@ namespace jGL return v; } + /** + * @brief Use the shader. + * @remark Use will auto-compile if required. + */ virtual void use() = 0; + /** + * @brief Display the vertex shader with line numbers. + * + * @return std::string the formatted vertex shader + */ std::string displayVertexSource() const { return formatWithLineNumbers(vertex); } + + /** + * @brief Display the fragment shader with line numbers. + * + * @return std::string the formatted fragment shader + */ std::string displayFragmentSource() const { return formatWithLineNumbers(fragment); } protected: