extra/gpu/shaders/shaders-docs.factor

   1 ! Copyright (C) 2009 Joe Groff.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes classes.struct gpu.buffers gpu.shaders.private
   4 help.markup help.syntax images math sequences strings words ;
   5 IN: gpu.shaders
   6
   7 HELP: <multi-vertex-array>
   8 { $values
   9     { "vertex-formats" "a list of " { $link buffer-ptr } "/" { $link vertex-format } " pairs" }
  10     { "program-instance" program-instance }
  11     { "vertex-array" vertex-array }
  12 }
  13 { $description "Creates a new " { $link vertex-array } " to feed data to " { $snippet "program-instance" } " from the set of " { $link buffer } "s specified in " { $snippet "vertex-formats" } ". The first element of each pair in " { $snippet "vertex-formats" } " can be either a " { $link buffer-ptr } " or a " { $link buffer } "; in the latter case, vertex data in the associated format is read from the beginning of the buffer." } ;
  14
  15 HELP: <program-instance>
  16 { $values
  17     { "program" program }
  18     { "instance" program-instance }
  19 }
  20 { $description "Compiles and links an instance of " { $snippet "program" } " for the current graphics context. If an instance already exists for " { $snippet "program" } " in the current context, it is reused." } ;
  21
  22 HELP: <shader-instance>
  23 { $values
  24     { "shader" shader }
  25     { "instance" shader-instance }
  26 }
  27 { $description "Compiles an instance of " { $snippet "shader" } " for the current graphics context. If an instance already exists for " { $snippet "shader" } " in the current context, it is reused." } ;
  28
  29 HELP: <vertex-array-object>
  30 { $values
  31   { "vertex-buffer" "a vertex buffer" }
  32   { "program-instance" program-instance }
  33   { "format" vertex-format }
  34 }
  35 { $description "Creates a new vertex array object." } ;
  36
  37 HELP: feedback-format:
  38 { $syntax "feedback-format: vertex-format" }
  39 { $description "When used as part of a " { $link POSTPONE: GLSL-PROGRAM: } " definition, this syntax specifies the " { $link vertex-format } " in which transform feedback output will be generated." } ;
  40
  41 HELP: GLSL-PROGRAM:
  42 { $syntax "GLSL-PROGRAM: program-name shader shader ... [vertex-format vertex-format ...] [feedback-format: vertex-format] ;" }
  43 { $description "Defines a new shader " { $link program } " named " { $snippet "program-name" } ". When the program is instantiated with " { $link <program-instance> } ", it will link together instances of all of the specified " { $link shader } "s to create the program instance. If any " { $link vertex-format } "s are specified, their attributes will be pre-assigned attribute indexes at link time, to ensure that their indexes remain constant if the program is refreshed with " { $link refresh-program } ". A transform feedback vertex format may optionally be specified with " { $link POSTPONE: feedback-format: } "; if the program is used to collect transform feedback, the given vertex format will be used for the output." }
  44 { $notes "Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ;
  45
  46 HELP: GLSL-SHADER-FILE:
  47 { $syntax "GLSL-SHADER-FILE: shader-name shader-kind \"filename\"" }
  48 { $description "Defines a new " { $link shader } " of kind " { $link shader-kind } " named " { $snippet "shader-name" } ". The shader will read its source code from " { $snippet "filename" } " in the current Factor source file's directory." } ;
  49
  50 HELP: GLSL-SHADER:
  51 { $syntax "GLSL-SHADER: shader-name shader-kind
  52
  53 shader source
  54
  55 ;" }
  56 { $description "Defines a new " { $link shader } " of kind " { $link shader-kind } " named " { $snippet "shader-name" } ". The shader will read its source code from the current Factor source file between the " { $snippet "GLSL-SHADER:" } " line and the first subsequent line with a single semicolon on it." } ;
  57
  58 HELP: VERTEX-FORMAT:
  59 { $syntax "VERTEX-FORMAT: format-name
  60     { \"attribute\"/f component-type dimension normalize? }
  61     { \"attribute\"/f component-type dimension normalize? }
  62     ...
  63     { \"attribute\"/f component-type dimension normalize? } ;" }
  64 { $description "Defines a new binary " { $link vertex-format } " for structuring vertex data stored in " { $link buffer } "s. Each " { $snippet "attribute" } " name either corresponds to an input parameter of a vertex shader, or is " { $link f } " to include padding in the vertex format. The " { $link component-type } " determines the format of the components, and the " { $snippet "dimension" } " determines the number of components. If the " { $snippet "component-type" } " is an integer type and " { $snippet "normalize?" } " is true, the component values will be scaled to the range 0.0 to 1.0 when fed to the vertex shader; otherwise, they will be cast to floats retaining their integral values." } ;
  65
  66 HELP: VERTEX-STRUCT:
  67 { $syntax "VERTEX-STRUCT: struct-name format-name" }
  68 { $description "Defines a struct class (like " { $link POSTPONE: STRUCT: } ") with the same binary format and component types as the given " { $link vertex-format } "." } ;
  69
  70 { POSTPONE: GLSL-PROGRAM: POSTPONE: GLSL-SHADER-FILE: POSTPONE: GLSL-SHADER: } related-words
  71
  72 HELP: attribute-index
  73 { $values
  74     { "program-instance" program-instance } { "attribute-name" string }
  75     { "index" integer }
  76 }
  77 { $description "Returns the numeric index of the vertex attribute named " { $snippet "attribute-name" } " in " { $snippet "program-instance" } "." } ;
  78
  79 HELP: <vertex-array>
  80 { $values
  81     { "vertex-buffer" "a " { $link buffer } " or " { $link buffer-ptr } } { "program-instance" program-instance }
  82     { "vertex-array" vertex-array }
  83 }
  84 { $description "Creates a new " { $link vertex-array } " from the entire contents of a single " { $link buffer } " for use with a " { $link program-instance } ". The data in " { $snippet "buffer" } " is taken in the first " { $link vertex-format } " specified in the program instance's originating " { $link POSTPONE: GLSL-PROGRAM: } " definition. If the program has no associated vertex formats, an error will be thrown. To specify a different vertex format, use " { $link <vertex-array*> } "." } ;
  85
  86 HELP: <vertex-array*>
  87 { $values
  88     { "vertex-buffer" "a " { $link buffer } " or " { $link buffer-ptr } } { "program-instance" program-instance } { "format" vertex-format }
  89     { "vertex-array" vertex-array }
  90 }
  91 { $description "Creates a new " { $link vertex-array } " from the entire contents of a single " { $link buffer } " for use with a " { $link program-instance } ". The data in " { $snippet "buffer" } " is taken in the specified " { $link vertex-format } "." } ;
  92
  93 { vertex-array <multi-vertex-array> <vertex-array> <vertex-array*> } related-words
  94
  95 HELP: compile-shader-error
  96 { $class-description "An error compiling the source for a " { $link shader } "."
  97 { $list
  98 { "The " { $snippet "shader" } " slot indicates the shader that failed to compile." }
  99 { "The " { $snippet "log" } " slot contains the error string from the GLSL compiler." }
 100 } } ;
 101
 102 HELP: define-vertex-format
 103 { $values
 104     { "class" class } { "vertex-attributes" sequence }
 105 }
 106 { $description "Defines a new " { $link vertex-format } " with the binary format specified by the " { $link vertex-attribute } " tuple values in " { $snippet "vertex-attributes" } ". The runtime equivalent of " { $link POSTPONE: VERTEX-FORMAT: } ". This word must be called inside a compilation unit." } ;
 107
 108 HELP: define-vertex-struct
 109 { $values
 110     { "class" word } { "vertex-format" vertex-format }
 111 }
 112 { $description "Defines a new struct C type from a " { $link vertex-format } ". The runtime equivalent of " { $link POSTPONE: VERTEX-STRUCT: } ". This word must be called inside a compilation unit." } ;
 113
 114 HELP: fragment-shader
 115 { $class-description "This " { $link shader-kind } " indicates that a " { $link shader } " is a fragment shader." } ;
 116
 117 HELP: link-program-error
 118 { $class-description "An error linking the constituent shaders of a " { $link program } "."
 119 { $list
 120 { "The " { $snippet "program" } " slot indicates the program that failed to link." }
 121 { "The " { $snippet "log" } " slot contains the error string from the GLSL linker." }
 122 } } ;
 123
 124 { compile-shader-error link-program-error } related-words
 125
 126 HELP: output-index
 127 { $values
 128     { "program-instance" program-instance } { "output-name" string }
 129     { "index" integer }
 130 }
 131 { $description "Returns the numeric index of the fragment shader output named " { $snippet "output-name" } " in " { $snippet "program-instance" } "." }
 132 { $notes "Named fragment shader outputs require OpenGL 3.0 or later and GLSL 1.30 or later, or OpenGL 2.0 or later and GLSL 1.20 or earlier with the " { $snippet "GL_EXT_gpu_shader4" } " extension." } ;
 133
 134 HELP: program
 135 { $class-description "A " { $snippet "program" } " provides a specification for linking a " { $link program-instance } " in a graphics context. Programs are defined with " { $link POSTPONE: GLSL-PROGRAM: } " and instantiated for a context with " { $link <program-instance> } "." } ;
 136
 137 HELP: program-instance
 138 { $class-description "A " { $snippet "program-instance" } " is a shader " { $link program } " that has been compiled and linked for a graphics context using " { $link <program-instance> } "." } ;
 139
 140 HELP: refresh-program
 141 { $values
 142     { "program" program }
 143 }
 144 { $description "Rereads the source code for every " { $link shader } " in " { $link program } " and attempts to refresh all the existing " { $link shader-instance } "s and " { $link program-instance } "s for those shaders. If any of the new source code fails to compile or link, the existing valid shader and program instances will remain untouched. However, subsequent attempts to compile new shader or program instances will still attempt to use the new source code. If the compilation and linking succeed, the existing shader and program instances will be updated on the fly to reference the newly compiled code." } ;
 145
 146 HELP: shader
 147 { $class-description "A " { $snippet "shader" } " provides a block of GLSL source code that can be compiled into a " { $link shader-instance } " in a graphics context. Shaders are defined with " { $link POSTPONE: GLSL-SHADER: } " or " { $link POSTPONE: GLSL-SHADER-FILE: } " and instantiated for a context with " { $link <shader-instance> } "." } ;
 148
 149 HELP: shader-instance
 150 { $class-description "A " { $snippet "shader-instance" } " is a " { $link shader } " that has been compiled for a graphics context using " { $link <shader-instance> } "." } ;
 151
 152 HELP: shader-kind
 153 { $class-description "A " { $snippet "shader-kind" } " value is passed as part of a " { $link POSTPONE: GLSL-SHADER: } " or " { $link POSTPONE: GLSL-SHADER-FILE: } " definition to indicate the kind of " { $link shader } " being defined."
 154 { $list
 155 { { $link vertex-shader } "s run during primitive assembly and map input vertex data to positions in screen space for rasterization." }
 156 { { $link fragment-shader } "s run as part of rasterization and decide the final rendered output of a primitive as the outputs of the vertex shader are interpolated across its surface." }
 157 } } ;
 158
 159 HELP: too-many-feedback-formats-error
 160 { $class-description "This error is thrown when a " { $link POSTPONE: GLSL-PROGRAM: } " definition attempts to include more than one " { $link vertex-format } " for transform feedback formatting." } ;
 161
 162 HELP: invalid-link-feedback-format-error
 163 { $class-description "This error is thrown when the " { $link vertex-format } " specified as the transform feedback output format of a " { $link program } " is not suitable for the purpose. Transform feedback formats do not support padding (fields with a name of " { $link f } ")." } ;
 164
 165 HELP: inaccurate-feedback-attribute-error
 166 { $class-description "This error is thrown when the " { $link vertex-format } " specified as the transform feedback output format of a " { $link program } " does not match the format of the output attributes linked into a " { $link program-instance } "." } ;
 167
 168 HELP: uniform-index
 169 { $values
 170     { "program-instance" program-instance } { "uniform-name" string }
 171     { "index" integer }
 172 }
 173 { $description "Returns the numeric index of the uniform parameter named " { $snippet "output-name" } " in " { $snippet "program-instance" } "." } ;
 174
 175 HELP: vertex-shader
 176 { $class-description "This " { $link shader-kind } " indicates that a " { $link shader } " is a vertex shader." } ;
 177
 178 HELP: vertex-array
 179 { $class-description "A " { $snippet "vertex-array" } " object associates a shader " { $link program-instance } " with vertex attribute data from one or more " { $link buffer } "s. The format of the binary data inside these buffers is described using " { $link vertex-format } "s. " { $snippet "vertex-array" } "s are constructed using the " { $link <multi-vertex-array> } " or " { $link <vertex-array*> } " words. The actual type of a vertex-array object is opaque, but the " { $link vertex-array-buffers } " word can be used to query a vertex array object for its component buffers." } ;
 180
 181 HELP: vertex-array-buffers
 182 { $values
 183     { "vertex-array" vertex-array }
 184     { "buffers" sequence }
 185 }
 186 { $description "Returns a sequence containing all of the " { $link buffer } " objects that make up " { $snippet "vertex-array" } "." } ;
 187
 188 HELP: vertex-array-buffer
 189 { $values
 190     { "vertex-array" vertex-array }
 191     { "vertex-buffer" buffer }
 192 }
 193 { $description "Returns the first " { $link buffer } " object that makes up " { $snippet "vertex-array" } "." } ;
 194
 195 { vertex-array-buffer vertex-array-buffers } related-words
 196
 197 HELP: vertex-attribute
 198 { $class-description "This tuple type is passed to " { $link define-vertex-format } " to define a new " { $link vertex-format } " type." } ;
 199
 200 HELP: vertex-format
 201 { $class-description "This class encompasses all vertex formats defined by " { $link POSTPONE: VERTEX-FORMAT: } ". A vertex format defines the binary layout of vertex attribute data in a " { $link buffer } " for use as part of a " { $link vertex-array } ". See the " { $link POSTPONE: VERTEX-FORMAT: } " documentation for details on how vertex formats are defined." } ;
 202
 203 HELP: vertex-format-size
 204 { $values
 205     { "format" vertex-format }
 206     { "size" integer }
 207 }
 208 { $description "Returns the size in bytes of a set of vertex attributes in " { $snippet "format" } "." } ;
 209
 210 ARTICLE: "gpu.shaders" "Shader objects"
 211 "The " { $vocab-link "gpu.shaders" } " vocabulary supports defining, compiling, and linking " { $link shader } "s into " { $link program } "s that run on the GPU and control rendering."
 212 { $subsections
 213     POSTPONE: GLSL-PROGRAM:
 214     POSTPONE: GLSL-SHADER:
 215     POSTPONE: GLSL-SHADER-FILE:
 216 }
 217 "A program must be instantiated for each graphics context it is used in:"
 218 { $subsections <program-instance> }
 219 "Program instances can be updated on the fly, allowing for interactive development of shaders:"
 220 { $subsections refresh-program }
 221 "Render data inside GPU " { $link buffer } "s is organized into " { $link vertex-array } "s for consumption by shader code:"
 222 { $subsections
 223     vertex-array
 224     <multi-vertex-array>
 225     <vertex-array*>
 226     <vertex-array>
 227     POSTPONE: VERTEX-FORMAT:
 228 } ;
 229
 230 ABOUT: "gpu.shaders"