extra/gpu/shaders/shaders-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: classes classes.struct gpu.buffers help.markup help.syntax
   3 images kernel math multiline quotations sequences strings words ;
   4 IN: gpu.shaders
   5
   6 HELP: <program-instance>
   7 { $values
   8     { "program" program }
   9     { "instance" program-instance }
  10 }
  11 { $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." } ;
  12
  13 HELP: <shader-instance>
  14 { $values
  15     { "shader" shader }
  16     { "instance" shader-instance }
  17 }
  18 { $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." } ;
  19
  20 HELP: <vertex-array>
  21 { $values
  22     { "program-instance" program-instance } { "vertex-formats" "a list of " { $link buffer-ptr } "/" { $link vertex-format } " pairs" }
  23     { "vertex-array" vertex-array }
  24 }
  25 { $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" } "." } ;
  26
  27 HELP: GLSL-PROGRAM:
  28 { $syntax "GLSL-PROGRAM: program-name shader shader ... shader [vertex-format] ;" }
  29 { $description "Defines a new " { $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. A single " { $link vertex-array } " may optionally be specified; if the program is used to collect transform feedback, this format will be used for the output." }
  30 { $notes "Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ;
  31
  32 HELP: GLSL-SHADER-FILE:
  33 { $syntax "GLSL-SHADER-FILE: shader-name shader-kind \"filename\"" }
  34 { $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." } ;
  35
  36 HELP: GLSL-SHADER:
  37 { $syntax """GLSL-SHADER-FILE: shader-name shader-kind
  38
  39 shader source
  40
  41 ;""" }
  42 { $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." } ;
  43
  44 HELP: VERTEX-FORMAT:
  45 { $syntax """VERTEX-FORMAT: format-name
  46     { "attribute"/f component-type dimension normalize? }
  47     { "attribute"/f component-type dimension normalize? }
  48     ...
  49     { "attribute"/f component-type dimension normalize? } ;""" }
  50 { $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." } ;
  51
  52 HELP: VERTEX-STRUCT:
  53 { $syntax """VERTEX-STRUCT: struct-name format-name""" }
  54 { $description "Defines a struct class (like " { $link POSTPONE: STRUCT: } ") with the same binary format and component types as the given " { $link vertex-format } "." } ;
  55
  56 { POSTPONE: GLSL-PROGRAM: POSTPONE: GLSL-SHADER-FILE: POSTPONE: GLSL-SHADER: } related-words
  57
  58 HELP: attribute-index
  59 { $values
  60     { "program-instance" program-instance } { "attribute-name" string }
  61     { "index" integer }
  62 }
  63 { $description "Returns the numeric index of the vertex attribute named " { $snippet "attribute-name" } " in " { $snippet "program-instance" } "." } ;
  64
  65 HELP: buffer>vertex-array
  66 { $values
  67     { "vertex-buffer" buffer } { "program-instance" program-instance } { "format" vertex-format }
  68     { "vertex-array" vertex-array }
  69 }
  70 { $description "Creates a new " { $link vertex-array } " from the entire contents of a single " { $link buffer } " in a single " { $link vertex-format } " for use with " { $snippet "program-instance" } "." } ;
  71
  72 { vertex-array <vertex-array> buffer>vertex-array } related-words
  73
  74 HELP: compile-shader-error
  75 { $class-description "An error compiling the source for a " { $link shader } "."
  76 { $list
  77 { "The " { $snippet "shader" } " slot indicates the shader that failed to compile." }
  78 { "The " { $snippet "log" } " slot contains the error string from the GLSL compiler." }
  79 } } ;
  80
  81 HELP: define-vertex-format
  82 { $values
  83     { "class" class } { "vertex-attributes" sequence }
  84 }
  85 { $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." } ;
  86
  87 HELP: define-vertex-struct
  88 { $values
  89     { "class" word } { "vertex-format" vertex-format }
  90 }
  91 { $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." } ;
  92
  93 HELP: fragment-shader
  94 { $class-description "This " { $link shader-kind } " indicates that a " { $link shader } " is a fragment shader." } ;
  95
  96 HELP: link-program-error
  97 { $class-description "An error linking the constituent shaders of a " { $link program } "."
  98 { $list
  99 { "The " { $snippet "program" } " slot indicates the program that failed to link." }
 100 { "The " { $snippet "log" } " slot contains the error string from the GLSL linker." }
 101 } } ;
 102
 103 { compile-shader-error link-program-error } related-words
 104
 105 HELP: output-index
 106 { $values
 107     { "program-instance" program-instance } { "output-name" string }
 108     { "index" integer }
 109 }
 110 { $description "Returns the numeric index of the fragment shader output named " { $snippet "output-name" } " in " { $snippet "program-instance" } "." }
 111 { $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." } ;
 112
 113 HELP: program
 114 { $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> } "." } ;
 115
 116 HELP: program-instance
 117 { $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> } "." } ;
 118
 119 HELP: refresh-program
 120 { $values
 121     { "program" program }
 122 }
 123 { $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." } ;
 124
 125 HELP: shader
 126 { $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> } "." } ;
 127
 128 HELP: shader-instance
 129 { $class-description "A " { $snippet "shader-instance" } " is a " { $link shader } " that has been compiled for a graphics context using " { $link <shader-instance> } "." } ;
 130
 131 HELP: shader-kind
 132 { $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."
 133 { $list
 134 { { $link vertex-shader } "s run during primitive assembly and map input vertex data to positions in screen space for rasterization." }
 135 { { $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." }
 136 } } ;
 137
 138 HELP: too-many-feedback-formats-error
 139 { $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." } ;
 140
 141 HELP: invalid-link-feedback-format-error
 142 { $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 } ")." } ;
 143
 144 HELP: inaccurate-feedback-attribute-error
 145 { $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 } "." } ;
 146
 147 HELP: uniform-index
 148 { $values
 149     { "program-instance" program-instance } { "uniform-name" string }
 150     { "index" integer }
 151 }
 152 { $description "Returns the numeric index of the uniform parameter named " { $snippet "output-name" } " in " { $snippet "program-instance" } "." } ;
 153
 154 HELP: vertex-shader
 155 { $class-description "This " { $link shader-kind } " indicates that a " { $link shader } " is a vertex shader." } ;
 156
 157 HELP: vertex-array
 158 { $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 <vertex-array> } " or " { $link buffer>vertex-array } " words." } ;
 159
 160 HELP: vertex-array-buffer
 161 { $values
 162     { "vertex-array" vertex-array }
 163     { "vertex-buffer" buffer }
 164 }
 165 { $description "Returns the first " { $link buffer } " object comprised in " { $snippet "vertex-array" } "." } ;
 166
 167 HELP: vertex-attribute
 168 { $class-description "This tuple type is passed to " { $link define-vertex-format } " to define a new " { $link vertex-format } " type." } ;
 169
 170 HELP: vertex-format
 171 { $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." } ;
 172
 173 HELP: vertex-format-size
 174 { $values
 175     { "format" vertex-format }
 176     { "size" integer }
 177 }
 178 { $description "Returns the size in bytes of a set of vertex attributes in " { $snippet "format" } "." } ;
 179
 180 ARTICLE: "gpu.shaders" "Shader objects"
 181 "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."
 182 { $subsections
 183     POSTPONE: GLSL-PROGRAM:
 184     POSTPONE: GLSL-SHADER:
 185     POSTPONE: GLSL-SHADER-FILE:
 186 }
 187 "A program must be instantiated for each graphics context it is used in:"
 188 { $subsections <program-instance> }
 189 "Program instances can be updated on the fly, allowing for interactive development of shaders:"
 190 { $subsections refresh-program }
 191 "Render data inside GPU " { $link buffer } "s is organized into " { $link vertex-array } "s for consumption by shader code:"
 192 { $subsections
 193     vertex-array
 194     <vertex-array>
 195     buffer>vertex-array
 196     POSTPONE: VERTEX-FORMAT:
 197 } ;
 198
 199 ABOUT: "gpu.shaders"