[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    playground/libs/kgllib/core/kgllib
From:       Rivo Laks <rivolaks () hot ! ee>
Date:       2008-08-31 9:48:15
Message-ID: 1220176095.350426.17018.nullmailer () svn ! kde ! org
[Download RAW message or body]

SVN commit 855189 by rivol:

More docs

 M  +103 -0    program.h  
 M  +11 -9     shader.h  


--- trunk/playground/libs/kgllib/core/kgllib/program.h #855188:855189
@@ -40,6 +40,51 @@
  * Program can encapsulate vertex and fragment shaders or just one of them. If
  *  only either vertex or fragment shader is used, then traditional
  *  fixed-function pipeline is used for the other stage.
+ *
+ * @section creating Creating Program objects
+ * The easiest way to create usable Program object is to pass filenames of the
+ *  vertex- and fragment shader to the Program constructor. This automatically
+ *  creates temporary Shader objects and then combines them into a Program:
+ * @code
+ * Program* prog = new Program(vertexShaderFile, fragmentShaderFile);
+ * if (!prog->isValid()) {
+ *     // Error: program failed to load
+ * }
+ * @endcode
+ *
+ * @section binding Binding
+ * To use the program, you need to first bind() it, then render your geometry
+ *  and finally unbind() it. Note that it's more convenient to use the Mesh
+ *  class which takes care of the binding and unbinding automatically.
+ * @code
+ * prog->bind();
+ * // Everything rendered now will use the bound program
+ * renderObjects();
+ * // Finally unbind the program
+ * prog->unbind();
+ * @endcode
+ *
+ * @section uniforms Uniform variables
+ * For communication between GPU Program and your main application, uniform
+ *  variables can be used. They can be written from your main program and read
+ *  in shader code. Note that modifying values of uniform variables may be
+ *  expensive, thus you should do it only when really necessary.
+ * @code
+ * // The program has to be bound before setUniform() can be used
+ * prog->bind();
+ * // Set variable "objectScale" to 2.0f
+ * prog->setUniform("objectScale", 2.0f);
+ * // Unbind the program
+ * prog->unbind();
+ * @endcode
+ *
+ * The corresponding section in the shader code would look like this:
+ * @code
+ * uniform float objectScale;
+ * // objectScale can now be used as any other variable
+ * @endcode
+ *
+ * @see Shader, Mesh
  **/
 class KGLLIB_EXPORT Program
 {
@@ -61,6 +106,9 @@
      * If everything succeeded, then the program is ready to be used.
      **/
     Program(const QString& vertexshaderfile, const QString& fragmentshaderfile);
+    /**
+     * Deletes this program and frees all resources.
+     **/
     virtual ~Program();
 
     /**
@@ -80,6 +128,14 @@
      **/
     virtual bool link();
 
+    /**
+     * Returns true if this program can be used for rendering, false otherwise.
+     *
+     * Invalid programs can be result of syntax errors in the shader code.
+     *  Program which hasn't been linked yet is also invalid.
+     *
+     * @see link(), linkLog()
+     **/
     bool isValid() const  { return mValid; }
     /**
      * @return Link log of the program or null if there was none or the program
@@ -93,6 +149,8 @@
     /**
      * Binds the program so that it will be used for anything that is rendered
      * after the bind() call.
+     *
+     * @see unbind()
      **/
     virtual void bind() const;
     /**
@@ -100,6 +158,8 @@
      *  rendered using the fixed-function pipeline.
      * Note that if you want to change the currently used program, you needn't
      *  call unbind() before bind()ing the next program.
+     *
+     * @see bind()
      **/
     virtual void unbind() const;
 
@@ -115,13 +175,56 @@
      * Sets the uniform with the given name to the given value and returns
      *  true.
      * If there is no uniform with such name then false is returned.
+     *
+     * Note that the program has to be bound before this method can be used.
+     *
+     * @see bind()
      **/
     bool setUniform(const char* name, float value);
+    /**
+     * Sets the uniform with the given name to the given value and returns
+     *  true.
+     * If there is no uniform with such name then false is returned.
+     *
+     * Note that the program has to be bound before this method can be used.
+     *
+     * @see bind()
+     **/
     bool setUniform(const char* name, Eigen::Vector2f value);
+    /**
+     * Sets the uniform with the given name to the given value and returns
+     *  true.
+     * If there is no uniform with such name then false is returned.
+     *
+     * Note that the program has to be bound before this method can be used.
+     *
+     * @see bind()
+     **/
     bool setUniform(const char* name, Eigen::Vector3f value);
+    /**
+     * Sets the uniform with the given name to the given value and returns
+     *  true.
+     * If there is no uniform with such name then false is returned.
+     *
+     * Note that the program has to be bound before this method can be used.
+     *
+     * @see bind()
+     **/
     bool setUniform(const char* name, Eigen::Vector4f value);
+    /**
+     * Sets the uniform with the given name to the given value and returns
+     *  true.
+     * If there is no uniform with such name then false is returned.
+     *
+     * Note that the program has to be bound before this method can be used.
+     *
+     * @see bind()
+     **/
     bool setUniform(const char* name, int value);
 
+    /**
+     * @return OpenGL id (aka handle) of this program.
+     **/
     GLuint glId() const  { return mGLId; }
 
 protected:
--- trunk/playground/libs/kgllib/core/kgllib/shader.h #855188:855189
@@ -34,20 +34,22 @@
  *  objects used to create @ref Program objects.
  * For simple use cases, you can use @ref Program class which can automatically
  *  create and use necessary Shader objects.
+ *
+ * @see Program
  **/
 class KGLLIB_EXPORT Shader
 {
 public:
     /**
      * Creates a shader of given type.
-     * You need to manually call @ref setSource() and @ref compile() before
-     *  the shader can be added to a @ref Program.
+     * You need to manually call setSource() and compile() before
+     *  the shader can be added to a Program.
      **/
     Shader(GLenum type);
     /**
      * Loads shader of given type from given file.
      * Loaded shader is automatically compiled, so if the compilation succeeds,
-     *  you can add it to a @ref Program object.
+     *  you can add it to a Program object.
      **/
     Shader(GLenum type, const QString& filename);
     /**
@@ -59,15 +61,15 @@
 
     /**
      * Sets shader source to @p source.
-     * Next you will need to @ref compile the shader.
+     * Next you will need to compile the shader.
      **/
     void setSource(const QString& source);
     void setSource(const QByteArray& source);
 
     /**
      * Compiles the shader.
-     * If compilation succeeds, you can add it to a @ref Program object.
-     * If compilation fails, you can see the error using @ref compileLog() method.
+     * If compilation succeeds, you can add it to a Program object.
+     * If compilation fails, you can see the error using compileLog() method.
      **/
     bool compile();
 
@@ -76,7 +78,7 @@
     /**
      * @return Compile log of the shader or null if there was none or the
      *  shader hasn't been compiled.
-     * Note that @ref Shader keeps ownership of the returned string, so you
+     * Note that Shader keeps ownership of the returned string, so you
      * mustn't delete it.
      * TODO: maybe return QString?
      **/
@@ -99,7 +101,7 @@
 
 /**
  * Vertex shader subclass, so you needn't pass the type=GL_VERTEX_SHADER
- *  parameter to @ref Shader constructor yourself.
+ *  parameter to Shader constructor yourself.
  **/
 class KGLLIB_EXPORT VertexShader : public Shader
 {
@@ -110,7 +112,7 @@
 
 /**
  * Fragment shader subclass, so you needn't pass the type=GL_FRAGMENT_SHADER
- *  parameter to @ref Shader constructor yourself.
+ *  parameter to Shader constructor yourself.
  **/
 class KGLLIB_EXPORT FragmentShader : public Shader
 {
[prev in list] [next in list] [prev in thread] [next in thread]