NAME
OpenGL::Sandbox - Rapid-prototyping utilities for OpenGL
VERSION
version 0.041
SYNOPSIS
use OpenGL::Sandbox qw( -V1 :all );
make_context;
setup_projection;
next_frame;
scale .01;
font('Arial.ttf')->render("Hello World");
next_frame;DESCRIPTION
This module collection aims to provide quick and easy access to OpenGL, for use in one-liners or experiments or simple visualizations. There are many system dependencies involved, so to make the modules more accessible I divided it into multiple distributions:
- OpenGL::Sandbox
-
This package, containing the foundation for the rest, and anything in common among the different OpenGL APIs. It has methods to help set up the context, and load textures.
- OpenGL::Sandbox::V1
-
Everything related to OpenGL 1.x API
- OpenGL::Sandbox::V1::FTGLFont
-
A class providing fonts, but only for OpenGL 1.x
EXPORTS
GL_$CONSTANT, gl$Function
This module can export OpenGL constants and functions, selecting them out of either OpenGL or OpenGL::Modern. When exported by name, constants will be exported as true perl constants. However, the full selection of GL constants and functions is *not* available directly from this module's namespace. i.e. OpenGL::Sandbox::GL_TRUE() does not work.
$res
Returns a default global instance of the resource manager with resource_root_dir pointing to the current directory.
tex
Shortcut for OpenGL::Sandbox::ResMan->default_instance->tex
font
Shortcut for OpenGL::Sandbox::ResMan->default_instance->font
Note that you need to install OpenGL::Sandbox::V1::FTGLFont in order to get font support, currently. Other font providers might be added later.
-V1
Loads OpenGL::SandBox::V1 (which must be installed separately) and makes all its symbols available for importing. This module contains many "sugar" functions to make the GL 1.x API more friendly.
-V2, -V3, etc will likewise import everything from packages named OpenGL::SandBox::V$_ which do not currently exist, but could be authored in the future.
:all
This *only* exports the symbols defined by this module collection, *not* every OpenGL symbol.
make_context
my $context= make_context( %opts );Pick the lightest smallest module that can get a window set up for rendering. This tries: X11::GLX, and SDLx::App in that order. You can override the detection with environment variable OPENGL_SANDBOX_CONTEXT_PROVIDER. It assumes you don't have any desire to receive user input and just want to render some stuff. If you do actually have a preference, you should just invoke that package yourself.
Returns an object whose scope controls the lifecycle of the window, and that object always has a swap_buffers method. If you call this method in void context, the object is stored internally and you can access it with "current_context".
This attempts to automatically pick up the window geometry, either from a "--geometry=" option or from the environment variable OPENGL_SANDBOX_GEOMETRY. The Geometry value is in X11 notation of "${WIDTH}x${HEIGHT}+$X+$Y" except that negative X,Y (from right edge) are not supported.
Not all options have been implemented for each source, but the list of possibilities is:
- x, y, width, height
-
Set the placement and dimensions of the created window.
- visible
-
Defaults to true, but if false, attempts to create an off-screen GL context.
- fullscreen
-
Attempts to create a full-screen context.
- noframe
-
Attempts to create a window without window border decorations.
- title
-
Window title
Note that if you're using Classic OpenGL (V1) you also need to set up the projection matrix to something more useful than the defaults before rendering anything. See "setup_projection" in OpenGL::Sandbox::V1.
current_context
Returns the most recently created result of "make_context", assuming it hasn't been garbage-collected. If you stored the return value of "make_context", then garbage collection happens according to that reference. If you called "make_context" in void context, then the GL context will live indefinitely.
If you have a simple program with only one context, this global simplifies life for you.
next_frame
This calls a sequence of:
current_context->swap_buffers;
warn_gl_errors;
glClear(GL_COLOR_BUFFER_BIT|GL_DEPTH_BUFFER_BIT);If you have loaded "-V1" it also calls
glLoadIdentity();Note that current_context->swap_buffers() will only work after "make_context".
This is intended to help out with quick prototyping and one-liners:
perl -e 'use OpenGL::Sandbox qw( -V1 :all ); make_context; while(1) { next_frame; ...; }'get_gl_errors
Returns the symbolic names of any pending OpenGL errors, as a list.
log_gl_errors
Write all GL errors to Log::Any as ->error
warn_gl_errors
Emit any GL errors using 'warn'
INSTALLING
Getting this module collection installed is abnormally difficult. This is a "selfish module" that I wrote primarily for me, but published in case it might be useful to someone else. My other more altruistic modules aim for high compatibility, but this one just unapologetically depends on lots of specific things.
For the core module, you need:
Perl 5.14 or higher
libGL, and headers
LibAV libraries libswscale, libavutil, and headers, for the feature that automatically rescales textures
Image::PNG::Libpng, for the feature that automatically loads PNG.
File::Map, for efficiently memory-mapping resource files
XS support (C compiler)
For the "V1" module (OpenGL::Sandbox::V1) you will additionally need
libGLU and headers
For the "FTGLFont" module (OpenGL::Sandbox::V1::FTGLFont) you will additionally need
libftgl, and libfreetype2, and headers
You probably also want a module to open a GL context to see things in. This module is aware of OpenGL::GLFW, X11::GLX and SDL, but you can use anything you like since the GL context is global.
AUTHOR
Michael Conrad <mike@nrdvana.net>
COPYRIGHT AND LICENSE
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.