basis/opengl/opengl-docs.factor

   1 USING: help.markup help.syntax io kernel math quotations
   2 opengl.gl assocs vocabs.loader sequences accessors ;
   3 IN: opengl
   4
   5 HELP: gl-color
   6 { $values { "color" "a color specifier" } }
   7 { $description "Wrapper for " { $link glColor4d } " taking a color specifier." } ;
   8
   9 HELP: gl-error
  10 { $description "If the most recent OpenGL call resulted in an error, print the error to " { $link output-stream } "." } ;
  11
  12 HELP: do-enabled
  13 { $values { "what" integer } { "quot" quotation } }
  14 { $description "Wraps a quotation in " { $link glEnable } "/" { $link glDisable } " calls." } ;
  15
  16 HELP: do-matrix
  17 { $values { "mode" { $link GL_MODELVIEW } " or " { $link GL_PROJECTION } } { "quot" quotation } }
  18 { $description "Saves and restores the matrix specified by " { $snippet "mode" } " before and after calling the quotation." } ;
  19
  20 HELP: gl-line
  21 { $values { "a" "a pair of integers" } { "b" "a pair of integers" } }
  22 { $description "Draws a line between two points." } ;
  23
  24 HELP: gl-fill-rect
  25 { $values { "dim" "a pair of integers" } }
  26 { $description "Draws a filled rectangle with the top-left corner at the origin and the given dimensions." } ;
  27
  28 HELP: gl-rect
  29 { $values { "dim" "a pair of integers" } }
  30 { $description "Draws the outline of a rectangle with the top-left corner at the origin and the given dimensions." } ;
  31
  32 HELP: gen-texture
  33 { $values { "id" integer } }
  34 { $description "Wrapper for " { $link glGenTextures } " to handle the common case of generating a single texture ID." } ;
  35
  36 HELP: gen-gl-buffer
  37 { $values { "id" integer } }
  38 { $description "Wrapper for " { $link glGenBuffers } " to handle the common case of generating a single buffer ID." } ;
  39
  40 HELP: delete-texture
  41 { $values { "id" integer } }
  42 { $description "Wrapper for " { $link glDeleteTextures } " to handle the common case of deleting a single texture ID." } ;
  43
  44 HELP: delete-gl-buffer
  45 { $values { "id" integer } }
  46 { $description "Wrapper for " { $link glDeleteBuffers } " to handle the common case of deleting a single buffer ID." } ;
  47
  48 { gen-texture delete-texture } related-words
  49 { gen-gl-buffer delete-gl-buffer } related-words
  50
  51 HELP: bind-texture-unit
  52 { $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" } ")" } }
  53 { $description "Binds texture " { $snippet "id" } " to texture target " { $snippet "target" } " of texture unit " { $snippet "unit" } ". Equivalent to " { $snippet "unit glActiveTexture target id glBindTexture" } "." } ;
  54
  55 HELP: set-draw-buffers
  56 { $values { "buffers" "A sequence of buffer words (e.g. " { $snippet "GL_BACK" } ", " { $snippet "GL_COLOR_ATTACHMENT0_EXT" } ")"} }
  57 { $description "Wrapper for " { $link glDrawBuffers } ". Sets up the buffers named in the sequence for simultaneous drawing." } ;
  58
  59 HELP: do-attribs
  60 { $values { "bits" integer } { "quot" quotation } }
  61 { $description "Wraps a quotation in " { $link glPushAttrib } "/" { $link glPopAttrib } " calls." } ;
  62
  63 HELP: sprite
  64 { $class-description "A sprite is an OpenGL texture together with a display list which renders a textured quad. Sprites are used to draw text in the UI. Sprites have the following slots:"
  65     { $list
  66         { { $snippet "dlist" } " - an OpenGL display list ID" }
  67         { { $snippet "texture" } " - an OpenGL texture ID" }
  68         { { $snippet "loc" } " - top-left corner of the sprite" }
  69         { { $snippet "dim" } " - dimensions of the sprite" }
  70         { { $snippet "dim2" } " - dimensions of the sprite, rounded up to the nearest powers of two" }
  71     }
  72 } ;
  73
  74 HELP: gray-texture
  75 { $values { "sprite" sprite } { "pixmap" "an alien or byte array" } { "id" "an OpenGL texture ID" } }
  76 { $description "Creates a new OpenGL texture from a 1 byte per pixel image whose dimensions are equal to " { $snippet "dim2" } "." } ;
  77
  78 HELP: gen-dlist
  79 { $values { "id" integer } }
  80 { $description "Wrapper for " { $link glGenLists } " to handle the common case of generating a single display list ID." } ;
  81
  82 HELP: make-dlist
  83 { $values { "type" "one of " { $link GL_COMPILE } " or " { $link GL_COMPILE_AND_EXECUTE } } { "quot" quotation } { "id" "an OpenGL texture ID" } }
  84 { $description "Compiles the results of calling the quotation into a new OpenGL display list." } ;
  85
  86 HELP: gl-translate
  87 { $values { "point" "a pair of integers" } }
  88 { $description "Wrapper for " { $link glTranslated } " taking a point object." } ;
  89
  90 HELP: free-sprites
  91 { $values { "sprites" "a sequence of " { $link sprite } " instances" } }
  92 { $description "Deallocates native resources associated toa  sequence of sprites." } ;
  93
  94 HELP: with-translation
  95 { $values { "loc" "a pair of integers" } { "quot" quotation } }
  96 { $description "Calls the quotation with a translation by " { $snippet "loc" } " pixels applied to the current " { $link GL_MODELVIEW } " matrix, restoring the matrix when the quotation is done." } ;
  97
  98
  99 ARTICLE: "gl-utilities" "OpenGL utility words"
 100 "The " { $vocab-link "opengl" } " vocabulary implements some utility words to give OpenGL a more Factor-like feel."
 101 $nl
 102 "The " { $vocab-link "opengl.gl" } " and " { $vocab-link "opengl.glu" } " vocabularies have the actual OpenGL bindings."
 103 { $subsection "opengl-low-level" }
 104 "Wrappers:"
 105 { $subsection gl-color }
 106 { $subsection gl-translate }
 107 { $subsection gen-texture }
 108 { $subsection bind-texture-unit }
 109 "Combinators:"
 110 { $subsection do-enabled }
 111 { $subsection do-attribs }
 112 { $subsection do-matrix }
 113 { $subsection with-translation }
 114 { $subsection make-dlist }
 115 "Rendering geometric shapes:"
 116 { $subsection gl-line }
 117 { $subsection gl-fill-rect }
 118 { $subsection gl-rect }
 119 ;
 120
 121 ABOUT: "gl-utilities"