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>
  14 { $values
  15     { "upload" buffer-upload-pattern }
  16     { "usage" buffer-usage-pattern }
  17     { "kind" buffer-kind }
  18     { "size" integer }
  19     { "initial-data" { $maybe c-ptr } }
  20     { "buffer" buffer }
  21 }
  22 { $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." } ;
  23
  24 HELP: allocate-buffer
  25 { $values
  26     { "buffer" buffer } { "size" integer } { "initial-data" { $maybe c-ptr } }
  27 }
  28 { $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." } ;
  29
  30 HELP: buffer
  31 { $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 } ":"
  32 { $list
  33 { { $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." }
  34 { { $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." }
  35 { { $snippet "kind" } " is one of the " { $link buffer-kind } " values and indicates the primary purpose of the buffer." }
  36 }
  37 "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."
  38 } ;
  39
  40 HELP: buffer-access-mode
  41 { $class-description "A " { $snippet "buffer-access-mode" } " value is passed to " { $link with-mapped-buffer } " to control access to the mapped address space." }
  42 { $list
  43 { { $link read-access } " permits the mapped address space only to be read from." }
  44 { { $link write-access } " permits the mapped address space only to be written to." }
  45 { { $link read-write-access } " permits full access to the mapped address space." }
  46 } ;
  47
  48 HELP: buffer-kind
  49 { $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."
  50 { $list
  51 { "A " { $link vertex-buffer } " is used to store vertex attribute data to be rendered as part of a vertex array." }
  52 { "An " { $link index-buffer } " is used to store indexes into a vertex array." }
  53 { "A " { $link pixel-unpack-buffer } " is used as a source for updating texture image data." }
  54 { "A " { $link pixel-pack-buffer } " is used as a destination for reading texture or framebuffer image data." }
  55 } }
  56 { $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." } ;
  57
  58 HELP: buffer-ptr
  59 { $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:"
  60 { $list
  61 { { $snippet "buffer" } " is the " { $link buffer } " object being referenced." }
  62 { { $snippet "offset" } " is an integer offset from the beginning of the buffer." }
  63 } } ;
  64
  65 HELP: buffer-upload-pattern
  66 { $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."
  67 { $list
  68 { { $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 } "." }
  69 { { $link static-upload } " declares that the buffer data will be provided once and accessed frequently without modification." }
  70 { { $link dynamic-upload } " declares that the buffer data will be frequently modified." }
  71 }
  72 "A " { $snippet "buffer-upload-pattern" } " is only a declaration and does not actually control access to the underlying buffer data." } ;
  73
  74 HELP: buffer-usage-pattern
  75 { $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."
  76 { $list
  77 { { $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." }
  78 { { $link read-usage } " declares that the buffer will be supplied with data from other GPU resources and read from primarily by the CPU." }
  79 { { $link copy-usage } " declares that the buffer will both receive and supply data primarily for other GPU resources." }
  80 }
  81 "A " { $snippet "buffer-usage-pattern" } " is only a declaration and does not actually control access to the underlying buffer data." } ;
  82
  83 { buffer-kind buffer-upload-pattern buffer-usage-pattern } related-words
  84
  85 HELP: byte-array>buffer
  86 { $values
  87     { "byte-array" byte-array }
  88     { "upload" buffer-upload-pattern }
  89     { "usage" buffer-usage-pattern }
  90     { "kind" buffer-kind }
  91     { "buffer" buffer }
  92 }
  93 { $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." } ;
  94
  95 HELP: copy-buffer
  96 { $values
  97     { "to-buffer-ptr" buffer-ptr } { "from-buffer-ptr" buffer-ptr } { "size" integer }
  98 }
  99 { $description "Instructs the GPU to asynchronously copy " { $snippet "size" } " bytes from " { $snippet "from-buffer-ptr" } " into " { $snippet "to-buffer-ptr" } "." }
 100 { $notes "This word requires that the graphics context support OpenGL 3.1 or the " { $snippet "GL_ARB_copy_buffer" } " extension." } ;
 101
 102 HELP: copy-usage
 103 { $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." } ;
 104
 105 HELP: draw-usage
 106 { $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." } ;
 107
 108 HELP: dynamic-upload
 109 { $class-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be updated frequently during its lifetime." } ;
 110
 111 HELP: gpu-data-ptr
 112 { $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." } ;
 113
 114 HELP: index-buffer
 115 { $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be to index vertex arrays." } ;
 116
 117 HELP: pixel-pack-buffer
 118 { $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." }
 119 { $notes "This word requires OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 120
 121 HELP: pixel-unpack-buffer
 122 { $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." }
 123 { $notes "This word requires OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
 124
 125 HELP: read-access
 126 { $class-description "This " { $link buffer-access-mode } " value requests read-only access when mapping a " { $link buffer } " object through " { $link with-mapped-buffer } "." } ;
 127
 128 HELP: read-buffer
 129 { $values
 130     { "buffer-ptr" buffer-ptr } { "size" integer }
 131     { "data" byte-array }
 132 }
 133 { $description "Reads " { $snippet "size" } " bytes from " { $snippet "buffer" } " into a new " { $link byte-array } "." } ;
 134
 135 HELP: read-usage
 136 { $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." } ;
 137
 138 { copy-usage draw-usage read-usage } related-words
 139
 140 HELP: read-write-access
 141 { $class-description "This " { $link buffer-access-mode } " value requests full access when mapping a buffer object through " { $link with-mapped-buffer } "." } ;
 142
 143 HELP: static-upload
 144 { $class-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be read from frequently and modified infrequently." } ;
 145
 146 HELP: stream-upload
 147 { $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." } ;
 148
 149 { dynamic-upload static-upload stream-upload } related-words
 150
 151 HELP: update-buffer
 152 { $values
 153     { "buffer-ptr" buffer-ptr } { "size" integer } { "data" { $maybe c-ptr } }
 154 }
 155 { $description "Replaces " { $snippet "size" } " bytes of data in the " { $link buffer } " referenced by " { $snippet "buffer-ptr" } " with data from " { $snippet "data" } "." } ;
 156
 157 HELP: vertex-buffer
 158 { $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." } ;
 159
 160 { index-buffer pixel-pack-buffer pixel-unpack-buffer vertex-buffer } related-words
 161
 162 HELP: with-mapped-buffer
 163 { $values
 164     { "buffer" buffer } { "access" buffer-access-mode } { "quot" { $quotation "( alien -- )" } }
 165 }
 166 { $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." } ;
 167
 168 { allocate-buffer update-buffer read-buffer copy-buffer with-mapped-buffer } related-words
 169
 170 HELP: write-access
 171 { $class-description "This " { $link buffer-access-mode } " value requests write-only access when mapping a buffer object through " { $link with-mapped-buffer } "." } ;
 172
 173 { read-access read-write-access write-access } related-words
 174
 175 ARTICLE: "gpu.buffers" "Buffer objects"
 176 "The " { $vocab-link "gpu.buffers" } " vocabulary provides words for creating, allocating, updating, and reading GPU data buffers."
 177 { $subsection buffer }
 178 { $subsection <buffer> }
 179 { $subsection byte-array>buffer }
 180 "Declaring buffer usage:"
 181 { $subsection buffer-kind }
 182 { $subsection buffer-upload-pattern }
 183 { $subsection buffer-usage-pattern }
 184 "Referencing buffer data:"
 185 { $subsection buffer-ptr }
 186 "Manipulating buffer data:"
 187 { $subsection allocate-buffer }
 188 { $subsection update-buffer }
 189 { $subsection read-buffer }
 190 { $subsection copy-buffer }
 191 { $subsection with-mapped-buffer }
 192 ;
 193
 194 ABOUT: "gpu.buffers"