1Name 2 3 NV_parameter_buffer_object 4 5Name Strings 6 7 None (implied by NV_gpu_program4) 8 9Contact 10 11 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 12 Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com) 13 14Status 15 16 Shipping for GeForce 8 Series (November 2006) 17 18Version 19 20 Last Modified Date: 03/09/2011 21 NVIDIA Revision: 9 22 23Number 24 25 339 26 27Dependencies 28 29 OpenGL 2.0 is required. 30 31 NV_gpu_program4 is required. 32 33 This extension is written against the OpenGL 2.0 specification. 34 35 NV_transform_feedback affects this extension. 36 37 OpenGL 3.0 affects this extension. 38 39Overview 40 41 This extension, in conjunction with NV_gpu_program4, provides a new type 42 of program parameter than can be used as a constant during vertex, 43 fragment, or geometry program execution. Each program target has a set of 44 parameter buffer binding points to which buffer objects can be attached. 45 46 A vertex, fragment, or geometry program can read data from the attached 47 buffer objects using a binding of the form "program.buffer[a][b]". This 48 binding reads data from the buffer object attached to binding point <a>. 49 The buffer object attached is treated either as an array of 32-bit words 50 or an array of four-component vectors, and the binding above reads the 51 array element numbered <b>. 52 53 The use of buffer objects allows applications to change large blocks of 54 program parameters at once, simply by binding a new buffer object. It 55 also provides a number of new ways to load parameter values, including 56 readback from the frame buffer (EXT_pixel_buffer_object), transform 57 feedback (NV_transform_feedback), buffer object loading functions such as 58 MapBuffer and BufferData, as well as dedicated parameter buffer update 59 functions provided by this extension. 60 61New Procedures and Functions 62 63 void BindBufferRangeNV(enum target, uint index, uint buffer, 64 intptr offset, sizeiptr size); 65 void BindBufferOffsetNV(enum target, uint index, uint buffer, 66 intptr offset); 67 void BindBufferBaseNV(enum target, uint index, uint buffer); 68 void ProgramBufferParametersfvNV(enum target, uint bindingIndex, uint wordIndex, 69 sizei count, const float *params); 70 void ProgramBufferParametersIivNV(enum target, uint bindingIndex, uint wordIndex, 71 sizei count, const int *params); 72 void ProgramBufferParametersIuivNV(enum target, uint bindingIndex, uint wordIndex, 73 sizei count, const uint *params); 74 void GetIntegerIndexedvEXT(enum value, uint index, int *data); 75 76New Tokens 77 78 Accepted by the <pname> parameter of GetProgramivARB: 79 80 MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS_NV 0x8DA0 81 MAX_PROGRAM_PARAMETER_BUFFER_SIZE_NV 0x8DA1 82 83 Accepted by the <target> parameter of ProgramBufferParametersfvNV, 84 ProgramBufferParametersIivNV, and ProgramBufferParametersIuivNV, 85 BindBufferRangeNV, BindBufferOffsetNV, BindBufferBaseNV, and BindBuffer 86 and the <value> parameter of GetIntegerv and GetIntegerIndexedvEXT: 87 88 VERTEX_PROGRAM_PARAMETER_BUFFER_NV 0x8DA2 89 GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV 0x8DA3 90 FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV 0x8DA4 91 92Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 93 94 Modify "Section 2.14.1" of the ARB_vertex_program specification. 95 96 (Add after the discussion of environment parameters.) 97 98 Additionally, each program target has an array of parameter buffer binding 99 points, to which a buffer object (Section 2.9) can be bound. The number 100 of available binding points is given by the implementation-dependent 101 constant MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS_NV. These binding points 102 are shared by all programs of a given type. All bindings are initialized 103 to the name zero, which indicates that no valid binding is present. 104 105 A program parameter binding is associated with a buffer object using 106 BindBufferOffsetNV with a <target> of VERTEX_PROGRAM_PARAMETER_BUFFER_NV, 107 GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV, or 108 FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV and <index> corresponding to the 109 number of the desired binding point. The error INVALID_VALUE is generated 110 if the value of <index> is greater than or equal to 111 MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS. 112 113 Buffer objects are made to be sources of program parameter buffers by 114 calling one of 115 116 void BindBufferRangeNV(enum target, uint index, uint buffer, 117 intptr offset, sizeiptr size) 118 void BindBufferOffsetNV(enum target, uint index, uint buffer, 119 intptr offset) 120 void BindBufferBaseNV(enum target, uint index, uint buffer) 121 122 where <target> is set to VERTEX_PROGRAM_PARAMETER_BUFFER_NV, 123 GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV, or 124 FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV. Any of the three BindBuffer* 125 commands perform the equivalent of BindBuffer(target, buffer). <buffer> 126 specifies which buffer object to bind to the target at index number 127 <index>. <index> must be less than the value of 128 MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS_NV. <offset> specifies a starting 129 offset into the buffer object <buffer>. <size> specifies the number of 130 elements in the bound portion of the buffer. Both <offset> and <size> are 131 in basic machine units. The error INVALID_VALUE is generated if the value 132 of <size> is less than or equal to zero. The error INVALID_VALUE is 133 generated if <offset> or <size> are not word-aligned. For program 134 parameter buffers, the error INVALID_VALUE is generated if <offset> is 135 non-zero. 136 137 BindBufferBaseNV is equivalent to calling BindBufferOffsetNV with an 138 <offset> of 0. BindBufferOffsetNV is the equivalent of calling 139 BindBufferRangeNV with <size> = sizeof(buffer) - <offset> and rounding 140 <size> down so that it is word-aligned. 141 142 All program parameter buffer parameters are either single-component 32-bit 143 words or four-component vectors made up of 32-bit words. The program 144 parameter buffers may hold signed integer, unsigned integer, or 145 floating-point data. There is a limit on the maximum number of words of a 146 buffer object that can be accessed using any single parameter buffer 147 binding point, given by the implementation-dependent constant 148 MAX_PROGRAM_PARAMETER_BUFFER_SIZE_NV. Buffer objects larger than this 149 size may be used, but the results of accessing portions of the buffer 150 object beyond the limit are undefined. 151 152 The commands 153 154 void ProgramBufferParametersfvNV(enum target, uint bindingIndex, uint wordIndex, 155 sizei count, const float *params); 156 void ProgramBufferParametersIivNV(enum target, uint bindingIndex, uint wordIndex, 157 sizei count, const int *params); 158 void ProgramBufferParametersIuivNV(enum target, uint bindingIndex, uint wordIndex, 159 sizei count, const uint *params); 160 161 update words <wordIndex> through <wordIndex>+<count>-1 in the buffer object bound 162 to the binding point numbered <bindingIndex> for the program target <target>. 163 The new data is referenced by <params>. The error INVALID_OPERATION is 164 generated if no buffer object is bound to the binding point numbered 165 <bindingIndex>. The error INVALID_VALUE is generated if <wordIndex>+<count> is 166 greater than either the number of words in the buffer object or the 167 maximum parameter buffer size MAX_PROGRAM_PARAMETER_BUFFER_SIZE_NV. These 168 functions perform an operation functionally equivalent to calling 169 BufferSubData, but possibly with higher performance. 170 171Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 172 173 None. 174 175Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 176Operations and the Frame Buffer) 177 178 None. 179 180Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 181 182 None. 183 184Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 185State Requests) 186 187 Modify the second paragraph of section 6.1.1 (Simple Queries) p. 244 to 188 read as follows: 189 190 ...<data> is a pointer to a scalar or array of the indicated type in which 191 to place the returned data. 192 193 void GetIntegerIndexedvEXT(enum target, uint index, 194 int *data); 195 196 are used to query indexed state. <target> is the name of the indexed 197 state and <index> is the index of the particular element being queried. 198 <data> is a pointer to a scalar or array of the indicated type in which to 199 place the returned data. 200 201 When <target> is one of VERTEX_PROGRAM_PARAMETER_BUFFER_NV, 202 GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV, or 203 FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV, the <index> is a buffer 204 binding index; the error INVALID_VALUE is generated if <index> 205 is greater or equal to the implementation-dependent value of 206 MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS. 207 208Additions to the AGL/GLX/WGL Specifications 209 210 None 211 212GLX Protocol 213 214 TBD 215 216Dependencies on NV_transform_feedback 217 218 Both NV_transform_feedback and this extension define the behavior of 219 BindBuffer{Range, Offset, Base}NV. Both definitions should be functionally 220 identical. 221 222Dependencies on OpenGL 3.0 223 224 GetIntegeri_v accepts the same target parameters GetIntegerIndexedvEXT 225 and the two queries return identical results. 226 227Errors 228 229 The error INVALID_VALUE is generated by BindBufferRangeNV, 230 BindBufferOffsetNV, or BindBufferBaseNV if <target> is 231 VERTEX_PROGRAM_PARAMETER_BUFFER_NV, GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV, 232 or FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV, and <index> is greater than or 233 equal to MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS. 234 235 The error INVALID_VALUE is generated by BindBufferRangeNV or 236 BindBufferOffsetNV if <offset> or <size> is not word-aligned. 237 238 The error INVALID_VALUE is generated by BindBufferRangeNV if <size> is 239 less than zero. 240 241 The error INVALID_VALUE is generated by BindBufferRangeNV or 242 BindBufferOffsetNV if <target> is VERTEX_PROGRAM_PARAMETER_BUFFER_NV, 243 GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV, or 244 FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV, and <offset> is non-zero. 245 246 The error INVALID_OPERATION is generated by ProgramBufferParametersfvNV, 247 ProgramBufferParametersIivNV, or ProgramBufferParametersIuivNV if no 248 buffer object is bound to the binding point numbered <bindingIndex> for program 249 target <target>. 250 251 The error INVALID_VALUE is generated by ProgramBufferParametersfvNV, 252 ProgramBufferParametersIivNV, or ProgramBufferParametersIuivNV if the sum 253 of <wordIndex> and <count> is greater than either the number of words in the 254 buffer object bound to <bindingIndex> or the maximum parameter buffer size 255 MAX_PROGRAM_PARAMETER_BUFFER_SIZE_NV. 256 257 The error INVALID_VALUE is generated by GetIntegerIndexedvEXT 258 when <target> is one of VERTEX_PROGRAM_PARAMETER_BUFFER_NV, 259 GEOMETRY_PROGRAM_PARAMETER_BUFFER_NV, or 260 FRAGMENT_PROGRAM_PARAMETER_BUFFER_NV, and the <index> is greater 261 than or equal to MAX_PROGRAM_PARAMETER_BUFFER_BINDINGS. 262 263New State 264 265 (Modify ARB_vertex_program, Table X.6 -- Program State) 266 267 Initial 268 Get Value Type Get Command Value Description Sec. Attribute 269 --------- ------- ----------- ------- ------------------------ ------ --------- 270 VERTEX_PROGRAM_PARAMETER_ Z+ GetIntegerv 0 Active vertex program 2.14.1 - 271 BUFFER_NV buffer object binding 272 VERTEX_PROGRAM_PARAMETER_ nxZ+ GetInteger- 0 Buffer objects bound for 2.14.1 - 273 BUFFER_NV IndexedvEXT vertex program use 274 GEOMETRY_PROGRAM_PARAMETER_ Z+ GetIntegerv 0 Active geometry program 2.14.1 - 275 BUFFER_NV buffer object binding 276 GEOMETRY_PROGRAM_PARAMETER_ nxZ+ GetInteger- 0 Buffer objects bound for 2.14.1 - 277 BUFFER_NV IndexedvEXT geometry program use 278 FRAGMENT_PROGRAM_PARAMETER_ Z+ GetIntegerv 0 Active fragment program 2.14.1 - 279 BUFFER_NV buffer object binding 280 FRAGMENT_PROGRAM_PARAMETER_ nxZ+ GetInteger- 0 Buffer objects bound for 2.14.1 - 281 BUFFER_NV IndexedvEXT fragment program use 282 283New Implementation Dependent State 284 285 Minimum 286 Get Value Type Get Command Value Description Sec. Attribute 287 --------- ------- ----------- ------- ---------------- ------ --------- 288 MAX_PROGRAM_PARAMETER_ Z GetProgram- 8 size of program 2.14.1 - 289 BUFFER_BINDINGS_NV ivARB parameter binding 290 tables 291 MAX_PROGRAM_PARAMETER_ Z GetProgram- 4096 maximum usable 2.14.1 - 292 BUFFER_SIZE_NV ivARB size of program 293 parameter buffers 294 295Examples 296 297 !!NVfp4.0 298 # Legal 299 BUFFER bones[] = { program.buffer[0] }; 300 ALIAS funBone = bones[69]; 301 MOV t, bones[1]; 302 # Illegal 303 ALIAS numLights = program.buffer[5][6]; 304 MOV t, program.buffer[3][x]; 305 END 306 307Issues 308 309 (1) PBO is already taken as an acronym? What do we call this? 310 311 RESOLVED: PaBO. 312 313 (2) How should the ability to simultaneously access multiple parameter 314 buffers be exposed? 315 316 RESOLVED: In the program text (see NV_gpu_program4), the buffers are 317 referred to using a buffer binding statement which is dereferenced in 318 the instructions. In the rest of the APIs, an array of internal binding 319 points is provided, which are dereferenced using the index parameter of 320 BindBufferBaseNV and associated functions. 321 322 (3) Should program parameter buffer bindings be provided per-target (i.e., 323 environment parameters), per-program (i.e., local parameters), or some 324 combination of the two? 325 326 RESOLVED: Per-target. That fits most naturally with the ARB program 327 model, similar to textures. Having both per-program and per-target add 328 complexity with no benefit. 329 330 (4) Should references to the parameter buffer be scalar or vector? 331 332 RESOLVED: Scalar. Having vector is more consistent with the legacy APIs, 333 but is more difficult to build the arbitrary data structures that are 334 interesting to store in a parameter buffer. A future extension can 335 define an alternate keyword in the program text to specify accesses of a 336 different size. 337 338 (5) Should parameter buffers be editable using the ProgramEnvParameter 339 API? 340 341 RESOLVED: No. There is a new parallel API for the bindable buffers, 342 including the ability to update multiple parameters at a time. These are 343 more convenient than having to rebind for BufferData and potentially 344 faster. 345 346 (6) Should parameter buffers be editable outside the ProgramBufferParameters 347 API? 348 349 RESOLVED: Yes. The use of buffer objects allows the buffers to be 350 naturally manipulated using normal buffer object mechanisms. That 351 includes CPU mapping, loading via BufferData or BufferSubData, and even 352 reading data back using the ARB_pixel_buffer_object extension. 353 354 (7) Will buffer object updates from different sources cause potential 355 synchronization problems? If so, how will they be resolved. 356 357 RESOLVED: If reads and write occur in the course of the same call 358 (e.g. reading from a buffer using parameter buffer binding while writing 359 to it using transform feedback. All other cases are allowed and occur in 360 command order. Any synchronization is handled by the GL. 361 362 (8) Is there an implementation-dependent limit to the size of program 363 parameter buffers? 364 365 RESOLVED: Yes, limited-size buffers are provided to reduce the 366 complexity of the GPU design that supports program parameter buffer 367 access and updates. However, the minimum limit is 16K scalar 368 parameters, or 64KB. A larger buffer object can be provided, but only 369 the first 64KB is accessible. The limit is queryable with 370 GetProgramivARB with <pname> MAX_PROGRAM_PARAMETER_BUFFER_SIZE_NV. 371 372 (9) With scalar buffers, which parameter setting routines do we need? 373 374 UNRESOLVED: A function to set N scalars is very important. It might be 375 nice to have convenience functions that take 1 or 4 parameters directly. 376 377 (10) Do we need GetProgramBufferParameter functions? 378 379 UNRESOLVED: Probably not - they aren't performance critical and offer no 380 functionality beyond getting the buffer object data any of the standard 381 ways. 382 383 (11) What happens if a value written using ProgramBufferParametersfNV is 384 read as an integer or the other way around? 385 386 RESOLVED: Undefined - likely just a raw bit cast between whatever 387 internal representations are used by the GL. 388 389 (12) What's the differece between the "GLuint buffer" 390 in BindBuffer*NV commands and the "GLuint bindingIndex" 391 in ProgramBufferParameter*NV commands? 392 393 RESOLVED: The "GLuint buffer" parameter is a buffer object name 394 created with glBindBuffer or glGenBuffers. 395 396 The "GLuint bindingIndex" parameter is an unsigned index into the target's 397 array of buffer bindings. 398 399 The index used by GetIntegerIndexvEXT for NV_parameter_buffer_object 400 query tokens is an index into the query token's array of buffer 401 bindings (similar to bindingIndex). 402 403Revision History 404 405 Rev. Date Author Changes 406 ---- -------- -------- ----------------------------------------- 407 9 03/09/11 mjk Fix glGetIntegerIndexedvEXT prototype 408 Note about glGetIntegeri_v 409 Rename buffer and index parameters and 410 add Issue #12 to clarify the API 411 412 8 10/02/08 mjk Fix New Tokens to note glGetIntegerv works 413 for *_PROGRAM_PARAMETER_NV (matching the table); 414 NVIDIA drivers before 180.00 fail to implement 415 this get, later drivers do 416 7 04/18/07 pbrown Fixed state table to include the buffer 417 object binding array for each program type. 418 419 6 02/07/07 ewerness Updated inconsistent prototypes in spec - 420 <count> for ProgramBufferParameters* is 421 a <sizei>, not a <uint>. 422 423 1-5 Internal revisions. 424