Array (3)
Leading comments
Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) Standard preamble: ========================================================================
NAME
OpenGL::Array  Perl Array handling and conversion between Perl arrays and C array pointers.SYNOPSIS
use OpenGL qw(GL_FLOAT); my $array = OpenGL::Array>new(4, GL_FLOAT); my $c_ptr = $array>ptr(); # can be passed to OpenGL _c based functions $array>calc('col,27,+'); my @val = $array>retrieve(0, 4);
DESCRIPTION
OpenGL::Array (Due to the difference between how Perl and C handle pointers, all Perl OpenGL (
Many
Note: Since OGAs are stored as typed C arrays, there is no conversion/copy/casting when passing them to
CREATING OpenGL::Array OBJECTS
 new

my $array = OpenGL::Array>new($count,@types);
Creates an empty array object of $count rows made up data types @types.
 new_list

my $array = OpenGL::Array>new_list($type,@data);
Creates and populates a uniform array object made up @data of type $type.
 new_pointer

my $array = OpenGL::Array>new_pointer($type,ptr,$elements);
Creates an array object wrapper around a C pointer ptr of type $type and array length $elements. Caches C pointer directly; does not copy data.
Note: because OpenGL::Arrays store to direct memory addresses, it is possible to assign to the array the pointer was obtained from and the results will be available in the array created by new_pointer  and vice versa (because they are viewing portions of the same memory).
 new_scalar

my $str = pack 'C*', 1 .. 255; my $array = OpenGL::Array>new_scalar(GL_UNSIGNED_BYTE, $str, length($str));
Creates an array object from a perl scalar.
 new_from_pointer

my $array1 = OpenGL::Array>new_list(GL_UNSIGNED_BYTE, 1..9); my $array2 = OpenGL::Array>new_from_pointer($array1>ptr(), 9);
Special case, creates a uniform
GL_UNSIGNED_BYTEfrom a pointer.
USING OpenGL::Array OBJECT'S C POINTERS
OpenGL::Array objects are Perl references; in order to use them in OpenGL APIs that expect C pointers, you need to use the native pointer:
my $array = OpenGL::Array>new(4, GL_INT); glGetIntegerv_c(GL_VIEWPORT, $array>ptr); my @viewport = $array>retrieve(0, 4);
OpenGL::Array ACCESSORS
 assign

$array>assign($pos, @data);
Sets array data starting at element position $pos using @data.
 assign_data

$array>assign_data($pos, $data);
Sets array data element position $pos using packed string $data.
 retrieve

my @data = $array>retrieve($pos, $len);
Returns an array of $len elements from an array object.
 retrieve_data

my $data = $array>retrieve_data($pos, $len);
Returns a packed string of length $len bytes from an array object.
 elements

my $count = $array>elements();
Returns the element count from an array object.
 ptr

ptr = $array>ptr(); # typically passed to opengl _c functions
Returns a C pointer to an array object.
Returns a C pointer to an array object.
 offset

ptr = $array>offset($pos);
Returns a C pointer to the $pos element of an array object.
 update_ptr

$array>update_pointer($ptr);
Points the existing OpenGL::Array to a different data pointer.
BINDING TO VBOs
Helps abstract Vertex Array and# Requires GL_ARB_vertex_buffer_object extension and
 bind

$array>bind($id);
Binds a
GPUbuffer to an array object. If bound, glXxxPointer_p APIs will call glBindBufferARB.  bound

my $id = $array>bound();
Return bound buffer
ID,or 0 if not bound.
AFFINE TRANSFORMS ON OpenGL::Array OBJECTS
Eventually, this affine

$array>affine($xform); # $xform is an NxN OpenGL::Array object used to transform $array. #N must be one element wider than the width of the array.
Calc: POPULATING AND MANIPULATING OpenGL::Array OBJECTS
 calc

Used to populate or mathematically modify an POGLarray. Uses Reverse Polish Notation (RPN) for mathematical operations. At the moment, any array used with calc must be made of only ofGL_FLOATtypes.
$array>calc($value);
Populates the array with $value.
$array>calc(@values);
Populates each row of the array with @values, assuming rows have the same width as the length of @values. If the number of passed values must be evenly divisible by the number of elements in the array. The number of values becomes the number of ``columns.'' The number of ``rows'' is the total number of elements of the array divided by the columns.
$array>calc(1.0, '3,*', '2,*,rand,+', '');
Resets the first column of each row to 1.0; multiplies the values in the second column by 3; multiplies the third column by 2, then adds a random number between 0 and 1; leaves the fourth column alone. During this particular calc operation there would be 4 columns.
"calc" maintains a push/pop stack and a ``register'' for each column.
"calc" also allows for other OpenGL::Arrays to be passed in. If multiple arrays are passed they must all have the same number of elements. Only the calling array will be operated on, but as each element is visited, the values from the other arrays are preadded to the stack (in reverse order).
$array>calc($array2, $array3, $array4, @values);
calc currently supports the following primitives:

 !
 Logical ``Not'' for End of Stack (S0) for the current column; becomes 1.0 if empty or 0. otherwise 1.0
 
 Arithmetic Negation of S0
 +
 Add S0 and Next on Stack (S1), pop operands and push result (Result)
 *
 Multiply S0 and S1; Result
 /
 Divide S1 by S0; Result
 %
 S1 Modulus S0; Result
 =
 Test S0 equality to S1; pop operands and push nonzero (1.0) for true, otherwise 0.0 (Boolean)
 >
 Test if S0 Greater than S1; Boolean
 <
 Test if S0 Lesser than S1; Boolean
 ?
 If S0 is true (nonzero), pop S0 and S1; otherwise pop s03, push s1
 pop
 Pop s0
 rand
 Push a random number from 0.0 to 1.0
 dup
 Push a copy of S0
 swap
 Swap values of S0 and S1
 set
 Copy S0 to the column's Register
 get
 Push the column's Register onto the column's Stack
 store

Pop S0, and copy the values from the matching row of the passed
OpenGL::Array at that index. Values are copied into the current
column registers.
my $o1 = OpenGL::Array>new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6); my $o2 = OpenGL::Array>new_list(GL_FLOAT, 7, 8 ,9, 10, 11, 12); $o1>calc($o2, "1,store,get","","get"); $o1>retreive(0,6) will be (7, 2, 9, 10, 5, 12)
 load

Pop S0, and set the values of the matching row of the passed
OpenGL::Array named at that index. Values are copied from the current
column registers.
my $o1 = OpenGL::Array>new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6); my $o2 = OpenGL::Array>new_list(GL_FLOAT, 7, 8 ,9, 10, 11, 12); $o1>calc($o2, "set","", "set,1,load"); $o2>retreive(0,6) will be (1, 0, 3, 5, 0, 6)
 colget

Pop S0, and push the column S0 value onto the current stack.
$o = OpenGL::Array>new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6); $o>calc('2,colget','',''); # $o>retreive(0,6) will be (3, 2, 3, 6, 5, 6)
 colset

Pop S0, and set the column S0 value to the new top of the stack.
$o = OpenGL::Array>new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6); $o>calc('27,2,colset','',''); # $o>retreive(0,6) will be (1, 2, 27, 4, 5, 27)
 rowget

Pop S0 and S1, and push the column S0 value from row S1 onto the current stack.
$o = OpenGL::Array>new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6); $o>calc('1,2,rowget','',''); # $o>retreive(0,6) equiv (6, 2, 3, 6, 5, 6)
 rowset

Pop S0 and S1, and set the column S0 value of row S1 to the new top of the stack.
$o = OpenGL::Array>new_list(GL_FLOAT, 1, 2, 3, 4, 5, 6); $o>calc('27,1,2,rowset','',''); # $o>retreive(0,6) will be (1, 2, 3, 4, 5, 27)
 end
 End processing; column unchanged
 endif
 Pop S0, End if true; column unchanged
 endrow
 End processing of current row; column unchanged
 endrowif
 Pop S0, End processing of current row if true; column unchanged
 return
 End processing; column value set to s0
 returnif
 Pop S0, End if true; column value set to s0
 returnrow
 End processing of current row; column value set to s0
 returnrowif
 Pop S0, End processing of current row if true; column value set to s0
 if
 alias to "?"
 or
 alias to "+"
 and
 alias to "*"
 inc
 Add 1 to S0
 dec
 Subtract 1 from S0
 sum
 Add and pop everything in stack; push result
 avg
 Average and pop everything in stack; push result
 abs
 Replace S0 with its absolute value
 power
 Raise S1 to the power of S0; Result
 min
 The lower of S0 and S1; Result
 max
 The higher of S0 and S1; Result
 sin
 Sine of S0 in Radians; Result
 cos
 Cosine of S0; Result
 tan
 Tangent of S0; Result
 atan2
 ArcTangent of S1 over s0; Result
 count
 Push the number of elements in the array
 index
 Push the current element index (zerobased)
 columns
 Push the number of columns in the array
 column
 Push the current column index
 rows
 Push the number of rows in the array
 row
 Push the current row index
 pi

Push the the value of PI(but remember calc is just for floats)
 dump

Print a dump of the current stack to standard out.
OpenGL::Array>new_list(GL_FLOAT,7)>calc("dup,dec,2,swap,10,4,set,dump");
Would print:
(row: 0, col: 0) Register: 4.0000000 Stack 4: 7.0000000 Stack 3: 2.0000000 Stack 2: 6.0000000 Stack 1: 10.0000000 Stack 0: 4.0000000

AUTHOR
Bulk of documentation taken from graphcomp.com/pogl.cgi?v=0111s3p1&r=s3p6Additions by Paul Seamons