extra/gpu/buffers/buffers-docs.factor

   1 ! (c)2009 Joe Groff bsd license
   2 USING: alien byte-arrays destructors help.markup help.syntax kernel math
   3 quotations ;
   4 IN: gpu.buffers
   5
   6 HELP: <buffer-ptr>
   7 { $values
   8     { "buffer" buffer } { "offset" integer }
   9     { "buffer-ptr" buffer-ptr }
  10 }
  11 { $description "Constructs a " { $link buffer-ptr } " tuple." } ;
  12
  13 HELP: <buffer-range>
  14 { $values
  15     { "buffer" buffer } { "offset" integer } { "size" integer }
  16     { "buffer-range" buffer-range }
  17 }
  18 { $description "Constructs a " { $link buffer-range } " tuple." } ;
  19
  20 HELP: <buffer>
  21 { $values
  22     { "upload" buffer-upload-pattern }
  23     { "usage" buffer-usage-pattern }
  24     { "kind" buffer-kind }
  25     { "size" integer }
  26     { "initial-data" { $maybe c-ptr } }
  27     { "buffer" buffer }
  28 }
  29 { $description "Allocates a new " { $link buffer } " object of " { $snippet "size" } " bytes. If " { $snippet "initial-data" } " is not " { $link f } ", " { $snippet "size" } " bytes are copied from " { $snippet "initial-data" } " into the buffer to initialize it; otherwise, the buffer content is left uninitialized. " { $snippet "upload" } ", " { $snippet "usage" } ", and " { $snippet "kind" } " provide hints to the implementation about the expected usage pattern of the buffer as documented in the " { $link buffer } " class documentation." } ;
  30
  31 HELP: allocate-buffer
  32 { $values
  33     { "buffer" buffer } { "size" integer } { "initial-data" { $maybe c-ptr } }
  34 }
  35 { $description "Discards any memory currently held by " { $snippet "buffer" } " and reallocates a new memory block of " { $snippet "size" } " bytes for it. If " { $snippet "initial-data" } " is not " { $link f } ", " { $snippet "size" } " bytes are copied from " { $snippet "initial-data" } " into the buffer to initialize it; otherwise, the buffer content is left uninitialized." } ;
  36
  37 HELP: buffer
  38 { $class-description "Objects of this class represent GPU-accessible memory buffers. Buffer objects can be used to store vertex data and to update or read pixel data from textures and framebuffers without CPU involvement. The data inside buffer objects may be resident in main memory or different parts of GPU memory; the graphics driver will choose a location for a buffer based on usage hints specified when the buffer object is constructed with " { $link <buffer> } " or " { $link byte-array>buffer } ":"
  39 { $list
  40 { { $snippet "upload-pattern" } " is one of the " { $link buffer-upload-pattern } " values and indicates how frequently the data in the buffer will be updated with new data from CPU memory." }
  41 { { $snippet "usage-pattern" } " is one of the " { $link buffer-usage-pattern } " values and indicates how frequently the data in the buffer will be updated with new data from CPU memory." }
  42 { { $snippet "kind" } " is one of the " { $link buffer-kind } " values and indicates the primary purpose of the buffer." }
  43 }
  44 "These settings are only performance hints and do not restrict the usage of the buffer in any way. For example, a buffer constructed as a " { $link vertex-buffer } " with " { $link static-upload } " can still receive pixel data as though it were a " { $link pixel-pack-buffer } ", and can still be updated with " { $link copy-buffer } " or " { $link update-buffer } ". However, performance may be worse when actual usage conflicts with declared usage."
  45 } ;
  46
  47 HELP: buffer-access-mode
  48 { $class-description "A " { $snippet "buffer-access-mode" } " value is passed to " { $link with-mapped-buffer } " to control access to the mapped address space." }
  49 { $list
  50 { { $link read-access } " permits the mapped address space only to be read from." }
  51 { { $link write-access } " permits the mapped address space only to be written to." }
  52 { { $link read-write-access } " permits full access to the mapped address space." }
  53 } ;
  54
  55 HELP: buffer-kind
  56 { $class-description { $snippet "buffer-kind" } " values tell the graphics driver what the primary application of a " { $link buffer } " object will be. Note that any buffer can be used for any purpose; however, performance may be improved if a buffer object is constructed as the same kind as its primary use case."
  57 { $list
  58 { "A " { $link vertex-buffer } " is used to store vertex attribute data to be rendered as part of a vertex array." }
  59 { "An " { $link index-buffer } " is used to store indexes into a vertex array." }
  60 { "A " { $link pixel-unpack-buffer } " is used as a source for updating texture image data." }
  61 { "A " { $link pixel-pack-buffer } " is used as a destination for reading texture or framebuffer image data." }
  62 { "A " { $link transform-feedback-buffer } " is used as a destination for transform feedback output from a vertex shader." }
  63 } }
  64 { $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." } ;
  65
  66 HELP: buffer-ptr
  67 { $class-description "A " { $snippet "buffer-ptr" } " references a memory location inside a " { $link buffer } " object. " { $snippet "buffer-ptr" } "s are tuples with the following slots:"
  68 { $list
  69 { { $snippet "buffer" } " is the " { $link buffer } " object being referenced." }
  70 { { $snippet "offset" } " is an integer offset from the beginning of the buffer." }
  71 } } ;
  72
  73 HELP: buffer-ptr>range
  74 { $values
  75     { "buffer-ptr" buffer-ptr }
  76     { "buffer-range" buffer-range }
  77 }
  78 { $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 } "." } ;
  79
  80 HELP: buffer-range
  81 { $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:"
  82 { $list
  83 { { $snippet "buffer" } " is the " { $link buffer } " object being referenced." }
  84 { { $snippet "offset" } " is an integer offset from the beginning of the buffer to the beginning of the referenced range." }
  85 { { $snippet "size" } " is the integer length from the beginning offset to the end of the referenced range." }
  86 } } ;
  87
  88 { buffer-ptr buffer-range } related-words
  89
  90 HELP: buffer-size
  91 { $values
  92     { "buffer" buffer }
  93     { "size" integer }
  94 }
  95 { $description "Returns the size in bytes of the memory currently allocated for a " { $link buffer } " object." } ;
  96
  97 HELP: buffer-upload-pattern
  98 { $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."
  99 { $list
 100 { { $link stream-upload } " declares that the buffer data will only be used a few times before being deallocated by " { $link dispose } " or replaced by " { $link allocate-buffer } "." }
 101 { { $link static-upload } " declares that the buffer data will be provided once and accessed frequently without modification." }
 102 { { $link dynamic-upload } " declares that the buffer data will be frequently modified." }
 103 }
 104 "A " { $snippet "buffer-upload-pattern" } " is only a declaration and does not actually control access to the underlying buffer data." } ;
 105
 106 HELP: buffer-usage-pattern
 107 { $class-description { $snippet "buffer-usage-pattern" } " values aid the graphics driver in optimizing access to " { $link buffer } " objects by declaring the primary provider and consumer of data for the buffer."
 108 { $list
 109 { { $link draw-usage } " declares that the buffer will be supplied with data from CPU memory and read from by the GPU for vertex or texture image data." }
 110 { { $link read-usage } " declares that the buffer will be supplied with data from other GPU resources and read from primarily by the CPU." }
 111 { { $link copy-usage } " declares that the buffer will both receive and supply data primarily for other GPU resources." }
 112 }
 113 "A " { $snippet "buffer-usage-pattern" } " is only a declaration and does not actually control access to the underlying buffer data." } ;
 114
 115 { buffer-kind buffer-upload-pattern buffer-usage-pattern } related-words
 116
 117 HELP: byte-array>buffer
 118 { $values
 119     { "byte-array" byte-array }
 120     { "upload" buffer-upload-pattern }
 121     { "usage" buffer-usage-pattern }
 122     { "kind" buffer-kind }
 123     { "buffer" buffer }
 124 }
 125 { $description "Allocates a new " { $link buffer } " object with the size and contents of " { $snippet "byte-array" } ". " { $snippet "upload" } ", " { $snippet "usage" } ", and " { $snippet "kind" } " provide hints to the implementation about the expected usage pattern of the buffer as documented in the " { $link buffer } " class documentation." } ;
 126
 127 HELP: copy-buffer
 128 { $values
 129     { "to-buffer-ptr" buffer-ptr } { "from-buffer-ptr" buffer-ptr } { "size" integer }
 130 }
 131 { $description "Instructs the GPU to asynchronously copy " { $snippet "size" } " bytes from " { $snippet "from-buffer-ptr" } " into " { $snippet "to-buffer-ptr" } "." }
 132 { $notes "This word requires that the graphics context support OpenGL 3.1 or the " { $snippet "GL_ARB_copy_buffer" } " extension." } ;
 133
 134 HELP: copy-usage
 135 { $class-description "This " { $link buffer-usage-pattern } " declares that a " { $link buffer } " object will be primarily read from and written to by other GPU resources." } ;
 136
 137 HELP: draw-usage
 138 { $class-description "This " { $link buffer-usage-pattern } " declares that a " { $link buffer } " object will be primarily read from by the GPU and written to by the CPU." } ;
 139
 140 HELP: dynamic-upload
 141 { $class-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be updated frequently during its lifetime." } ;
 142
 143 HELP: gpu-data-ptr
 144 { $class-description "This class is a union of the " { $link c-ptr } " and " { $link buffer-ptr } " classes. It represents a value that can be supplied either from CPU or GPU memory." } ;
 145
 146 HELP: index-buffer
 147 { $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be to index vertex arrays." } ;
 148
 149 HELP: pixel-pack-buffer
 150 { $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be as a destination for receiving image data from textures or framebuffers." }
 151 { $notes "This word requires OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 152
 153 HELP: pixel-unpack-buffer
 154 { $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be as a source for supplying image data to textures." }
 155 { $notes "This word requires OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 156
 157 HELP: read-access
 158 { $class-description "This " { $link buffer-access-mode } " value requests read-only access when mapping a " { $link buffer } " object through " { $link with-mapped-buffer } "." } ;
 159
 160 HELP: read-buffer
 161 { $values
 162     { "buffer-ptr" buffer-ptr } { "size" integer }
 163     { "data" byte-array }
 164 }
 165 { $description "Reads " { $snippet "size" } " bytes from " { $snippet "buffer" } " into a new " { $link byte-array } "." } ;
 166
 167 HELP: read-usage
 168 { $class-description "This " { $link buffer-usage-pattern } " declares that a " { $link buffer } " object will be primarily read from by the CPU and written to by the GPU." } ;
 169
 170 { copy-usage draw-usage read-usage } related-words
 171
 172 HELP: read-write-access
 173 { $class-description "This " { $link buffer-access-mode } " value requests full access when mapping a buffer object through " { $link with-mapped-buffer } "." } ;
 174
 175 HELP: static-upload
 176 { $class-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be read from frequently and modified infrequently." } ;
 177
 178 HELP: stream-upload
 179 { $var-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be used only a handful of times before being deallocated or replaced." } ;
 180
 181 { dynamic-upload static-upload stream-upload } related-words
 182
 183 HELP: transform-feedback-buffer
 184 { $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." }
 185 { $notes "Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ;
 186
 187 HELP: update-buffer
 188 { $values
 189     { "buffer-ptr" buffer-ptr } { "size" integer } { "data" { $maybe c-ptr } }
 190 }
 191 { $description "Replaces " { $snippet "size" } " bytes of data in the " { $link buffer } " referenced by " { $snippet "buffer-ptr" } " with data from " { $snippet "data" } "." } ;
 192
 193 HELP: vertex-buffer
 194 { $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." } ;
 195
 196 { index-buffer pixel-pack-buffer pixel-unpack-buffer vertex-buffer transform-feedback-buffer } related-words
 197
 198 HELP: with-mapped-buffer
 199 { $values
 200     { "buffer" buffer } { "access" buffer-access-mode } { "quot" { $quotation "( alien -- )" } }
 201 }
 202 { $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." } ;
 203
 204 { allocate-buffer buffer-size update-buffer read-buffer copy-buffer with-mapped-buffer } related-words
 205
 206 HELP: write-access
 207 { $class-description "This " { $link buffer-access-mode } " value requests write-only access when mapping a buffer object through " { $link with-mapped-buffer } "." } ;
 208
 209 { read-access read-write-access write-access } related-words
 210
 211 ARTICLE: "gpu.buffers" "Buffer objects"
 212 "The " { $vocab-link "gpu.buffers" } " vocabulary provides words for creating, allocating, updating, and reading GPU data buffers."
 213 { $subsections
 214     buffer
 215     <buffer>
 216     byte-array>buffer
 217 }
 218 "Declaring buffer usage:"
 219 { $subsections
 220     buffer-kind
 221     buffer-upload-pattern
 222     buffer-usage-pattern
 223 }
 224 "Referencing buffer data:"
 225 { $subsections
 226     buffer-ptr
 227     buffer-range
 228 }
 229 "Manipulating buffer data:"
 230 { $subsections
 231     allocate-buffer
 232     update-buffer
 233     read-buffer
 234     copy-buffer
 235     with-mapped-buffer
 236 }
 237 ;
 238
 239 ABOUT: "gpu.buffers"