1Array(3) User Contributed Perl Documentation Array(3)
2
6 OpenGL::Array - Perl Array handling and conversion between Perl arrays
7 and C array pointers.
8
10 use OpenGL qw(GL_FLOAT);
11 my $array = OpenGL::Array->new(4, GL_FLOAT);
13 my $c_ptr = $array->ptr(); # can be passed to OpenGL _c based functions
14 $array->calc('col,27,+');
15 my @val = $array->retrieve(0, 4);
16
18 OpenGL::Array (OGA) objects provide Perl Array handling and conversion
19 between Perl arrays and C array pointers.
20 Due to the difference between how Perl and C handle pointers, all Perl
22 OpenGL (POGL) APIs that require pointers are suffixed with _c. OGAs
23 provide a means to convert Perl arrays into C pointers that can be
24 passed into these APIs.
25 Many POGL _c APIs also have a _s version to support SDL's packed string
27 APIs; OGA provides APIs to convert between C arrays and packed strings.
28 POGL also provides many _p APIs that accept native Perl arrays, or in
30 some cases OGAs directly. In the case of VBOs, OGAs may be bound to GPU
31 buffers, automatically switching buffers at render time.
32 Note: Since OGAs are stored as typed C arrays, there is no
34 conversion/copy/casting when passing them to POGL APIs, resulting in
35 significant performance improvements over other non-compiled bindings
36 (SDL, PyOpenGL, etc).
37
39 "new"
40 my $array = OpenGL::Array->new($count,@types);
41 Creates an empty array object of $count rows made up data types
43 @types.
44 "new_list"
46 my $array = OpenGL::Array->new_list($type,@data);
47 Creates and populates a uniform array object made up @data of type
49 $type.
50 "new_pointer"
52 my $array = OpenGL::Array->new_pointer($type,ptr,$elements);
53 Creates an array object wrapper around a C pointer ptr of type
55 $type and array length $elements. Caches C pointer directly; does
56 not copy data.
57 Note: because OpenGL::Arrays store to direct memory addresses, it
59 is possible to assign to the array the pointer was obtained from
60 and the results will be available in the array created by
61 new_pointer - and vice versa (because they are viewing portions of
62 the same memory).
63 "new_scalar"
65 my $str = pack 'C*', 1 .. 255;
66 my $array = OpenGL::Array->new_scalar(GL_UNSIGNED_BYTE, $str, length($str));
67 Creates an array object from a perl scalar.
69 "new_from_pointer"
71 my $array1 = OpenGL::Array->new_list(GL_UNSIGNED_BYTE, 1..9);
72 my $array2 = OpenGL::Array->new_from_pointer($array1->ptr(), 9);
73 Special case, creates a uniform GL_UNSIGNED_BYTE from a pointer.
75
77 OpenGL::Array objects are Perl references; in order to use them in
78 OpenGL APIs that expect C pointers, you need to use the native pointer:
79 my $array = OpenGL::Array->new(4, GL_INT);
81 glGetIntegerv_c(GL_VIEWPORT, $array->ptr);
82 my @viewport = $array->retrieve(0, 4);
83
85 "assign"
86 $array->assign($pos, @data);
87 Sets array data starting at element position $pos using @data.
89 "assign_data"
91 $array->assign_data($pos, $data);
92 Sets array data element position $pos using packed string $data.
94 "retrieve"
96 my @data = $array->retrieve($pos, $len);
97 Returns an array of $len elements from an array object.
99 "retrieve_data"
101 my $data = $array->retrieve_data($pos, $len);
102 Returns a packed string of length $len bytes from an array object.
104 "elements"
106 my $count = $array->elements();
107 Returns the element count from an array object.
109 "ptr"
111 ptr = $array->ptr(); # typically passed to opengl _c functions
112 Returns a C pointer to an array object.
114 Returns a C pointer to an array object.
116 "offset"
118 ptr = $array->offset($pos);
119 Returns a C pointer to the $pos element of an array object.
121 "update_ptr"
123 $array->update_pointer($ptr);
124 Points the existing OpenGL::Array to a different data pointer.
126
128 Helps abstract Vertex Array and VBO rendering.
129 # Requires GL_ARB_vertex_buffer_object extension and POGL 0.55_01 or
131 newer
132 "bind"
134 $array->bind($id);
135 Binds a GPU buffer to an array object. If bound, glXxxPointer_p
137 APIs will call glBindBufferARB.
138 "bound"
140 my $id = $array->bound();
141 Return bound buffer ID, or 0 if not bound.
143
145 Eventually, this API will abstract CPU vs GPU-based affine transforms
146 for the best performance.
147 "affine"
149 $array->affine($xform);
150 # $xform is an NxN OpenGL::Array object used to transform $array.
152 #N must be one element wider than the width of the array.
154
156 "calc"
157 Used to populate or mathematically modify an POGL array. Uses
158 Reverse Polish Notation (RPN) for mathematical operations. At the
159 moment, any array used with calc must be made of only of GL_FLOAT
160 types.
161 $array->calc($value);
163 Populates the array with $value.
165 $array->calc(@values);
167 Populates each row of the array with @values, assuming rows have
169 the same width as the length of @values. If the number of passed
170 values must be evenly divisible by the number of elements in the
171 array. The number of values becomes the number of "columns." The
172 number of "rows" is the total number of elements of the array
173 divided by the columns.
174 $array->calc(1.0, '3,*', '2,*,rand,+', '');
176 Resets the first column of each row to 1.0; multiplies the values
178 in the second column by 3; multiplies the third column by 2, then
179 adds a random number between 0 and 1; leaves the fourth column
180 alone. During this particular calc operation there would be 4
181 columns.
182 "calc" maintains a push/pop stack and a "register" for each column.
184 "calc" also allows for other OpenGL::Arrays to be passed in. If
186 multiple arrays are passed they must all have the same number of
187 elements. Only the calling array will be operated on, but as each
188 element is visited, the values from the other arrays are pre-added
189 to the stack (in reverse order).
190 $array->calc($array2, $array3, $array4, @values);
192 calc currently suports the following primitives:
194 "!" Logical "Not" for End of Stack (S0) for the current column;
196 becomes 1.0 if empty or 0. otherwise 1.0
197 "-" Arithmetic Negation of S0
199 "+" Add S0 and Next on Stack (S1), pop operands and push result
201 (Result)
202 "*" Multiply S0 and S1; Result
204 "/" Divide S1 by S0; Result
206 "%" S1 Modulus S0; Result
208 "=" Test S0 equality to S1; pop operands and push non-zero (1.0)
210 for true, otherwise 0.0 (Boolean)
211 ">" Test if S0 Greater than S1; Boolean
213 "<" Test if S0 Lesser than S1; Boolean
215 "?" If S0 is true (non-zero), pop S0 and S1; otherwise pop s0-3,
217 push s1
218 "pop"
220 Pop s0
221 "rand"
223 Push a random number from 0.0 to 1.0
224 "dup"
226 Push a copy of S0
227 "swap"
229 Swap values of S0 and S1
230 "set"
232 Copy S0 to the column's Register
233 "get"
235 Push the column's Register onto the column's Stack
236 "store"
238 Pop S0, and copy the values from the matching row of the passed
239 OpenGL::Array at that index. Values are copied into the
240 current column registers.
241 my $o1 = OpenGL::Array->new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6);
243 my $o2 = OpenGL::Array->new_list(GL_FLOAT, 7, 8 ,9, 10, 11, 12);
244 $o1->calc($o2, "1,store,get","","get");
245 $o1->retreive(0,6) will be (7, 2, 9, 10, 5, 12)
246 "load"
248 Pop S0, and set the values of the matching row of the passed
249 OpenGL::Array named at that index. Values are copied from the
250 current column registers.
251 my $o1 = OpenGL::Array->new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6);
253 my $o2 = OpenGL::Array->new_list(GL_FLOAT, 7, 8 ,9, 10, 11, 12);
254 $o1->calc($o2, "set","", "set,1,load");
255 $o2->retreive(0,6) will be (1, 0, 3, 5, 0, 6)
256 "colget"
258 Pop S0, and push the column S0 value onto the current stack.
259 $o = OpenGL::Array->new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6);
261 $o->calc('2,colget','','');
262 # $o->retreive(0,6) will be (3, 2, 3, 6, 5, 6)
263 "colset"
265 Pop S0, and set the column S0 value to the new top of the
266 stack.
267 $o = OpenGL::Array->new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6);
269 $o->calc('27,2,colset','','');
270 # $o->retreive(0,6) will be (1, 2, 27, 4, 5, 27)
271 "rowget"
273 Pop S0 and S1, and push the column S0 value from row S1 onto
274 the current stack.
275 $o = OpenGL::Array->new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6);
277 $o->calc('1,2,rowget','','');
278 # $o->retreive(0,6) equiv (6, 2, 3, 6, 5, 6)
279 "rowset"
281 Pop S0 and S1, and set the column S0 value of row S1 to the new
282 top of the stack.
283 $o = OpenGL::Array->new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6);
285 $o->calc('27,1,2,rowset','','');
286 # $o->retreive(0,6) will be (1, 2, 3, 4, 5, 27)
287 "end"
289 End processing; column unchanged
290 "endif"
292 Pop S0, End if true; column unchanged
293 "endrow"
295 End processing of current row; column unchanged
296 "endrowif"
298 Pop S0, End processing of current row if true; column unchanged
299 "return"
301 End processing; column value set to s0
302 "returnif"
304 Pop S0, End if true; column value set to s0
305 "returnrow"
307 End processing of current row; column value set to s0
308 "returnrowif"
310 Pop S0, End processing of current row if true; column value set
311 to s0
312 "if"
314 alias to "?"
315 "or"
317 alias to "+"
318 "and"
320 alias to "*"
321 "inc"
323 Add 1 to S0
324 "dec"
326 Subtract 1 from S0
327 "sum"
329 Add and pop everything in stack; push result
330 "avg"
332 Average and pop everything in stack; push result
333 "abs"
335 Replace S0 with its absolute value
336 "power"
338 Raise S1 to the power of S0; Result
339 "min"
341 The lower of S0 and S1; Result
342 "max"
344 The higher of S0 and S1; Result
345 "sin"
347 Sine of S0 in Radians; Result
348 "cos"
350 Cosine of S0; Result
351 "tan"
353 Tangent of S0; Result
354 "atan2"
356 ArcTangent of S1 over s0; Result
357 "count"
359 Push the number of elements in the array
360 "index"
362 Push the current element index (zero-based)
363 "columns"
365 Push the number of columns in the array
366 "column"
368 Push the current column index
369 "rows"
371 Push the number of rows in the array
372 "row"
374 Push the current row index
375 "pi"
377 Push the the value of PI (but remember calc is just for floats)
378 "dump"
380 Print a dump of the current stack to standard out.
381 OpenGL::Array->new_list(GL_FLOAT,7)->calc("dup,dec,2,swap,10,4,set,dump");
383 Would print:
385 -----------------(row: 0, col: 0)----
387 Register: 4.0000000
388 Stack 4: 7.0000000
389 Stack 3: 2.0000000
390 Stack 2: 6.0000000
391 Stack 1: 10.0000000
392 Stack 0: 4.0000000
393
395 Bulk of documentation taken from
396 http://graphcomp.com/pogl.cgi?v=0111s3p1&r=s3p6
397 Additions by Paul Seamons
399perl v5.30.0 2019-07-26 Array(3)