basis/opengl/opengl-docs.factor

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