OpenGL::Sandbox::V1 - Various OpenGL tools and utilities that depend on the OpenGL 1.x API
version 0.042
This module is seperate from OpenGL::Sandbox in order to keep the OpenGL API dependencies less tangled. Everything specific to OpenGL 1.x that I would have otherwise included in OpenGL::Sandbox is located here, instead. The main OpenGL::Sandbox module can automatically load this module using the import tag of -V1. After doing so, all these additional symbols are made available from the main OpenGL::Sandbox module.
-V1
Loading OpenGL::Sandbox::V1 causes the "next_frame" in OpenGL::Sandbox function to also call
glLoadIdentity();
This is excluded by default since glLoadIdentity isn't applicable to newer GL programs.
Alias for glLoadIdentity
The default OpenGL context projects with a lower-left of (-1,-1) and upper-right of (1,1), with near and far clipping planes of (-1 .. 1). This isn't terribly useful.
setup_projection( %opts )
This function assists with setting up a coordinate system (either glOrtho or glFrustum) where the aspect ratio of the screen is preserved, and the Z coordinate is pre-translated to something in front of the near clipping plane.
That last bit is hard to describe, but consider that you want a 3D frustum where the left edge of the screen is (-10,0,0) and right edge of the screen is (10,0,0), and the top is at something that matches the aspect ration (like say, (0,.6,0)) and near clipping plane is at z = -10. For that, simply call
(-10,0,0)
(10,0,0)
(0,.6,0)
z = -10
setup_projection( left => -10, right => 10, near => 1, z => 11 );
(near must be greater than zero, and 1 is a good choice. So set Z = Near + 10). If you had tried the similar
Z = Near + 10
glFrustum(-10, 10, -.6, .6, 1, 1000); glTranslate(0,0,-10);
the left and right edges wouldn't be where you wanted after the call to glTranslate. This method corrects for that.
Options:
left
right
top
bottom
width
height
The edges of the screen at the near clipping plane. Missing values will be calculated from others (such as left from width and right) and as a last resort, the aspect ratio of the viewport. (and viewport defaults to same dimensions as screen) If nothing is given, it starts with a bottom of -1 and top of 1 and the rest from viewport aspect ratio.
near
far
The near and far clipping plane. The near clipping plane is the pre-translation value passed to glOrtho or glFrustum. The default far is 1000. The default near is 1 for furstum and -1 for ortho.
ortho
If true, calls glOrtho. Else calls glFrustum.
x
y
z
Coordinates of the desired origin, after setting up the ortho/frustum.
apect
Override the aspect ratio used to calculate default width/height.
mirror_x
mirror_y
Set these (boolean) to flip the orientation of that axis. If only one axis is flipped, then this also updates the value of glFrontFace to GL_CW. Else it sets the value of glFrontFace to GL_CCW (the default).
glFrontFace
GL_CW
GL_CCW
local_matrix { ... };
Wrap a block of code with glPushMatrix/glPopMatrix. This wrapper also checks the matrix stack depth before and after the call, warns if they don't match, and performs any missing glPopMatrix calls.
scale $xyz; scale $x, $y; # z=1 scale $x, $y, $z;
Scale all axes (one argument), the x and y axes (2 arguments), or a normal call to glScale (3 arguments).
trans $x, $y; trans $x, $y, $z;
Translate by x,y or x,y,z. $z defaults to 0 if not supplied.
$z
trans_scale $x, $y, $x, $s; # scale each by $s trans_scale $x, $y, $x, $sx, $sy; # $sz=1 trans_scale $x, $y, $x, $sx, $sy, $sz;
Combination of "trans" then "scale".
rotate $degrees, $x, $y, $z; rotate x => $degrees; rotate y => $degrees; rotate z => $degrees;
Normal call to glRotated, or x/y/z notation to rotate around that axis.
mirror 'x'; # glScale(-1, 0, 0) mirror 'y'; # glScale(0, -1, 0) mirror 'xyz'; # glScale(-1, -1, -1)
Use glScale to invert one more more axes.
local_gl { ... };
Like local_matrix, but also calls glPushAttrib/glPopAttrib. This is expensive, and should probably only be used for debugging.
lines { ... };
Wraps code with glBegin(GL_LINES); ... glEnd();, and also temporarily disables GL_TEXTURE_2D.
glBegin(GL_LINES);
glEnd();
GL_TEXTURE_2D
line_strip { ... };
Wraps code with glBegin(GL_LINE_STRIP); ... glEnd();, and also temporarily disables GL_TEXTURE_2D.
glBegin(GL_LINE_STRIP);
quads { ... }; # wraps code with glBegin(GL_QUADS); ... glEnd();
quad_strip { ... }; # wraps code with glBegin(GL_QUAD_STRIP); ... glEnd();
triangles { ... }; # wraps code with glBegin(GL_TRIANGLES); ... glEnd();
triangle_strip { ... }; # wraps code with glBegin(GL_TRIANGLE_STRIP); ... glEnd();
triangle_fan { ... }; # wraps code with glBegin(GL_TRIANGLE_FAN); ... glEnd();
vertex $x, $y; vertex $x, $y, $z; vertex $x, $y, $z, $w;
Call one of glVertex${N} based on number of arguments.
plot_xy( $geom_mode, # optional, i.e. GL_TRIANGLES or undef $x0, $y0, # Shortcut for many glVertex2d calls $x1, $y1, ... $xN, $yN, );
If $geom_mode is not undef or zero, this makes a call to glBegin and glEnd around the calls to glVertex2d.
$geom_mode
glBegin
glEnd
glVertex2d
plot_xyz( $geom_mode, $x0, $y0, $z0, $x1, $y1, $z1, ... $xN, $yN, $zN, );
Like above, but call glVertex3d.
glVertex3d
plot_st_xy( $geom_mode, $s0, $t0, $x0, $y0, $s1, $t1, $x1, $y1, ... $sN, $tN, $xN, $yN, );
Like above, but calls both glTexCoord2d and glVertex2d.
glTexCoord2d
plot_st_xyz( $geom_mode, $s0, $t0, $x0, $y0, $z0, $s1, $t1, $x1, $y1, $z1, ... $sN, $tN, $xN, $yN, $zN, );
Like above, but call both glTexCoord2d and glVertex3d.
plot_norm_st_xyz( $geom_mode, $nx0, $ny0, $nz0, $s0, $t0, $x0, $y0, $z0, $nx0, $ny0, $nz0, $s1, $t1, $x1, $y1, $z1, ... $nx0, $ny0, $nz0, $sN, $tN, $xN, $yN, $zN, );
Like above, but calls each of glNormal3d, glTexCoord2d, glVertex3d.
glNormal3d
plot_rect(x0,y0, x1,y1)
plot_rect3(x0,y0,z0, x1,y1,z1)
cylinder($base_radius, $top_radius, $height, $radial_slices, $stacks);
Plot a cylinder along the Z axis with the specified dimensions. Shortcut for "cylinder" in OpenGL::Sandbox::V1::Quadric on the default_quadric. That quadric determines whether normals or texture coordinates get generated.
sphere($radius, $radial_slices, $stacks);
Plot a sphere around the origin with specified dimensions. Shortcut for "sphere" in OpenGL::Sandbox::V1::Quadric on the default_quadric.
disk($inner_rad, $outer_rad, $slices, $stacks);
Plot a disk on XY plane around the Z axis with specified inner and outer radius. Shortcut for "disk" in OpenGL::Sandbox::V1::Quadric on the default_quadric.
partial_disk($inner_rad, $outer_rad, $slices, $loops, $start_angle, $sweep_degrees);
Plot a wedge of a disk around the Z axis. Shortcut for "disk" in OpenGL::Sandbox::V1::Quadric on the default_quadric.
my $list= compile_list { ... };
Constructs a displaylist by compiling the code in the block.
call_list($list, sub { ... });
If the variable $list contains a compiled displaylist, this calls that list. Else it creates a new list, assigns it to the variable $list, and compiles the contents of the coderef. This is a convenient way of compiling some code on the first pass and then calling it every iteration after that.
$list
setcolor($r, $g, $b); setcolor($r, $g, $b, $a); setcolor(\@rgb); setcolor(\@rgba); setcolor('#RRGGBB'); setcolor('#RRGGBBAA');
Various ways to specify a color for glSetColor4f. If Alpha component is missing, it defaults to 1.0
my ($r, $g, $b, $a)= color_parts('#RRGGBBAA');
Convenience method that always returns 4 components of a color, given the same variety of formats as setcolor.
my ($r, $g, $b, $a)= color_mult( \@color1, \@color2 )
Multiply each component of color1 by that component of color2.
This function enables a generic overhead light source similar to sunlight. Light0 is set to a directional light source from above (+Y downward) with a slight yellow tinge and large ambient factor. This is mostly useful for quick one-liner scripts to inspect shapes.
draw_axes_xy( $range, $unit_size, $color ); draw_axes_xy( $range, $unit_size, $colorX, $colorY );
Renders the X and Y axis as lines from -$range to +$range, with a thinner lines making a grid of $unit_size squares on the X/Y plane.
-$range
+$range
$unit_size
$range defaults to 1. $unit_size defaults to 0.1. $color defaults to Red for the X axis and Green for the Y axis.
1
0.1
$color
Automatically disables textures for this operation.
draw_axes_xyz( $range, $unit_size, $color ); draw_axes_xyz( $range, $unit_size, $colorX, $colorY, $colorZ );
Renders each of the X,Y,Z axes and the XY, XZ, YZ planes.
draw_boundbox( $x0, $y0, $x1, $y1, $color_edge, $color_to_origin );
Draw lines around a rectangle, and also a line from each corner to the origin, and the section of the X and Y axes that are within the bounds of the rectangle. This is useful for marking a 2D widget relative to the current coordinate system.
In general, "Get" is bad because if the data is coming from the graphics card it can be slow. However, they can be valuable for debugging. These are perl-ified versions of glGetxxx:
my ($x, $y, $w, $h)= get_viewport_rect;
my @matrix4x4= get_matrix(GL_MODELVIEW_MATRIX);
Michael Conrad <mike@nrdvana.net>
This software is copyright (c) 2019 by Michael Conrad.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install OpenGL::Sandbox::V1, copy and paste the appropriate command in to your terminal.
cpanm
cpanm OpenGL::Sandbox::V1
CPAN shell
perl -MCPAN -e shell install OpenGL::Sandbox::V1
For more information on module installation, please visit the detailed CPAN module installation guide.