OpenGL::Array - Perl Array handling and conversion between Perl arrays and C array pointers.
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);
OpenGL::Array (OGA) objects provide Perl Array handling and conversion between Perl arrays and C array pointers.
Due to the difference between how Perl and C handle pointers, all Perl OpenGL (POGL) APIs that require pointers are suffixed with _c. OGAs provide a means to convert Perl arrays into C pointers that can be passed into these APIs.
Many POGL _c APIs also have a _s version to support SDL's packed string APIs; OGA provides APIs to convert between C arrays and packed strings.
POGL also provides many _p APIs that accept native Perl arrays, or in some cases OGAs directly. In the case of VBOs, OGAs may be bound to GPU buffers, automatically switching buffers at render time.
Note: Since OGAs are stored as typed C arrays, there is no conversion/copy/casting when passing them to POGL APIs, resulting in significant performance improvements over other non-compiled bindings (SDL, PyOpenGL, etc).
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_BYTE from a pointer.
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);
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.
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.
Helps abstract Vertex Array and VBO rendering.
# Requires GL_ARB_vertex_buffer_object extension and POGL 0.55_01 or newer
bind
$array->bind($id);
Binds a GPU buffer 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.
Eventually, this API will abstract CPU vs GPU-based affine transforms for the best performance.
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
Used to populate or mathematically modify an POGL array. Uses Reverse Polish Notation (RPN) for mathematical operations. At the moment, any array used with calc must be made of only of GL_FLOAT types.
$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 pre-added to the stack (in reverse order).
$array->calc($array2, $array3, $array4, @values);
calc currently suports 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 non-zero (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 (non-zero), pop S0 and S1; otherwise pop s0-3, 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 (zero-based)
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
Bulk of documentation taken from http://graphcomp.com/pogl.cgi?v=0111s3p1&r=s3p6
Additions by Paul Seamons
To install OpenGL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenGL
CPAN shell
perl -MCPAN -e shell install OpenGL
For more information on module installation, please visit the detailed CPAN module installation guide.