PageRenderTime 66ms CodeModel.GetById 10ms app.highlight 52ms RepoModel.GetById 1ms app.codeStats 0ms

/extra/gpu/buffers/buffers-docs.factor

http://github.com/abeaumont/factor
Unknown | 258 lines | 213 code | 45 blank | 0 comment | 0 complexity | 24888073b8301d9918143b64f2ccbd32 MD5 | raw file
  1! (c)2009 Joe Groff bsd license
  2USING: alien alien.data byte-arrays destructors help.markup help.syntax
  3kernel math quotations ;
  4IN: gpu.buffers
  5
  6HELP: <buffer-ptr>
  7{ $values
  8    { "buffer" buffer } { "offset" integer }
  9    { "buffer-ptr" buffer-ptr }
 10}
 11{ $description "Constructs a " { $link buffer-ptr } " tuple." } ;
 12
 13HELP: <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
 20HELP: <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
 31HELP: 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
 37HELP: allocate-byte-array
 38{ $values
 39    { "buffer" buffer } { "byte-array" byte-array }
 40}
 41{ $description "Discards any memory currently held by " { $snippet "buffer" } " and reallocates a new memory block large enough to store " { $snippet "byte-array" } ". The contents of " { $snippet "byte-array" } " are then copied into the buffer." } ;
 42
 43HELP: buffer
 44{ $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 } ":"
 45{ $list
 46{ { $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." }
 47{ { $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." }
 48{ { $snippet "kind" } " is one of the " { $link buffer-kind } " values and indicates the primary purpose of the buffer." }
 49}
 50"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."
 51} ;
 52
 53HELP: buffer-access-mode
 54{ $class-description "A " { $snippet "buffer-access-mode" } " value is passed to " { $link with-mapped-buffer } " to control access to the mapped address space." }
 55{ $list
 56{ { $link read-access } " permits the mapped address space only to be read from." }
 57{ { $link write-access } " permits the mapped address space only to be written to." }
 58{ { $link read-write-access } " permits full access to the mapped address space." }
 59} ;
 60
 61HELP: buffer-kind
 62{ $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."
 63{ $list
 64{ "A " { $link vertex-buffer } " is used to store vertex attribute data to be rendered as part of a vertex array." }
 65{ "An " { $link index-buffer } " is used to store indexes into a vertex array." }
 66{ "A " { $link pixel-unpack-buffer } " is used as a source for updating texture image data." }
 67{ "A " { $link pixel-pack-buffer } " is used as a destination for reading texture or framebuffer image data." }
 68{ "A " { $link transform-feedback-buffer } " is used as a destination for transform feedback output from a vertex shader." }
 69} }
 70{ $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." } ;
 71
 72HELP: buffer-ptr
 73{ $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:"
 74{ $list
 75{ { $snippet "buffer" } " is the " { $link buffer } " object being referenced." }
 76{ { $snippet "offset" } " is an integer offset from the beginning of the buffer." }
 77} } ;
 78
 79HELP: buffer-ptr>range
 80{ $values
 81    { "buffer-ptr" buffer-ptr }
 82    { "buffer-range" buffer-range }
 83}
 84{ $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 } "." } ;
 85
 86HELP: buffer-range
 87{ $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:"
 88{ $list
 89{ { $snippet "buffer" } " is the " { $link buffer } " object being referenced." }
 90{ { $snippet "offset" } " is an integer offset from the beginning of the buffer to the beginning of the referenced range." }
 91{ { $snippet "size" } " is the integer length from the beginning offset to the end of the referenced range." }
 92} } ;
 93
 94{ buffer-ptr buffer-range } related-words
 95
 96HELP: buffer-size
 97{ $values
 98    { "buffer" buffer }
 99    { "size" integer }
100}
101{ $description "Returns the size in bytes of the memory currently allocated for a " { $link buffer } " object." } ;
102
103HELP: buffer-upload-pattern
104{ $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."
105{ $list
106{ { $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 } "." }
107{ { $link static-upload } " declares that the buffer data will be provided once and accessed frequently without modification." } 
108{ { $link dynamic-upload } " declares that the buffer data will be frequently modified." }
109}
110"A " { $snippet "buffer-upload-pattern" } " is only a declaration and does not actually control access to the underlying buffer data." } ;
111
112HELP: buffer-usage-pattern
113{ $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."
114{ $list
115{ { $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." }
116{ { $link read-usage } " declares that the buffer will be supplied with data from other GPU resources and read from primarily by the CPU." }
117{ { $link copy-usage } " declares that the buffer will both receive and supply data primarily for other GPU resources." } 
118}
119"A " { $snippet "buffer-usage-pattern" } " is only a declaration and does not actually control access to the underlying buffer data." } ;
120
121{ buffer-kind buffer-upload-pattern buffer-usage-pattern } related-words
122
123HELP: byte-array>buffer
124{ $values
125    { "byte-array" byte-array }
126    { "upload" buffer-upload-pattern }
127    { "usage" buffer-usage-pattern }
128    { "kind" buffer-kind }
129    { "buffer" buffer }
130}
131{ $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." } ;
132
133HELP: copy-buffer
134{ $values
135    { "to-buffer-ptr" buffer-ptr } { "from-buffer-ptr" buffer-ptr } { "size" integer }
136}
137{ $description "Instructs the GPU to asynchronously copy " { $snippet "size" } " bytes from " { $snippet "from-buffer-ptr" } " into " { $snippet "to-buffer-ptr" } "." }
138{ $notes "This word requires that the graphics context support OpenGL 3.1 or the " { $snippet "GL_ARB_copy_buffer" } " extension." } ;
139
140HELP: copy-usage
141{ $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." } ;
142
143HELP: draw-usage
144{ $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." } ;
145
146HELP: dynamic-upload
147{ $class-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be updated frequently during its lifetime." } ;
148
149HELP: gpu-data-ptr
150{ $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." } ;
151
152HELP: grow-buffer
153{ $values { "buffer" buffer } { "target-size" integer } }
154{ $description "If the " { $link buffer-size } " of the given " { $link buffer } " is less than " { $snippet "target-size" } ", reallocates the buffer to a size large enough to accommodate " { $snippet "target-size" } " bytes. If the buffer is reallocated, the original contents are lost." } ;
155
156HELP: index-buffer
157{ $class-description "This " { $link buffer-kind } " declares that a " { $link buffer } "'s primary use will be to index vertex arrays." } ;
158
159HELP: pixel-pack-buffer
160{ $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." }
161{ $notes "This word requires OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
162
163HELP: pixel-unpack-buffer
164{ $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." }
165{ $notes "This word requires OpenGL 2.1 or the " { $snippet "GL_ARB_pixel_buffer_object" } " extension." } ;
166
167HELP: read-access
168{ $class-description "This " { $link buffer-access-mode } " value requests read-only access when mapping a " { $link buffer } " object through " { $link with-mapped-buffer } "." } ;
169
170HELP: read-buffer
171{ $values
172    { "buffer-ptr" buffer-ptr } { "size" integer }
173    { "data" byte-array }
174}
175{ $description "Reads " { $snippet "size" } " bytes from " { $snippet "buffer" } " into a new " { $link byte-array } "." } ;
176
177HELP: read-usage
178{ $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." } ;
179
180{ copy-usage draw-usage read-usage } related-words
181
182HELP: read-write-access
183{ $class-description "This " { $link buffer-access-mode } " value requests full access when mapping a buffer object through " { $link with-mapped-buffer } "." } ;
184
185HELP: static-upload
186{ $class-description "This " { $link buffer-upload-pattern } " declares that a " { $link buffer } " object's data store will be read from frequently and modified infrequently." } ;
187
188HELP: stream-upload
189{ $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." } ;
190
191{ dynamic-upload static-upload stream-upload } related-words
192
193HELP: transform-feedback-buffer
194{ $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." }
195{ $notes "Transform feedback requires OpenGL 3.0 or one of the " { $snippet "GL_EXT_transform_feedback" } " or " { $snippet "GL_ARB_transform_feedback" } " extensions." } ;
196
197HELP: update-buffer
198{ $values
199    { "buffer-ptr" buffer-ptr } { "size" integer } { "data" { $maybe c-ptr } }
200}
201{ $description "Replaces " { $snippet "size" } " bytes of data in the " { $link buffer } " referenced by " { $snippet "buffer-ptr" } " with data from " { $snippet "data" } "." } ;
202
203HELP: vertex-buffer
204{ $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." } ;
205
206{ index-buffer pixel-pack-buffer pixel-unpack-buffer vertex-buffer transform-feedback-buffer } related-words
207
208HELP: with-mapped-buffer
209{ $values
210    { "buffer" buffer } { "access" buffer-access-mode } { "quot" { $quotation "( ..a alien -- ..b )" } }
211}
212{ $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." } ;
213
214HELP: with-mapped-buffer-array
215{ $values
216    { "buffer" buffer } { "access" buffer-access-mode } { "c-type" "a C type" } { "quot" { $quotation "( ..a array -- ..b )" } }
217}
218{ $description "Maps " { $snippet "buffer" } " into CPU address space with " { $snippet "access" } " for the dynamic extent of " { $snippet "quot" } ". " { $snippet "quot" } " is called with the pointer to the mapped memory wrapped in a specialized array of " { $snippet "c-type" } "." }
219{ $notes "The appropriate specialized array vocabulary must be loaded; otherwise, an error will be thrown. See the " { $vocab-link "specialized-arrays" } " vocabulary for details on the underlying sequence type constructed." } ;
220
221{ allocate-buffer allocate-byte-array buffer-size update-buffer read-buffer copy-buffer with-mapped-buffer } related-words
222
223HELP: write-access
224{ $class-description "This " { $link buffer-access-mode } " value requests write-only access when mapping a buffer object through " { $link with-mapped-buffer } "." } ;
225
226{ read-access read-write-access write-access } related-words
227
228ARTICLE: "gpu.buffers" "Buffer objects"
229"The " { $vocab-link "gpu.buffers" } " vocabulary provides words for creating, allocating, updating, and reading GPU data buffers."
230{ $subsections
231    buffer
232    <buffer>
233    byte-array>buffer
234}
235"Declaring buffer usage:"
236{ $subsections
237    buffer-kind
238    buffer-upload-pattern
239    buffer-usage-pattern
240}
241"Referencing buffer data:"
242{ $subsections
243    buffer-ptr
244    buffer-range
245}
246"Manipulating buffer data:"
247{ $subsections
248    allocate-buffer
249    allocate-byte-array
250    grow-buffer
251    update-buffer
252    read-buffer
253    copy-buffer
254    with-mapped-buffer
255    with-mapped-buffer-array
256} ;
257
258ABOUT: "gpu.buffers"