From b99b6861944723239193cd8ce3370b8711d9e9de Mon Sep 17 00:00:00 2001 From: Joe Groff Date: Sun, 26 Jul 2009 23:00:35 -0500 Subject: [PATCH] update gpu docs --- extra/gpu/buffers/buffers-docs.factor | 41 +++++++++++++++++++++++++-- extra/gpu/render/render-docs.factor | 3 +- extra/gpu/shaders/shaders-docs.factor | 11 +++++-- 3 files changed, 50 insertions(+), 5 deletions(-) diff --git a/extra/gpu/buffers/buffers-docs.factor b/extra/gpu/buffers/buffers-docs.factor index eee5d2b716..d05783dbf8 100644 --- a/extra/gpu/buffers/buffers-docs.factor +++ b/extra/gpu/buffers/buffers-docs.factor @@ -10,6 +10,13 @@ HELP: } { $description "Constructs a " { $link buffer-ptr } " tuple." } ; +HELP: +{ $values + { "buffer" buffer } { "offset" integer } { "size" integer } + { "buffer-range" buffer-range } +} +{ $description "Constructs a " { $link buffer-range } " tuple." } ; + HELP: { $values { "upload" buffer-upload-pattern } @@ -52,6 +59,7 @@ HELP: buffer-kind { "An " { $link index-buffer } " is used to store indexes into a vertex array." } { "A " { $link pixel-unpack-buffer } " is used as a source for updating texture image data." } { "A " { $link pixel-pack-buffer } " is used as a destination for reading texture or framebuffer image data." } +{ "A " { $link transform-feedback-buffer } " is used as a destination for transform feedback output from a vertex shader." } } } { $notes "The " { $snippet "pixel-unpack-buffer" } " and " { $snippet "pixel-pack-buffer" } " kinds require OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ; @@ -62,6 +70,30 @@ HELP: buffer-ptr { { $snippet "offset" } " is an integer offset from the beginning of the buffer." } } } ; +HELP: buffer-ptr>range +{ $values + { "buffer-ptr" buffer-ptr } + { "buffer-range" buffer-range } +} +{ $description "Converts a " { $link buffer-ptr } " into a " { $link buffer-range } " spanning from the " { $snippet "offset" } " referenced by the " { $snippet "buffer-ptr" } " to the end of the underlying " { $link buffer } "." } ; + +HELP: buffer-range +{ $class-description "A " { $snippet "buffer-range" } " references a subset of a " { $link buffer } " object's memory. " { $snippet "buffer-range" } "s are tuples with the following slots:" +{ $list +{ { $snippet "buffer" } " is the " { $link buffer } " object being referenced." } +{ { $snippet "offset" } " is an integer offset from the beginning of the buffer to the beginning of the referenced range." } +{ { $snippet "size" } " is the integer length from the beginning offset to the end of the referenced range." } +} } ; + +{ buffer-ptr buffer-range } related-words + +HELP: buffer-size +{ $values + { "buffer" buffer } + { "size" integer } +} +{ $description "Returns the size in bytes of the memory currently allocated for a " { $link buffer } " object." } ; + HELP: buffer-upload-pattern { $class-description { $snippet "buffer-upload-pattern" } " values aid the graphics driver in optimizing access to " { $link buffer } " objects by declaring the frequency with which the buffer will be supplied new data." { $list @@ -148,6 +180,10 @@ HELP: stream-upload { dynamic-upload static-upload stream-upload } related-words +HELP: transform-feedback-buffer +{ $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be to receive transform feedback output from a render job." } +{ $notes "Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ; + HELP: update-buffer { $values { "buffer-ptr" buffer-ptr } { "size" integer } { "data" { $maybe c-ptr } } @@ -157,7 +193,7 @@ HELP: update-buffer HELP: vertex-buffer { $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be to provide vertex attribute information to a vertex array." } ; -{ index-buffer pixel-pack-buffer pixel-unpack-buffer vertex-buffer } related-words +{ index-buffer pixel-pack-buffer pixel-unpack-buffer vertex-buffer transform-feedback-buffer } related-words HELP: with-mapped-buffer { $values @@ -165,7 +201,7 @@ HELP: with-mapped-buffer } { $description "Maps " { $snippet "buffer" } " into CPU address space with " { $snippet "access" } " for the dynamic extent of " { $snippet "quot" } ". " { $snippet "quot" } " is called with a pointer to the mapped memory on top of the stack." } ; -{ allocate-buffer update-buffer read-buffer copy-buffer with-mapped-buffer } related-words +{ allocate-buffer buffer-size update-buffer read-buffer copy-buffer with-mapped-buffer } related-words HELP: write-access { $class-description "This " { $link buffer-access-mode } " value requests write-only access when mapping a buffer object through " { $link with-mapped-buffer } "." } ; @@ -183,6 +219,7 @@ ARTICLE: "gpu.buffers" "Buffer objects" { $subsection buffer-usage-pattern } "Referencing buffer data:" { $subsection buffer-ptr } +{ $subsection buffer-range } "Manipulating buffer data:" { $subsection allocate-buffer } { $subsection update-buffer } diff --git a/extra/gpu/render/render-docs.factor b/extra/gpu/render/render-docs.factor index 187f08a7ea..171c9bb031 100755 --- a/extra/gpu/render/render-docs.factor +++ b/extra/gpu/render/render-docs.factor @@ -216,8 +216,9 @@ HELP: render-set { "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." } { "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." } { "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." } +{ "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." } } } -{ $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." } ; +{ $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." } ; { render render-set } related-words diff --git a/extra/gpu/shaders/shaders-docs.factor b/extra/gpu/shaders/shaders-docs.factor index 456a76e5ce..27e0f544cd 100755 --- a/extra/gpu/shaders/shaders-docs.factor +++ b/extra/gpu/shaders/shaders-docs.factor @@ -25,8 +25,9 @@ HELP: { $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" } "." } ; HELP: GLSL-PROGRAM: -{ $syntax "GLSL-PROGRAM: program-name shader shader ... shader ;" } -{ $description "Defines a new " { $link program } " named " { $snippet "program-name" } ". When the program is instantiated with " { $link } ", it will link together instances of all of the specified " { $link shader } "s to create the program instance." } ; +{ $syntax "GLSL-PROGRAM: program-name shader shader ... shader [vertex-format] ;" } +{ $description "Defines a new " { $link program } " named " { $snippet "program-name" } ". When the program is instantiated with " { $link } ", 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." } +{ $notes "Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ; HELP: GLSL-SHADER-FILE: { $syntax "GLSL-SHADER-FILE: shader-name shader-kind \"filename\"" } @@ -134,6 +135,12 @@ HELP: shader-kind { { $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." } } } ; +HELP: too-many-feedback-formats-error +{ $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." } ; + +HELP: invalid-link-feedback-format-error +{ $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 } ")." } ; + HELP: uniform-index { $values { "program-instance" program-instance } { "uniform-name" string }