Documentation for new words in opengl vocab

extra/line-art/line-art.factor

@@ -223,7 +223,7 @@ M: line-art-gadget draw-gadget* ( gadget -- )
     line-art-draw-setup
     dup line-art-gadget-framebuffer [
         line-art-clear-framebuffer
-        GL_COLOR_ATTACHMENT0_EXT GL_COLOR_ATTACHMENT1_EXT 2array set-draw-buffers
+        { GL_COLOR_ATTACHMENT0_EXT GL_COLOR_ATTACHMENT1_EXT } set-draw-buffers
         dup line-art-gadget-step1-program dup [
             "color" glGetUniformLocation 0.6 0.5 0.5 1.0 glUniform4f
             0.0 -0.12 0.0 glTranslatef
@@ -239,7 +239,7 @@ M: line-art-gadget draw-gadget* ( gadget -- )
           [ "normalmap" glGetUniformLocation 1 glUniform1i ]
           [ "depthmap"  glGetUniformLocation 2 glUniform1i ]
           [ "line_color" glGetUniformLocation 0.2 0.0 0.0 1.0 glUniform4f ] } call-with
-        { -1.0 -1.0 } { 1.0 1.0 } draw-rectangle
+        { -1.0 -1.0 } { 1.0 1.0 } rect-vertices
     ] with-gl-program ;
 
 : line-art-window ( -- )

extra/opengl/opengl-docs.factor

@@ -37,6 +37,10 @@ HELP: gl-rect
 { $values { "loc" "a pair of integers" } { "ext" "a pair of integers" } }
 { $description "Draws the outline of a rectangle with top-left corner " { $snippet "loc" } " and bottom-right corner " { $snippet "ext" } "." } ;
 
+HELP: rect-vertices
+{ $values { "lower-left" "A pair of numbers indicating the lower-left coordinates of the rectangle." } { "upper-right" "The upper-right coordinates of the rectangle." } }
+{ $description "Emits" { $link glVertex2d } " calls outlining the axis-aligned rectangle from " { $snippet "lower-left" } to { $snippet "upper-right" } " on the z=0 plane in counterclockwise order." } ;
+
 HELP: gl-fill-poly
 { $values { "points" "a sequence of pairs of integers" } }
 { $description "Draws a filled polygon." } ;
@@ -53,6 +57,58 @@ HELP: gen-texture
 { $values { "id" integer } }
 { $description "Wrapper for " { $link glGenTextures } " to handle the common case of generating a single texture ID." } ;
 
+HELP: gen-framebuffer
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glGenFramebuffersEXT } " to handle the common case of generating a single framebuffer ID." } ;
+
+HELP: gen-renderbuffer
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glGenRenderbuffersEXT } " to handle the common case of generating a single render buffer ID." } ;
+
+HELP: gen-buffer
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glGenBuffers } " to handle the common case of generating a single buffer ID." } ;
+
+HELP: delete-texture
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glDeleteTextures } " to handle the common case of deleting a single texture ID." } ;
+
+HELP: delete-framebuffer
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glDeleteFramebuffersEXT } " to handle the common case of deleting a single framebuffer ID." } ;
+
+HELP: delete-renderbuffer
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glDeleteRenderbuffersEXT } " to handle the common case of deleting a single render buffer ID." } ;
+
+HELP: delete-buffer
+{ $values { "id" integer } }
+{ $description "Wrapper for " { $link glDeleteBuffers } " to handle the common case of deleting a single buffer ID." } ;
+
+{ gen-texture delete-texture } related-words
+{ gen-framebuffer delete-framebuffer } related-words
+{ gen-renderbuffer delete-renderbuffer } related-words
+{ gen-buffer delete-buffer } related-words
+
+HELP: framebuffer-incomplete?
+{ $values { "status/f" "The framebuffer error code, or " { $snippet "f" } " if the framebuffer is render-complete." } }
+{ $description "Checks the framebuffer currently bound by " { $link glBindFramebufferEXT } " or " { $link with-framebuffer } " to see if it is incomplete, i.e., it is not ready to be rendered to." } ;
+
+HELP: check-framebuffer
+{ $description "Checks the framebuffer currently bound by " { $link glBindFramebufferEXT } " or " { $link with-framebuffer } " with " { $link framebuffer-incomplete? } ", and throws a descriptive error if the framebuffer is incomplete." } ;
+
+HELP: with-framebuffer
+{ $values { "id" "The id of a framebuffer object." } { "quot" "a quotation" } }
+{ $description "Binds framebuffer " { $snippet "id" } " while calling " { $snippet "quot" } ", restoring the window framebuffer when finished." } ;
+
+HELP: bind-texture-unit
+{ $values { "id" "The id of a texture object." } { "target" "The texture target (e.g., " { $snippet "GL_TEXTURE_2D" } ")" } { "unit" "The texture unit to bind (e.g., " { $snippet "GL_TEXTURE0" } ")" } }
+{ $description "Binds texture " { $snippet "id" } " to texture target " { $snippet "target" } " of texture unit " { $snippet "unit" } ". Equivalent to " { $snippet "unit glActiveTexture target id glBindTexture" } "." } ;
+
+HELP: set-draw-buffers
+{ $values { "buffers" "A sequence of buffer words (e.g. " { $snippet GL_BACK } ", " { $snippet GL_COLOR_ATTACHMENT0_EXT } ")"} }
+{ $description "Wrapper for " { $link glDrawBuffers } ". Sets up the buffers named in the sequence for simultaneous drawing." } ;
+
 HELP: do-attribs
 { $values { "bits" integer } { "quot" quotation } }
 { $description "Wraps a quotation in " { $link glPushAttrib } "/" { $link glPopAttrib } " calls." } ;
@@ -148,11 +204,11 @@ HELP: gl-shader-info-log
 HELP: gl-program
 { $class-description { $snippet "gl-program" } " is a predicate class comprising values returned by OpenGL to represent proram objects. The following words are provided for creating and manipulating these objects:"
     { $list
-        { { $link <gl-program> } " - Link a set of shaders into a GLSL program" }
+        { { $link <gl-program> } ", " { $link <simple-gl-program> } " - Link a set of shaders into a GLSL program" }
         { { $link gl-program-ok? } " - Check whether a program object linked successfully" }
         { { $link check-gl-program } " - Throw an error unless a program object linked successfully" }
         { { $link gl-program-info-log } " - Retrieve the info log of messages generated by the GLSL linker" }
-        { { $link gl-program-shaders } " - Retrieve the set of shader objects composing the GLSL linker" }
+        { { $link gl-program-shaders } " - Retrieve the set of shader objects composing the GLSL program" }
         { { $link delete-gl-program } " - Invalidate a program object and all its attached shaders" }
         { { $link with-gl-program } " - Use a program object" }
     }
@@ -162,6 +218,12 @@ HELP: <gl-program>
 { $values { "shaders" "A sequence of " { $link gl-shader } " objects." } }
 { $description "Creates a new GLSL program object, attaches all the shader objects in the " { $snippet "shaders" } " sequence, and attempts to link them. The returned object can be checked for validity by " { $link check-gl-program } " or " { $link gl-program-ok? } ". Errors and warnings generated by the GLSL linker will be collected in the info log, available from " { $link gl-program-info-log } ".\n\nWhen the program object and its attached shaders are no longer needed, it should be deleted using " { $link delete-gl-program } "." } ;
 
+HELP: <simple-gl-program>
+{ $values { "vertex-shader-source" "A string containing GLSL vertex shader source" } { "fragment-shader-source" "A string containing GLSL fragment shader source" } }
+{ $description "Wrapper for " { $link <gl-program> } " for the simple case of compiling a single vertex shader and fragment shader and linking them into a GLSL program. Throws an exception if compiling or linking fails." } ;
+
+{ <gl-program> <simple-gl-program> } related-words
+
 HELP: gl-program-ok?
 { $values { "program" "A " { $link gl-program } " object" } }
 { $description "Returns a boolean value indicating whether the given program object linked successfully. Link errors and warnings are available in the program's info log, which can be gotten using " { $link gl-program-info-log } "." } ;
@@ -189,12 +251,16 @@ $nl
 { $subsection gl-color }
 { $subsection gl-vertex }
 { $subsection gl-translate }
+{ $subsection gen-texture }
+{ $subsection bind-texture-unit }
 "Combinators:"
 { $subsection do-state }
 { $subsection do-enabled }
 { $subsection do-attribs }
 { $subsection do-matrix }
 { $subsection with-translation }
+{ $subsection with-framebuffer }
+{ $subsection with-gl-program }
 { $subsection make-dlist }
 "Rendering geometric shapes:"
 { $subsection gl-line }

extra/opengl/opengl.factor

@@ -1,9 +1,9 @@
 ! Copyright (C) 2005, 2007 Slava Pestov.
 ! Portions copyright (C) 2007 Eduardo Cavazos.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: alien alien.c-types continuations kernel libc math namespaces sequences
+USING: alien alien.c-types continuations kernel libc math macros namespaces
-math.vectors math.constants math.functions opengl.gl opengl.glu
+math.vectors math.constants math.functions opengl.gl opengl.glu words
-combinators arrays ;
+combinators arrays sequences ;
 IN: opengl
 
 : coordinates [ first2 ] 2apply ;
@@ -115,7 +115,7 @@ IN: opengl
 : delete-buffer ( id -- )
     [ glDeleteBuffers ] (delete-gl-object) ;
 
-: framebuffer-incomplete? ( -- ? )
+: framebuffer-incomplete? ( -- status/f )
     GL_FRAMEBUFFER_EXT glCheckFramebufferStatusEXT
     dup GL_FRAMEBUFFER_COMPLETE_EXT = f rot ? ;
 
@@ -145,9 +145,12 @@ IN: opengl
     GL_FRAMEBUFFER_EXT swap GL_FRAMEBUFFER_ATTACHMENT_OBJECT_NAME_EXT
     0 <uint> [ glGetFramebufferAttachmentParameterivEXT ] keep *uint ;
     
-: set-draw-buffers ( buffers -- )
+: (set-draw-buffers) ( buffers -- )
     dup length swap >c-uint-array glDrawBuffers ;
 
+MACRO: set-draw-buffers ( buffers -- )
+    [ dup word? [ execute ] [ ] if ] map [ (set-draw-buffers) ] curry ;
+
 : do-attribs ( bits quot -- )
     swap glPushAttrib call glPopAttrib ; inline
 
@@ -206,7 +209,7 @@ TUPLE: sprite loc dim dim2 dlist texture ;
     swap sprite-loc v- gl-translate
     GL_TEXTURE_2D 0 glBindTexture ;
 
-: draw-rectangle ( lower-left upper-right -- )
+: rect-vertices ( lower-left upper-right -- )
     GL_QUADS [
         over first2 glVertex2d
         dup first pick second glVertex2d