/ 
X11-MinimalOpenGLViewport-0.00_00
River stage zero No dependents
/ X11::MinimalOpenGLViewport

NAME

X11::MinimalOpenGLViewport

VERSION

version 0.00_00

SYNOPSIS

use OpenGL;
use X11::MinimalOpenGLViewport;

my $v= X11::MinimalOpenGLViewport->new();
$v->connect;         # connect to X11 server
$v->setup_window;    # create X11 window, default to size of the screen
$v->project_frustum; # convenience for setting up standard GL_PROJECTION matrix

while (1) {
  ...; # Perform your OpenGL rendering
  $v->show();   # calls glXSwapBuffers, and logs glGetError()
}

DESCRIPTION

This module aims to be the quickest easiest way to get OpenGL oputput onto an X11 window, with minimal dependencies and setup hassle.

It does not have an event loop, does not accept window input, and requires no libraries other than OpenGL and XLib. This helps it work in more places than more complete solutions like SDL or GTK. (but while I claim that, I haven't actually tested on that many platforms yet, so the module might need patches if you run on a non-standard system.)

This module might eventually be extended to provide more support for the X11 objects, or it could be rewritten to use XCB instead of XLib, but I probably won't do that any time soon unless someone wants to assist.

ATTRIBUTES

mirror_x

If set to true, this reverses the window coordinates of the GL viewport and the logical coordinates of the OpenGL projection. Only takes effect if you call the "project_frustum" method.

This is automatically enabled if the window width given to "setup_window" is negative.

mirror_y

Like mirror_x.

This is automatically enabled if the window height given to "setup_window" is negative.

viewport_rect

Default value for "project_frustum"'s first argument.

frustum_rect

Default value for "project_frustum"'s second argument.

frustum_depth

Default value for the depth of glFrustum, when "project_frustum" is called.

on_error

$v->on_error(sub {
  my ($viewport, $x_error_info, $is_fatal)= @_;
  ...
});

X11 reports errors asynchronously, which can make it hard to associate an error to its source. This callback lets you know that an error was associated with this particular connection, and gives you the XErrorInfo to help track things down.

If the error was fatal, then $is_fatal is true, $x_error_info will be undef, and you won't be able to make any more XLib calls for the remaindr of your program! In this case you should clean up and exit.

Fatal errors affect all Viewports (and in fact, all other users of XLib, but this module has no control over that) so all viewports will get their on_error called, followed by their on_disconnect handler.

on_disconnect

Called any time you disconnect from the X server for any reason.

METHODS

new

Standard Moo constructor. No attributes are required.

connect

$v->connect();  # defaults to $ENV{DISPLAY}, else ":0"
$v->connect( $display_string );

Connect to X server. Dies if it can't connect.

is_connected

Returns true if this object is connected to an XServer. Does not check the connection.

disconnect

Graceful teardown of OpenGL context, window, and X11 connection

setup_window

$v->setup_window(); # defaults to $ENV{GEOMETRY}, else size of screen
$v->setup_window([ $x, $y, $w, $h ]); # or specify your own size

Create an X11 window and initialize an OpenGL context on it.

Automatically calls "connect" if not connected to a display yet. If "setup_window" has already been called this will destroy the current window and then create a new one.

window_rect

Returns the current rect of the window, live from the X server.

Throws an exception if called before "setup_window"

screen_dims

my ($width, $height, $physical_width_mm, $physical_height_mm)
  = $v->screen_dims

Query X11 for the pixel dimensions and physical dimensions of the default screen. This module does not yet support multi-display setups.

Throws an exception if called before "connect"

screen_pixel_aspect_ratio

my $pixel_aspect= $v->screen_pixel_aspect_ratio();

Returns the ratio of the physical width of one pixel by the physical height of one pixel. If any of the measurements are missing it defaults to 1.0

Throws an exception if called before "connect"

project_frustum

$v->viewport_rect( ... );  # default is size of window
$v->frustum_rect( ... );   # default is top=0.5, bottom=-0.5 with aspect-correct width
$v->project_frustum();
# -or-
$v->project_frustum( $viewport_rect, $frustum_rect );

This method sets up a sensible OpenGL projection matrix. It is not related to X11 and is just provided with this module for your convenience.

Throws an exception if called before "setup_window"

swap_buffers

$v->swap_buffers()

Pass-through to glXSwapBuffers();

Throws an exception if called before "setup_window"

show

Convenience method to call $v->swap_buffers() and log the results of $v->gl_get_errors() to Log::Any

Throws an exception if called before "setup_window"

get_gl_errors

Convenience method to call glGetError repeatedly and build a hash of the symbolic names of the error constants.

Throws an exception if called before "setup_window"

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 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.