From e2e981fcc1cb7df017955fb678574e27cf35fdc2 Mon Sep 17 00:00:00 2001 From: Josh Holtrop Date: Mon, 15 Jun 2015 23:16:40 -0400 Subject: [PATCH] add doxygen comments --- include/glcxx/Array.hpp | 20 +++++++++ include/glcxx/Buffer.hpp | 85 +++++++++++++++++++++++++++++++++++--- include/glcxx/Error.hpp | 13 +++++- include/glcxx/Program.hpp | 86 ++++++++++++++++++++++++++++++++++++++- include/glcxx/Shader.hpp | 59 ++++++++++++++++++++++++++- 5 files changed, 252 insertions(+), 11 deletions(-) diff --git a/include/glcxx/Array.hpp b/include/glcxx/Array.hpp index 97a3eeb..a5a5a82 100644 --- a/include/glcxx/Array.hpp +++ b/include/glcxx/Array.hpp @@ -5,21 +5,41 @@ namespace glcxx { + /** + * C++ wrapper for an OpenGL vertex array object. + */ class Array { public: + /** + * Create and allocate an OpenGL vertex array object. + */ Array(); + /** + * Destroy the vertex array object. + */ ~Array(); + /** + * Bind the vertex array object. + */ void bind() { glBindVertexArray(m_id); } + /** + * Get the vertex array object's ID. + * + * @return The buffer ID. + */ GLuint id() const { return m_id; } protected: + /** + * The vertex array object's ID. + */ GLuint m_id; }; }; diff --git a/include/glcxx/Buffer.hpp b/include/glcxx/Buffer.hpp index 9f5805f..638edd4 100644 --- a/include/glcxx/Buffer.hpp +++ b/include/glcxx/Buffer.hpp @@ -7,48 +7,114 @@ namespace glcxx { + /** + * C++ wrapper for an OpenGL buffer object. + */ class Buffer { public: + /** + * Construct and allocate an OpenGL buffer object. + */ Buffer(); + /** + * Destroy the buffer object. + */ ~Buffer(); + /** + * Set the buffer's data, target, and usage. + * + * @param target Buffer target (e.g. GL_ARRAY_BUFFER). + * @param usage Buffer usage hint (e.g. GL_STATIC_DRAW). + * @param ptr Pointer to data to load in buffer. + * @param size Length of the data to load in buffer. + */ void set_buffer_data(GLenum target, GLenum usage, const void * ptr, size_t size); + /** + * Set the buffer's data, target, and usage. + * + * @param target Buffer target (e.g. GL_ARRAY_BUFFER). + * @param usage Buffer usage hint (e.g. GL_STATIC_DRAW). + * @param data Data to load in buffer. + */ void set_buffer_data(GLenum target, GLenum usage, std::initializer_list data) { set_buffer_data(target, usage, &*data.begin(), (uintptr_t)&*data.end() - (uintptr_t)&*data.begin()); } + /** + * Set the buffer's data, target, and usage. + * + * @param target Buffer target (e.g. GL_ARRAY_BUFFER). + * @param usage Buffer usage hint (e.g. GL_STATIC_DRAW). + * @param data Data to load in buffer. + */ void set_buffer_data_d(GLenum target, GLenum usage, std::initializer_list data) { set_buffer_data(target, usage, &*data.begin(), (uintptr_t)&*data.end() - (uintptr_t)&*data.begin()); } + /** + * Get the buffer object's ID. + * + * @return The buffer object's ID. + */ GLuint id() const { return m_id; } + /** + * Bind the buffer object. + */ void bind() const { glBindBuffer(m_target, m_id); } - static std::shared_ptr create(GLenum target, GLenum usage, const void * ptr, size_t size) + /** + * Factory method to construct a Buffer. + * + * @param target Buffer target (e.g. GL_ARRAY_BUFFER). + * @param usage Buffer usage hint (e.g. GL_STATIC_DRAW). + * @param ptr Pointer to data to load in buffer. + * @param size Length of the data to load in buffer. + * + * @return std::shared_ptr to a Buffer. + */ + static std::shared_ptr + create(GLenum target, GLenum usage, const void * ptr, size_t size) { std::shared_ptr buffer = std::make_shared(); buffer->set_buffer_data(target, usage, ptr, size); return buffer; } - static std::shared_ptr create(GLenum target, GLenum usage, - std::initializer_list data) + /** + * Factory method to construct a Buffer. + * + * @param target Buffer target (e.g. GL_ARRAY_BUFFER). + * @param usage Buffer usage hint (e.g. GL_STATIC_DRAW). + * @param data Data to load in buffer. + */ + static std::shared_ptr + create(GLenum target, GLenum usage, + std::initializer_list data) { std::shared_ptr buffer = std::make_shared(); buffer->set_buffer_data(target, usage, data); return buffer; } - static std::shared_ptr create_d(GLenum target, GLenum usage, - std::initializer_list data) + /** + * Factory method to construct a Buffer. + * + * @param target Buffer target (e.g. GL_ARRAY_BUFFER). + * @param usage Buffer usage hint (e.g. GL_STATIC_DRAW). + * @param data Data to load in buffer. + */ + static std::shared_ptr + create_d(GLenum target, GLenum usage, + std::initializer_list data) { std::shared_ptr buffer = std::make_shared(); buffer->set_buffer_data_d(target, usage, data); @@ -56,10 +122,19 @@ namespace glcxx } protected: + /** + * The buffer object's ID. + */ GLuint m_id; + /** + * The target for binding the buffer. + */ GLenum m_target; + /** + * Allocate the OpenGL buffer object. + */ void allocate(); }; }; diff --git a/include/glcxx/Error.hpp b/include/glcxx/Error.hpp index ec4bcf3..f1c71fd 100644 --- a/include/glcxx/Error.hpp +++ b/include/glcxx/Error.hpp @@ -5,15 +5,24 @@ namespace glcxx { - + /** + * Exception class for glcxx errors. + * + * An instance of this class might be thrown if an OpenGL object cannot + * be allocated or another glcxx error condition arises. + */ class Error : public std::runtime_error { public: + /** + * Construct an Error instance. + * + * @param msg The exception message. + */ Error(const std::string & msg) : std::runtime_error(msg) { }; }; - }; #endif diff --git a/include/glcxx/Program.hpp b/include/glcxx/Program.hpp index 17e02e5..e70e68f 100644 --- a/include/glcxx/Program.hpp +++ b/include/glcxx/Program.hpp @@ -7,48 +7,109 @@ namespace glcxx { + /** + * C++ wrapper for an OpenGL program object. + */ class Program { public: + /** + * Create and allocate an OpenGL program object. + */ Program(); + /** + * Destroy the program object. + */ ~Program(); + /** + * Get the program object's ID. + * + * @return The program object's ID. + */ GLuint id() const { return m_id; } + /** + * Use the program. + */ void use() const { glUseProgram(m_id); } + /** + * Utility method to attach shaders and link the program. + * + * This method automatically invokes attach_shader() for each + * shader given and then invokes link() to link the program. + * + * @param shaders + * A std::unique_ptr, std::shared_ptr, or + * const Shader &. + */ template void build(Shaders... shaders) { - allocate(); _build(shaders...); } + /** + * Attach a shader to the program. + * + * @param shader The shader to attach. + */ void attach_shader(const Shader & shader) const { glAttachShader(m_id, shader.id()); } + /** + * Attach a shader to the program. + * + * @param shader The shader to attach. + */ void attach_shader(std::unique_ptr shader) const { glAttachShader(m_id, shader->id()); } + /** + * Attach a shader to the program. + * + * @param shader The shader to attach. + */ void attach_shader(std::shared_ptr shader) const { glAttachShader(m_id, shader->id()); } + /** + * Link the program. + */ void link() const; + /** + * Get the index of a uniform variable in the program. + * + * @param uniform_name Name of the uniform variable. + * + * @return Index of the uniform variable. + */ GLint get_uniform_location(const char * uniform_name) { return glGetUniformLocation(m_id, uniform_name); } + /** + * Factory method to construct a Program object. + * + * @param args + * The arguments given are passed to the constructed Program's + * build() method. + * + * @return std::shared_ptr to a Buffer. + */ template - static std::shared_ptr create(Args... args) + static std::shared_ptr + create(Args... args) { std::shared_ptr program = std::make_shared(); program->build(args...); @@ -56,15 +117,27 @@ namespace glcxx } protected: + /** + * The program object's ID. + */ GLuint m_id; + /** + * Allocate an OpenGL program object. + */ void allocate(); + /** + * Internal helper to build(). + */ void _build() const { link(); } + /** + * Internal helper to build(). + */ template void _build(const Shader & shader, Shaders... args) const { @@ -72,6 +145,9 @@ namespace glcxx _build(args...); } + /** + * Internal helper to build(). + */ template void _build(std::unique_ptr shader, Shaders... args) const { @@ -79,6 +155,9 @@ namespace glcxx _build(args...); } + /** + * Internal helper to build(). + */ template void _build(std::shared_ptr shader, Shaders... args) const { @@ -86,6 +165,9 @@ namespace glcxx _build(args...); } + /** + * Internal helper to build(). + */ template void _build(const char * attribute_name, GLuint index, Shaders... args) const { diff --git a/include/glcxx/Shader.hpp b/include/glcxx/Shader.hpp index 554e13b..c57a290 100644 --- a/include/glcxx/Shader.hpp +++ b/include/glcxx/Shader.hpp @@ -6,27 +6,73 @@ namespace glcxx { + /** + * C++ wrapper for an OpenGL shader object. + */ class Shader { public: + /** + * Create and allocate an OpenGL shader object. + * + * @param shader_type OpenGL shader type (e.g. GL_VERTEX_SHADER). + */ Shader(GLenum shader_type); + /** + * Destroy the shader object. + */ ~Shader(); + /** + * Load shader source from memory. + * + * @param source Pointer to the shader source. + * @param length + * Length of the shader source. If unspecified, the shader source + * must be NULL-terminated. + */ void set_source(const char * source, int length = -1); + /** + * Load shader source from a file. + * + * @param filename Name of the file to load. + */ void set_source_from_file(const char * filename); + /** + * Get the shader object's ID. + * + * @return The shader object's ID. + */ GLuint id() const { return m_id; } - static std::shared_ptr create(GLenum shader_type, const char * source, int length = -1) + /** + * Factory method to construct a Shader object. + * + * @param shader_type OpenGL shader type (e.g. GL_VERTEX_SHADER). + * @param source Pointer to the shader source. + * @param length + * Length of the shader source. If unspecified, the shader source + * must be NULL-terminated. + */ + static std::shared_ptr + create(GLenum shader_type, const char * source, int length = -1) { std::shared_ptr shader = std::make_shared(shader_type); shader->set_source(source, length); return shader; } - static std::shared_ptr create_from_file(GLenum shader_type, const char * filename) + /** + * Factory method to construct a Shader object. + * + * @param shader_type OpenGL shader type (e.g. GL_VERTEX_SHADER). + * @param filename Name of the file to load. + */ + static std::shared_ptr + create_from_file(GLenum shader_type, const char * filename) { std::shared_ptr shader = std::make_shared(shader_type); shader->set_source_from_file(filename); @@ -34,10 +80,19 @@ namespace glcxx } protected: + /** + * The shader object's ID. + */ GLuint m_id; + /** + * The OpenGL shader type. + */ GLenum m_shader_type; + /** + * Allocate the OpenGL shader object. + */ void allocate(); }; };