- SEE ALSO
Prima::OpenGL - Prima extension for OpenGL drawing
The module allows for programming GL library together with Prima widgets. OpenGL module does a similar jobs using freeglut GUI library.
Before a GL area is used, a GL visual need to be selected first. Currently this process is done by system-specific search function, so results differ between win32 and x11. Namely, x11 is less forgiving, and may fail with error. Also, win32 and x11 GL defaults are different.
All attributes are passed to function
context_create as a hashref (see description below). If an option is not set, or set to undef, system default is used.
- render ( "direct" or "xserver" )
Specifies whether rendering is to be done with a direct connection to the graphics system if possible ("direct") or through the X server ("xserver"). If direct is True, then a direct rendering context is created if the implementation supports direct rendering, if the connection is to an X server that is local, and if a direct rendering context is available. (An implementation may return an indirect context when direct is True.) If direct is False, then a rendering context that renders through the X server is always created. Direct rendering provides a performance advantage in some implementations. However, direct rendering contexts cannot be shared outside a single process, and they may be unable to render to GLX
I here may add that I needed that option when was testing cygwin implementation of the module in no-X11 environment. I couldn't get my X11 working on windows, and installed one under VirtualBox. However, the only way I could connect to X server there was to tell VirtualBox to forward the port 6000 inside the emulator to the host machine's 6000. GLX was happy finding that the connection was local, and tried to use shared memory or whatever underlies "direct" connection, and failed, instead of doing a soft fall-back to x11 protocol. The only way to make it work in such condition was explicitly setting config to "xserver".
Actual for x11 only.
- pixels ( "rgba" or "paletted" )
Selects either paletted or true-color visual representation.
- layer INTEGER
x11: Layer zero corresponds to the main frame buffer of the display. Layer one is the first overlay frame buffer, level two the second overlay frame buffer, and so on. Negative buffer levels correspond to underlay frame buffers.
win32: Provides only three layers, -1, 0, and 1 .
- double_buffer BOOLEAN
If set, select double buffering.
- stereo BOOLEAN
If set, select a stereo visual.
- color_bits INTEGER
Indicates the desired color index buffer size. Usual values are 8, 15, 16, 24, or 32.
- aux_buffers INTEGER
Indicated the desired number of auxilliary buffers.
- depth_bits INTEGER
If this value is zero, visuals with no depth buffer are preferred. Otherwise, the largest available depth buffer of at least the minimum size is preferred.
- stencil_bits INTEGER
Indicates the desired number of stencil bitplanes. The smallest stencil buffer of at least the specified size is preferred. If the desired value is zero, visuals with no stencil buffer are preferred.
- red_bits green_bits blue_bits alpha_bits INTEGER
If this value is zero, the smallest available red/green/blue/alpha buffer is preferred. Otherwise, the largest available buffer of at least the minimum size is preferred.
- accum_red_bits accum_green_bits accum_blue_bits accum_alpha_bits INTEGER
If this value is zero, visuals with no red/green/blue/alpha accumulation buffer are preferred. Otherwise, the largest possible accumulation buffer of at least the minimum size is preferred.
Pushes the current GL context on an internal stack; there can be only 32 entries. Returns success flag.
Pops the top GL context from the stack, and selects it. Returns success flag.
On X11, returns True if ctx is a direct rendering context, False otherwise. Direct rendering contexts pass rendering commands directly from the calling process's address space to the rendering system, bypassing the X server. Nondirect rendering contexts pass all rendering commands to the X server.
On Win32 return True.
last_errorthat returns string representation of the last error, or undef if there was none. Note that X11 errors are really unspecific due to asynchronous mode X server and clients operate; expect some generic error strings there.
The module also injects a set of gl_ methods for general use on Widget, Application, DeviceBitmap, Image, and Printer (the latter on win32 only) objects.
- gl_create %config
Creates a GL context and prepares it for drawing on the object. If the object is not a widget, it needs to be in
begin_paintstate. See valid
%configvalues in "Selection of a GL visual" .
Destroys GL context. Note that it doesn't synchronize GL area content, one should do that manually using
gl_flush(and also remember to call glFinish when drawing on bitmaps!). Need to be always called otherwise GL contexts would leak.
- gl_begin_paint %config
Shortcut for gl_create and gl_select. See valid
%configvalues in "Selection of a GL visual" .
Shortcut for gl_flush and gl_destroy.
Returns boolean flag indicating whether the object is within gl_begin_paint/gl_end_paint state.
Associates the widget visual with current GL context, so GL functions can be used on the widget.
Disassociates any GL context.
- gl_do &SUB
Executes &SUB within current GL context, restores context after the SUB is finished.
Copies eventual off-screen GL buffer to the screen. Needs to be always called at the end of paint routine.
- gl_read_pixels origin => [0,0], size => [ $self->size ], format => GL_UNSIGNED_BYTE, type => GL_RGB, icon => 0
Prima::Imageobject, and efficiently fills the pixels from the GL context using glReadPixels call. If either
format => GL_RGBAor
icon => 1is set, creates a
Prima::Iconobject, also filling the alpha channel.
The following combination of
typeproduce these images:
format => GL_RGB- im::RGB images .
- Grayscale images with
formatset to GL_RED, GL_GREEN, GL_DEPTH_COMPONENT etc
type => GL_UNSIGNED_BYTE|GL_BYTE- im::Byte
type => GL_UNSIGNED_SHORT|GL_SHORT- im::Short
type => GL_UNSIGNED_INT|GL_INT- im::Long
type => GL_FLOAT- im::Float
sizeare sent as is to
- gl_image_prepare $IMAGE, preferred_format
Prepares image for GL-compatible image pixel data call, and returns it together with the necessary GL constants. Returns IMAGE, FORMAT, TYPE, DATA, where IMAGE is either the original image or cloned copy with adjusted pixel format; FORMAT and TYPE are GL format and type constants. DATA is pixel storage pointer, suitable for use in OpenGL calls with _c postfix. It can be used for implementation of Prima-specific wrappers of pixel-based calls.
If the image has RGB type, the preferred_format is ignored, otherwise it has to be specificed to one of GL_ format constants, such as GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_LUMINANCE, or GL_LUMINANCE_ALPHA.
- gl_draw_pixels $IMAGE, format
Prima wrapper of
On X11, the GL context is lost when the widget is implicitly re-created. Prima::GLWidget tries to handle that by re-creating the context on that event, however, it doesn't restore GL properties set outside its
gl_config. One needs to track
SysHandle event and update the GL context manually if re-creation of GL-capable widgets takes place.
On Win32, re-creation of GL context on same window won't work ( See https://www.opengl.org/wiki/Platform_specifics:_Windows#How_many_times_can_I_call_SetPixelFormat.3F ).
Win32 DWM API does not recognize black pixels from OpenGL surfaces as transparent, while it does so for regular widgets. If this is needed, set layered(1) on your GLWidget.
See examples/icosahedron.pl for an example.
Dmitry Karasik, <firstname.lastname@example.org>.
git clone email@example.com:dk/Prima-OpenGL.git
This software is distributed under the BSD License.
Thanks to Chris Marshall for the motivating me writing this module!