extra/gpu/render/render-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: alien alien.c-types alien.syntax byte-arrays classes
   3 gpu.buffers gpu.framebuffers gpu.shaders gpu.textures help.markup
   4 help.syntax images kernel math sequences
   5 specialized-arrays strings ;
   6 QUALIFIED-WITH: alien.c-types c
   7 QUALIFIED-WITH: math m
   8 SPECIALIZED-ARRAY: c:float
   9 SPECIALIZED-ARRAY: int
  10 SPECIALIZED-ARRAY: uint
  11 SPECIALIZED-ARRAY: ulong
  12 SPECIALIZED-ARRAY: void*
  13 IN: gpu.render
  14
  15 HELP: <index-elements>
  16 { $values
  17     { "ptr" gpu-data-ptr } { "count" integer } { "index-type" index-type }
  18     { "index-elements" index-elements }
  19 }
  20 { $description "Constructs an " { $link index-elements } " tuple." } ;
  21
  22 HELP: <index-range>
  23 { $values
  24     { "start" integer } { "count" integer }
  25     { "index-range" index-range }
  26 }
  27 { $description "Constructs an " { $link index-range } " tuple." } ;
  28
  29 HELP: <multi-index-elements>
  30 { $values
  31     { "buffer" { $maybe buffer } } { "ptrs" "an " { $link uint-array } " or " { $link void*-array } } { "counts" uint-array } { "index-type" index-type }
  32     { "multi-index-elements" multi-index-elements }
  33 }
  34 { $description "Constructs a " { $link multi-index-elements } " tuple." } ;
  35
  36 HELP: <multi-index-range>
  37 { $values
  38     { "starts" uint-array } { "counts" uint-array }
  39     { "multi-index-range" multi-index-range }
  40 }
  41 { $description "Constructs a " { $link multi-index-range } " tuple." } ;
  42
  43 HELP: UNIFORM-TUPLE:
  44 { $syntax """UNIFORM-TUPLE: class-name
  45     { "slot" uniform-type dimension }
  46     { "slot" uniform-type dimension }
  47     ...
  48     { "slot" uniform-type dimension } ;""" }
  49 { $description "Defines a new " { $link uniform-tuple } " class. Tuples of the new class can be used as the " { $snippet "uniforms" } " slot of a " { $link render-set } " in order to set the uniform parameters of the active shader program. The " { $link uniform-type } " of each slot defines the component type, and the " { $snippet "dimension" } " specifies an array length if not " { $link f } "."
  50 $nl
  51 "Uniform parameters are passed from Factor to the shader program through the uniform tuple as follows:"
  52 { $list
  53 { { $link int-uniform } "s and " { $link uint-uniform } "s take their values from Factor " { $link integer } "s." }
  54 { { $link float-uniform } "s take their values from Factor " { $link m:float } "s." }
  55 { { $link bool-uniform } "s take their values from Factor " { $link boolean } "s." }
  56 { { $link texture-uniform } "s take their values from " { $link texture } " objects." }
  57 { "Vector uniforms take their values from Factor " { $link sequence } "s of the corresponding component type."
  58     { $list
  59     { "Float vector types: " { $link vec2-uniform } ", " { $link vec3-uniform } ", " { $link vec4-uniform } }
  60     { "Integer vector types: " { $link ivec2-uniform } ", " { $link ivec3-uniform } ", " { $link ivec4-uniform } }
  61     { "Unsigned integer vector types: " { $link uvec2-uniform } ", " { $link uvec3-uniform } ", " { $link uvec4-uniform } }
  62     { "Boolean vector types: " { $link bvec2-uniform } ", " { $link bvec3-uniform } ", " { $link bvec4-uniform } }
  63     }
  64 }
  65 { "Matrix uniforms take their values from row-major Factor " { $link sequence } "s of sequences of floats. Matrix types are:"
  66     { $list
  67     { { $link mat2-uniform } ", " { $link mat2x3-uniform } ", " { $link mat2x4-uniform } }
  68     { { $link mat3x2-uniform } ", " { $link mat3-uniform } ", " { $link mat3x4-uniform } }
  69     { { $link mat4x2-uniform } ", " { $link mat4x3-uniform } ", " { $link mat4-uniform } }
  70     }
  71 "Rectangular matrix type names are column x row."
  72 }
  73 { "Uniform slots can also be defined as other " { $snippet "uniform-tuple" } " types to bind uniform structures. The uniform structure will take its value from the slots of a tuple of the given type." }
  74 { "Array uniforms are passed as Factor sequences of the corresponding value type above." }
  75 }
  76 $nl
  77 "A value of a uniform tuple type is a standard Factor tuple. Uniform tuples are constructed with " { $link new } " or " { $link boa } ", and values are placed inside them using standard slot accessors."
  78 } ;
  79
  80 HELP: bool-uniform
  81 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a boolean uniform parameter." } ;
  82
  83 HELP: bvec2-uniform
  84 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a two-component boolean vector uniform parameter." } ;
  85
  86 HELP: bvec3-uniform
  87 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a three-component boolean vector uniform parameter." } ;
  88
  89 HELP: bvec4-uniform
  90 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a four-component boolean vector uniform parameter." } ;
  91
  92 HELP: define-uniform-tuple
  93 { $values
  94     { "class" class } { "superclass" class } { "uniforms" sequence }
  95 }
  96 { $description "Defines a new " { $link uniform-tuple } " as a subclass of " { $snippet "superclass" } " with the slots specified by the " { $link uniform } " tuple values in " { $snippet "uniforms" } ". The runtime equivalent of " { $link POSTPONE: UNIFORM-TUPLE: } ". This word must be called inside a compilation unit." } ;
  97
  98 HELP: float-uniform
  99 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a float uniform parameter." } ;
 100
 101 { index-elements index-range multi-index-elements multi-index-range } related-words
 102
 103 HELP: index-elements
 104 { $class-description "Objects of this tuple class can be passed as the " { $snippet "indexes" } " slot of a " { $link render-set } " to instruct " { $link render } " to assemble primitives from the active " { $link vertex-array } " by using an array of indexes in CPU or GPU memory."
 105 { $list
 106 { "The " { $snippet "ptr" } " slot contains a " { $link byte-array } ", " { $link alien } ", or " { $link buffer-ptr } " value referencing the beginning of the index array." }
 107 { "The " { $snippet "count" } " slot contains an " { $link integer } " value specifying the number of indexes to supply from the array." }
 108 { "The " { $snippet "index-type" } " slot contains an " { $link index-type } " value specifying whether the array consists of " { $link ubyte-indexes } ", " { $link ushort-indexes } ", or " { $link uint-indexes } "." }
 109 } } ;
 110
 111 HELP: index-range
 112 { $class-description "Objects of this tuple class can be passed as the " { $snippet "indexes" } " slot of a " { $link render-set } " to instruct " { $link render } " to assemble primitives sequentially from a slice of the active " { $link vertex-array } "."
 113 { $list
 114 { "The " { $snippet "start" } " slot contains an " { $link integer } " value indicating the first element of the array to draw." }
 115 { "The " { $snippet "count" } " slot contains an " { $link integer } " value indicating the number of elements to draw." }
 116 } } ;
 117
 118 HELP: index-type
 119 { $class-description "The " { $snippet "index-type" } " slot of an " { $link index-elements } " or " { $link multi-index-elements } " tuple indicates the type of the index array's elements: one-byte " { $link ubyte-indexes } ", two-byte " { $link ushort-indexes } ", or four-byte " { $link uint-indexes } "."  } ;
 120
 121 { index-type ubyte-indexes ushort-indexes uint-indexes } related-words
 122
 123 HELP: int-uniform
 124 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a signed integer uniform parameter." } ;
 125
 126 HELP: invalid-uniform-type
 127 { $values
 128     { "uniform" uniform }
 129 }
 130 { $description "Throws an error indicating that a slot of a " { $link uniform-tuple } " has been declared to have an invalid type." } ;
 131
 132 HELP: ivec2-uniform
 133 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a two-component integer vector uniform parameter." } ;
 134
 135 HELP: ivec3-uniform
 136 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a three-component integer vector uniform parameter." } ;
 137
 138 HELP: ivec4-uniform
 139 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a four-component integer vector uniform parameter." } ;
 140
 141 HELP: lines-mode
 142 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to assemble a line from each pair of indexed vertex array elements." } ;
 143
 144 HELP: line-loop-mode
 145 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to assemble a connected loop of lines from each consecutive pair of indexed vertex array elements, adding another line to close the last and first elements." } ;
 146
 147 HELP: line-strip-mode
 148 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to assemble a connected strip of lines from each consecutive pair of indexed vertex array elements." } ;
 149
 150 HELP: mat2-uniform
 151 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 2x2 square float matrix uniform parameter." } ;
 152
 153 HELP: mat2x3-uniform
 154 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 2-column, 3-row float matrix uniform parameter." } ;
 155
 156 HELP: mat2x4-uniform
 157 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 2-column, 4-row float matrix uniform parameter." } ;
 158
 159 HELP: mat3x2-uniform
 160 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 3-column, 2-row float matrix uniform parameter." } ;
 161
 162 HELP: mat3-uniform
 163 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 3x3 square float matrix uniform parameter." } ;
 164
 165 HELP: mat3x4-uniform
 166 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 3-column, 4-row float matrix uniform parameter." } ;
 167
 168 HELP: mat4x2-uniform
 169 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 4-column, 2-row float matrix uniform parameter." } ;
 170
 171 HELP: mat4x3-uniform
 172 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 4-column, 3-row float matrix uniform parameter." } ;
 173
 174 HELP: mat4-uniform
 175 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a 4x4 square float matrix uniform parameter." } ;
 176
 177 HELP: multi-index-elements
 178 { $class-description "Objects of this tuple class can be passed as the " { $snippet "indexes" } " slot of a non-instanced " { $link render-set } " to instruct " { $link render } " to assemble primitives from the active " { $link vertex-array } " by using multiple arrays of indexes in CPU or GPU memory."
 179 { $list
 180 { "The " { $snippet "buffer" } " slot contains either a " { $link buffer } " object to read indexes from, or " { $link f } " to read from CPU memory." }
 181 { "The " { $snippet "ptrs" } " slot contains either a " { $link void*-array } " of pointers to the starts of index data, or a pointer-sized " { $link ulong-array } " of offsets into " { $snippet "buffer" } "." }
 182 { "The " { $snippet "counts" } " slot contains a " { $link uint-array } " containing the number of indexes to read from each pointer or offset in " { $snippet "ptrs" } "." }
 183 { "The " { $snippet "index-type" } " slot contains an " { $link index-type } " value specifying whether the arrays consist of " { $link ubyte-indexes } ", " { $link ushort-indexes } ", or " { $link uint-indexes } "." }
 184 } } ;
 185
 186 HELP: multi-index-range
 187 { $class-description "Objects of this tuple class can be passed as the " { $snippet "indexes" } " slot of a non-instanced " { $link render-set } " to instruct " { $link render } " to assemble primitives from the active " { $link vertex-array } " by using multiple consecutive slices of its elements."
 188 { $list
 189 { "The " { $snippet "starts" } " slot contains a " { $link uint-array } " of indexes into the array from which to start generating primitives." }
 190 { "The " { $snippet "counts" } " slot contains a " { $link uint-array } " of corresponding counts of indexes to read from each specified " { $snippet "start" } " index." }
 191 } } ;
 192
 193 HELP: points-mode
 194 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to generate a point for each indexed vertex array element." } ;
 195
 196 HELP: primitive-mode
 197 { $class-description "The " { $snippet "primitive-mode" } " slot of a " { $link render-set } " tells " { $link render } " what kind of primitives to generate and how to assemble them from the selected elements of the active " { $link vertex-array } "."  }
 198 { $list
 199 { { $link points-mode } " causes each element to generate a point." }
 200 { { $link lines-mode } " causes each pair of elements to generate a disconnected line." }
 201 { { $link line-strip-mode } " causes each consecutive pair of elements to generate a connected strip of lines." }
 202 { { $link line-loop-mode } " causes each consecutive pair of elements to generate a connected loop of lines, with an extra line connecting the last and first elements." }
 203 { { $link triangles-mode } " causes every 3 elements to generate an independent triangle." }
 204 { { $link triangle-strip-mode } " causes every consecutive group of 3 elements to generate a connected strip of triangles." }
 205 { { $link triangle-fan-mode } " causes a triangle to be generated from the first element and every subsequent consecutive pair of elements in a fan pattern." } } ;
 206
 207 { primitive-mode points-mode lines-mode line-strip-mode line-loop-mode triangles-mode triangle-strip-mode triangle-fan-mode } related-words
 208
 209 HELP: render
 210 { $values
 211     { "render-set" render-set }
 212 }
 213 { $description "Submits a rendering job to the GPU. The values in the " { $link render-set } " tuple describe the job." } ;
 214
 215 HELP: render-set
 216 { $class-description "A " { $snippet "render-set" } " tuple describes a GPU rendering job."
 217 { $list
 218 { "The " { $link primitive-mode } " slot determines what kind of primitives should be rendered, and how they should be assembled." }
 219 { "The " { $link vertex-array } " slot supplies the shader program and vertex data to be rendered." }
 220 { "The " { $snippet "uniforms" } " slot contains a " { $link uniform-tuple } " with values for the shader program's uniform parameters." }
 221 { "The " { $snippet "indexes" } " slot contains one of the " { $link vertex-indexes } " types and selects elements from the vertex array to be rendered." }
 222 { "The " { $snippet "instances" } " slot, if not " { $link f } ", instructs the GPU to render several instances of the same set of vertexes. Instancing requires OpenGL 3.1 or one of the " { $snippet "GL_EXT_draw_instanced" } " or " { $snippet "GL_ARB_draw_instanced" } " extensions." }
 223 { "The " { $snippet "framebuffer" } " slot determines the target for the rendering output. Either the " { $link system-framebuffer } " or a user-created " { $link framebuffer } " object can be specified. " { $link f } " can also be specified to disable rasterization and only run the vertex transformation rendering stage." }
 224 { "The " { $snippet "output-attachments" } " slot specifies which of the framebuffer's " { $link color-attachment-ref } "s to write the fragment shader's color output to. If the shader uses " { $snippet "gl_FragColor" } " or " { $snippet "gl_FragData[n]" } " to write its output, then " { $snippet "output-attachments" } " should be an array of " { $link color-attachment-ref } "s, and the output to color attachment binding is determined positionally. If the shader uses named output values, then " { $snippet "output-attachments" } " should be a list of string/" { $link color-attachment-ref } " pairs, mapping output names to color attachments." }
 225 { "The " { $snippet "transform-feedback-output" } " slot specifies a target for transform feedback output from the vertex shader: either an entire " { $link buffer } ", a " { $link buffer-range } " subset, or a " { $link buffer-ptr } " offset into the buffer. If " { $link f } ", no transform feedback output is collected. The shader program associated with " { $snippet "vertex-array" } " must have a transform feedback output format specified." }
 226 } }
 227 { $notes "User-created framebuffers require OpenGL 3.0 or one of the " { $snippet "GL_EXT_framebuffer_object" } " or " { $snippet "GL_ARB_framebuffer_object" } " extensions. Disabling rasterization requires OpenGL 3.0 or the " { $snippet "GL_EXT_transform_feedback" } " extension. Named output-attachment values are available in GLSL 1.30 or later, and GLSL 1.20 and earlier using the " { $snippet "GL_EXT_gpu_shader4" } " extension. Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ;
 228
 229 HELP: bind-uniforms
 230 { $values { "program-instance" program-instance } { "uniforms" uniform-tuple } }
 231 { $description "Binds the uniform shader parameters for " { $snippet "program-instance" } " using values from the given uniform tuple." }
 232 { $notes "The " { $link render } " word uses this word. Calling this word directly is only necessary if uniform parameters need to be bound independently of a " { $snippet "render" } " operation." } ;
 233
 234 { render render-set } related-words
 235
 236 HELP: texture-uniform
 237 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a texture uniform parameter." } ;
 238
 239 HELP: triangle-fan-mode
 240 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to generate a fan of triangles using the first indexed vertex array element and every subsequent consecutive pair of elements." } ;
 241
 242 HELP: triangle-strip-mode
 243 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to generate a strip of triangles using every consecutive group of 3 indexed vertex array elements." } ;
 244
 245 HELP: triangles-mode
 246 { $class-description "This " { $link primitive-mode } " value instructs " { $link render } " to generate a triangle for each group of 3 indexed vertex array elements." } ;
 247
 248 HELP: ubyte-indexes
 249 { $class-description "This " { $link index-type } " indicates that an " { $link index-elements } " or " { $link multi-index-elements } " buffer consists of unsigned byte indexes." } ;
 250
 251 HELP: uint-indexes
 252 { $class-description "This " { $link index-type } " indicates that an " { $link index-elements } " or " { $link multi-index-elements } " buffer consists of four-byte unsigned int indexes." } ;
 253
 254 HELP: uint-uniform
 255 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to an unsigned integer uniform parameter." } ;
 256
 257 HELP: uniform
 258 { $class-description "Values of this tuple type are passed to " { $link define-uniform-tuple } " to define a new " { $link uniform-tuple } " type." } ;
 259
 260 HELP: uniform-tuple
 261 { $class-description "The base class for tuple types defined with " { $link POSTPONE: UNIFORM-TUPLE: } ". A uniform tuple is used as part of a " { $link render-set } " to supply values for a shader program's uniform parameters. See the " { $link POSTPONE: UNIFORM-TUPLE: } " documentation for details on how uniform tuples are defined and used." } ;
 262
 263 HELP: uniform-type
 264 { $class-description { $snippet "uniform-type" } " values are used as part of a " { $link POSTPONE: UNIFORM-TUPLE: } " definition to define the types of uniform slots." } ;
 265
 266 HELP: ushort-indexes
 267 { $class-description "This " { $link index-type } " indicates that an " { $link index-elements } " or " { $link multi-index-elements } " buffer consists of two-byte unsigned short indexes." } ;
 268
 269 { index-type ubyte-indexes ushort-indexes uint-indexes } related-words
 270
 271 HELP: uvec2-uniform
 272 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a two-component unsigned integer vector uniform parameter." } ;
 273
 274 HELP: uvec3-uniform
 275 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a three-component unsigned integer vector uniform parameter." } ;
 276
 277 HELP: uvec4-uniform
 278 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a four-component unsigned integer vector uniform parameter." } ;
 279
 280 HELP: vec2-uniform
 281 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a two-component float vector uniform parameter." } ;
 282
 283 HELP: vec3-uniform
 284 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a three-component float vector uniform parameter." } ;
 285
 286 HELP: vec4-uniform
 287 { $class-description "This " { $link uniform-type } " indicates that a slot of a " { $link uniform-tuple } " corresponds to a four-component float vector uniform parameter." } ;
 288
 289 HELP: vertex-indexes
 290 { $class-description "This class is a union of the following tuple types, any of which can be used as the " { $snippet "indexes" } " slot of a " { $link render-set } " to select elements from a " { $link vertex-array } " for rendering."
 291 { $list
 292 { "An " { $link index-range } " value submits a sequential slice of a vertex array for rendering." }
 293 { "An " { $link index-elements } " value submits vertex array elements in an order specified by an array of indexes." }
 294 { "A " { $link multi-index-range } " value submits multiple sequential slices of a vertex array." }
 295 { "A " { $link multi-index-elements } " value submits multiple separate lists of indexed vertex array elements." }
 296 } } ;
 297
 298 ARTICLE: "gpu.render" "Rendering"
 299 "The " { $vocab-link "gpu.render" } " vocabulary contains words for organizing and submitting data to the GPU for rendering."
 300 { $subsections
 301     render
 302     render-set
 303 }
 304 { $link uniform-tuple } "s provide Factor types for containing and submitting shader uniform parameters:"
 305 { $subsections POSTPONE: UNIFORM-TUPLE: }
 306 ;
 307
 308 ABOUT: "gpu.render"