From 19ed1c2744f577cb4a65d615a11dfa6ddb99b991 Mon Sep 17 00:00:00 2001 From: Joshua Moerman Date: Fri, 21 Oct 2011 16:18:56 +0200 Subject: [PATCH] added documentation all over the place --- J/J.h | 4 ++++ J/array.h | 4 ++++ J/basic.h | 6 ++++++ J/fbo.h | 11 ++++++++++- J/fbo.mm | 1 + J/shader.h | 27 +++++++++++++++++++-------- J/to_string.h | 5 ++++- 7 files changed, 48 insertions(+), 10 deletions(-) diff --git a/J/J.h b/J/J.h index db9a282..698e191 100644 --- a/J/J.h +++ b/J/J.h @@ -8,10 +8,14 @@ #import +// Bring some of the C++11 stuff to us. #import "to_string.h" #import "array.h" +// OpenGL functionality #import "shader.h" #import "fbo.h" + +// Other utilities #import "interpolator.h" diff --git a/J/array.h b/J/array.h index 577458c..a4e1b31 100644 --- a/J/array.h +++ b/J/array.h @@ -6,6 +6,10 @@ // Copyright 2011 Vadovas. All rights reserved. // +/* + Luckily for us there is tr1, we use the std::array from there. + */ + #ifndef J_array_h #define J_array_h diff --git a/J/basic.h b/J/basic.h index e971061..154fe2b 100644 --- a/J/basic.h +++ b/J/basic.h @@ -6,6 +6,12 @@ // Copyright 2011 Vadovas. All rights reserved. // +/* + This file will be included by all headers that need opengl. It alse defines a useful error checking function. + + There may be some notes here and there (especially in the fbo and shader headers) about OpenGL ES2, those notes can be educational ;). + */ + #ifndef J_basic_h #define J_basic_h diff --git a/J/fbo.h b/J/fbo.h index 6943117..0c7355a 100644 --- a/J/fbo.h +++ b/J/fbo.h @@ -6,6 +6,14 @@ // Copyright 2011 Vadovas. All rights reserved. // +/* + Like the shader object, all work is done in the constructor and destructor. So copying a fbo object is impossible, use smart pointers instead. The standard constructor only takes a width and height. Texture settings and the presence of a depth buffer are preset and cannot be changed (since one probably wants those things, and there is not a lot of flexibility in ES2). + + The other constructor (wich is defined in fbo.mm) is to make EAGLView more compact, it makes a fbo in a given context and with a given layer (no texture will be generated, so you cannot use this fbo for texture lookup). + + Just like the shader, this class has begin() and end() functions. + */ + #ifndef FBO_H #define FBO_H @@ -21,7 +29,7 @@ // TODO: more error checking in debug build. -// TODO: make texture class? for easier switching between linear/nearest interpolation for example +// TODO: make texture class? for easier switching between linear/nearest interpolation for example. (also affects shader::set_texture). // NOTE: stencil attachment is not supported namespace J { @@ -60,6 +68,7 @@ public: } // ctor from EAGLContext, not using textures, so you cannot use it as lookup, only as renderer. + // this one is defined in fbo.mm, because it uses Quartz and objC / iOS stuff. fbo(EAGLContext* context, CAEAGLLayer* layer); ~fbo() { diff --git a/J/fbo.mm b/J/fbo.mm index 3691ad5..47042f2 100644 --- a/J/fbo.mm +++ b/J/fbo.mm @@ -11,6 +11,7 @@ #import namespace J { + // NOTE: this function is merely to make the EAGLView more compact. It is really a objC / iOS thing. fbo::fbo(EAGLContext* context, CAEAGLLayer* layer) : width(0), height(0), fbo_number(0), renderbuffers(), texture_id(0){ glGenFramebuffers(1, &fbo_number); bind(); diff --git a/J/shader.h b/J/shader.h index f4b19c4..d34cf13 100644 --- a/J/shader.h +++ b/J/shader.h @@ -6,6 +6,14 @@ // Copyright 2011 Vadovas. All rights reserved. // +/* + This is a very basic shader class. The compilation and linking is done in the constructor, and deletion is don in the destructor. As a result, you can't copy a shader, use smart pointers instead. Because OpenGL ES2 uses attribute-indices at link-time, you have to specify your attributes in the constructor (this is a bit cumbersome). + + There are a lot of uniform setters, for both values and array's, they are called set_uniform() for all types. For matrices a additional parameter (trans) can be given, but in ES2 this value has to be false. It's still a parameter to avoid ambiguity, because the overload works with c-style arrays (vector4 is not distinguishable from matrix2x2). A fix would be to introduce types like vector4 and matrix2x2 and such, but Astrant already has those, so I refrain to do that. + + Using the setters should only be done between the begin() and end() functions. + */ + #ifndef SHADER_H #define SHADER_H @@ -19,17 +27,17 @@ #include "basic.h" #include "array.h" -// TODO: do glValidateProgram, like in the OpenGL template (see bottom) // TODO: add error checking at set_uniforms? // TODO: use an uniform map? (benchmark first!) -// TODO: allow arrays is uniforms (now all counts are 1) -// TODO: matrix attributes are not handled well (they take up 4 indices in the attributes) +// TODO: allow arrays in uniforms (now all counts are 1). To make this possible, first make vector and matrix structs. (But Astrant already has those) +// TODO: matrix attributes are not handled well (they take up 4 indices in the attributes instead of one) +// TODO: make the attribute-list nicer (it is really cumbersome now, with the vector) // NOTE: there is only 1 set_uniform for std::array... namespace J { class shader { - // NOTE: it could be hardcoded to use vertex_shader and fragment_shader, for ShaderMap. + // NOTE: it could be hardcoded to use vertex_shader and fragment_shader, for ShaderMap. There is no geometry_shader in ES2. typedef std::map ShaderMap; // shader_type -> shader_name typedef std::map AttributeMap; // attribute_name -> attribute_index @@ -77,7 +85,7 @@ public: GLuint shader = it.second; glDetachShader(program, shader); glDeleteShader(shader); - // NOTE: If a shader object to be deleted is attached to a program object, it will be flagged for deletion, but it will not be deleted until it is no longer attached to any program object + // NOTE: If a shader object to be deleted is attached to a program object, it will be flagged for deletion, but it will not be deleted until it is no longer attached to any program object. Also deleting a shader with name '0' is safe. } end(); @@ -96,6 +104,7 @@ public: // ***************** // attribute setters + // NOTE: the normalized parameter is for integer types, if true they will be mapped to [0, 1], if false it stays in [0, 256] or so. void set_attribute(const std::string& name, GLint size, GLenum type, GLboolean normalized, GLsizei stride, const GLvoid* ptr){ const GLuint index = attributes[name]; glVertexAttribPointer(index, size, type, normalized, stride, ptr); @@ -173,7 +182,8 @@ public: glUniform1iv(glGetUniformLocation(program, name), 1, value); } - // matrices (in ES2 only square matrices) + // matrices + // NOTE: in ES2 there are only square matrices void set_uniform(char const* name, const GLfloat (&value)[16], GLboolean trans) const { glUniformMatrix4fv(glGetUniformLocation(program, name), 1, trans, value); } @@ -190,7 +200,8 @@ public: glUniformMatrix2fv(glGetUniformLocation(program, name), 1, trans, value); } - // textures (see todo above) + // textures + // NOTE: with a texture class this can be made prettier (also se the TODO in fbo.h) void set_texture(const char* name, GLenum target, GLuint tex, int textureLocation, GLenum filter = GL_LINEAR) const { glActiveTexture(GL_TEXTURE0 + textureLocation); glBindTexture(target, tex); @@ -219,7 +230,7 @@ private: // ******************* // compiling / linking void compile_shader(std::istream& file, GLenum type) { - // get the c-string, the shortest way (not fastest) + // get the c-string, the shortest way (not fastest), from http://tinodidriksen.com/ std::string buffer((std::istreambuf_iterator(file)), std::istreambuf_iterator()); const char* sptr = buffer.c_str(); int ssize = buffer.size(); diff --git a/J/to_string.h b/J/to_string.h index 7266a82..2712c08 100644 --- a/J/to_string.h +++ b/J/to_string.h @@ -6,13 +6,16 @@ // Copyright 2011 Vadovas. All rights reserved. // +/* + Workaround for the std::to_string in C++11. Might not be the fastest way (performance-wise), but it was the fastest to implement ;). + */ + #ifndef OpenGLTemplate_to_string_h #define OpenGLTemplate_to_string_h #include #include -// NOTE: workaround for the std::to_string in C++11 namespace std { template