1Array(3)              User Contributed Perl Documentation             Array(3)
2
3
4

NAME

6       OpenGL::Array - Perl Array handling and conversion between Perl arrays
7       and C array pointers.
8

SYNOPSIS

10           use OpenGL qw(GL_FLOAT);
11
12           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

DESCRIPTION

18       OpenGL::Array (OGA) objects provide Perl Array handling and conversion
19       between Perl arrays and C array pointers.
20
21       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
26       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
29       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
33       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

CREATING OpenGL::Array OBJECTS

39       "new"
40               my $array = OpenGL::Array->new($count,@types);
41
42           Creates an empty array object of $count rows made up data types
43           @types.
44
45       "new_list"
46               my $array = OpenGL::Array->new_list($type,@data);
47
48           Creates and populates a uniform array object made up @data of type
49           $type.
50
51       "new_pointer"
52               my $array = OpenGL::Array->new_pointer($type,ptr,$elements);
53
54           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
58           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
64       "new_scalar"
65               my $str = pack 'C*', 1 .. 255;
66               my $array = OpenGL::Array->new_scalar(GL_UNSIGNED_BYTE, $str, length($str));
67
68           Creates an array object from a perl scalar.
69
70       "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
74           Special case, creates a uniform GL_UNSIGNED_BYTE from a pointer.
75

USING OpenGL::Array OBJECT'S C POINTERS

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
80             my $array = OpenGL::Array->new(4, GL_INT);
81             glGetIntegerv_c(GL_VIEWPORT, $array->ptr);
82             my @viewport = $array->retrieve(0, 4);
83

OpenGL::Array ACCESSORS

85       "assign"
86               $array->assign($pos, @data);
87
88           Sets array data starting at element position $pos using @data.
89
90       "assign_data"
91               $array->assign_data($pos, $data);
92
93           Sets array data element position $pos using packed string $data.
94
95       "retrieve"
96               my @data = $array->retrieve($pos, $len);
97
98           Returns an array of $len elements from an array object.
99
100       "retrieve_data"
101               my $data = $array->retrieve_data($pos, $len);
102
103           Returns a packed string of length $len bytes from an array object.
104
105       "elements"
106               my $count = $array->elements();
107
108           Returns the element count from an array object.
109
110       "ptr"
111               ptr = $array->ptr(); # typically passed to opengl _c functions
112
113           Returns a C pointer to an array object.
114
115           Returns a C pointer to an array object.
116
117       "offset"
118               ptr = $array->offset($pos);
119
120           Returns a C pointer to the $pos element of an array object.
121
122       "update_ptr"
123               $array->update_pointer($ptr);
124
125           Points the existing OpenGL::Array to a different data pointer.
126

BINDING TO VBOs

128       Helps abstract Vertex Array and VBO rendering.
129
130       # Requires GL_ARB_vertex_buffer_object extension and POGL 0.55_01 or
131       newer
132
133       "bind"
134               $array->bind($id);
135
136           Binds a GPU buffer to an array object.  If bound, glXxxPointer_p
137           APIs will call glBindBufferARB.
138
139       "bound"
140               my $id = $array->bound();
141
142           Return bound buffer ID, or 0 if not bound.
143

AFFINE TRANSFORMS ON OpenGL::Array OBJECTS

145       Eventually, this API will abstract CPU vs GPU-based affine transforms
146       for the best performance.
147
148       "affine"
149               $array->affine($xform);
150
151               # $xform is an NxN OpenGL::Array object used to transform $array.
152
153               #N must be one element wider than the width of the array.
154

Calc: POPULATING AND MANIPULATING OpenGL::Array OBJECTS

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
162               $array->calc($value);
163
164           Populates the array with $value.
165
166               $array->calc(@values);
167
168           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
175               $array->calc(1.0, '3,*', '2,*,rand,+', '');
176
177           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
183           "calc" maintains a push/pop stack and a "register" for each column.
184
185           "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
191               $array->calc($array2, $array3, $array4, @values);
192
193           calc currently suports the following primitives:
194
195           "!" Logical "Not" for End of Stack (S0) for the current column;
196               becomes 1.0 if empty or 0. otherwise 1.0
197
198           "-" Arithmetic Negation of S0
199
200           "+" Add S0 and Next on Stack (S1), pop operands and push result
201               (Result)
202
203           "*" Multiply S0 and S1; Result
204
205           "/" Divide S1 by S0; Result
206
207           "%" S1 Modulus S0; Result
208
209           "=" Test S0 equality to S1; pop operands and push non-zero (1.0)
210               for true, otherwise 0.0 (Boolean)
211
212           ">" Test if S0 Greater than S1; Boolean
213
214           "<" Test if S0 Lesser than S1; Boolean
215
216           "?" If S0 is true (non-zero), pop S0 and S1; otherwise pop s0-3,
217               push s1
218
219           "pop"
220               Pop s0
221
222           "rand"
223               Push a random number from 0.0 to 1.0
224
225           "dup"
226               Push a copy of S0
227
228           "swap"
229               Swap values of S0 and S1
230
231           "set"
232               Copy S0 to the column's Register
233
234           "get"
235               Push the column's Register onto the column's Stack
236
237           "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
242                 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
247           "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
252                 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
257           "colget"
258               Pop S0, and push the column S0 value onto the current stack.
259
260                  $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
264           "colset"
265               Pop S0, and set the column S0 value to the new top of the
266               stack.
267
268                  $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
272           "rowget"
273               Pop S0 and S1, and push the column S0 value from row S1 onto
274               the current stack.
275
276                  $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
280           "rowset"
281               Pop S0 and S1, and set the column S0 value of row S1 to the new
282               top of the stack.
283
284                  $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
288           "end"
289               End processing; column unchanged
290
291           "endif"
292               Pop S0, End if true; column unchanged
293
294           "endrow"
295               End processing of current row; column unchanged
296
297           "endrowif"
298               Pop S0, End processing of current row if true; column unchanged
299
300           "return"
301               End processing; column value set to s0
302
303           "returnif"
304               Pop S0, End if true; column value set to s0
305
306           "returnrow"
307               End processing of current row; column value set to s0
308
309           "returnrowif"
310               Pop S0, End processing of current row if true; column value set
311               to s0
312
313           "if"
314               alias to "?"
315
316           "or"
317               alias to "+"
318
319           "and"
320               alias to "*"
321
322           "inc"
323               Add 1 to S0
324
325           "dec"
326               Subtract 1 from S0
327
328           "sum"
329               Add and pop everything in stack; push result
330
331           "avg"
332               Average and pop everything in stack; push result
333
334           "abs"
335               Replace S0 with its absolute value
336
337           "power"
338               Raise S1 to the power of S0; Result
339
340           "min"
341               The lower of S0 and S1; Result
342
343           "max"
344               The higher of S0 and S1; Result
345
346           "sin"
347               Sine of S0 in Radians; Result
348
349           "cos"
350               Cosine of S0; Result
351
352           "tan"
353               Tangent of S0; Result
354
355           "atan2"
356               ArcTangent of S1 over s0; Result
357
358           "count"
359               Push the number of elements in the array
360
361           "index"
362               Push the current element index (zero-based)
363
364           "columns"
365               Push the number of columns in the array
366
367           "column"
368               Push the current column index
369
370           "rows"
371               Push the number of rows in the array
372
373           "row"
374               Push the current row index
375
376           "pi"
377               Push the the value of PI (but remember calc is just for floats)
378
379           "dump"
380               Print a dump of the current stack to standard out.
381
382                   OpenGL::Array->new_list(GL_FLOAT,7)->calc("dup,dec,2,swap,10,4,set,dump");
383
384               Would print:
385
386                   -----------------(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

AUTHOR

395       Bulk of documentation taken from
396       http://graphcomp.com/pogl.cgi?v=0111s3p1&r=s3p6
397
398       Additions by Paul Seamons
399
400
401
402perl v5.36.0                      2022-07-22                          Array(3)
Impressum