.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "OpenGL::XScreenSaver 3pm"
.TH OpenGL::XScreenSaver 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
OpenGL::XScreenSaver \- prepare environment for writing OpenGL\-based XScreenSaver hacks
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& use OpenGL qw(:all);
\& use OpenGL::XScreenSaver;
\&
\& OpenGL::XScreenSaver::init();
\& # GetOptions(...); # parse your own options, if any
\&
\& OpenGL::XScreenSaver::start();
\&
\& while (1) {
\&     glClear(...);
\&     # draw your scene here
\&     OpenGL::XScreenSaver::update();
\& }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module allows you to write OpenGL XScreenSaver hacks in Perl. It prepares
the GL to be used with XScreenSaver.
.PP
Read the synopsis for how your program might look.
.SS "Description of functions"
.IX Subsection "Description of functions"
The \fBinit()\fR function will return a true value if a window to draw on has been
found, and a false value if a window will have to be created. This value can
be ignored unless you want to make sure that your screenhack cannot be
executed outside XScreenSaver (e.g. if your standalone version comes as an
extra binary with keyboard control, which would be useless in a screensaver).
.PP
The \fBstart()\fR function will open the connection to the X server and bind to
the window ID or create a new window to draw on (depends on if it was called
standalone or from XScreenSaver).
.PP
The \fBupdate()\fR function should be called when you finished rendering the
frame. It will flush output and swap the buffers. In the future it might also
handle a minimal set of X events when run in standalone mode (like window
deletion requests by the window manager).
.PP
The \fBdimensions()\fR function returns a list with the width and the height of
the currently used window.
.SS "About screenhacks"
.IX Subsection "About screenhacks"
What follows is a short description of how it works and what XScreenSaver
expects a screenhack to do.
.PP
XScreenSaver tells the hack on startup what window ID the hack shall draw to.
This is either a small window mapping to the screen in the preview dialog, or
a fullscreen window. The window ID is passed either via the \fB\-window\-id\fR
option or via the \fBXSCREENSAVER_WINDOW\fR environment variable. \fBinit()\fR of
this module checks both of these.
.PP
XScreenSaver handles all user input including exiting and pausing the
screensaver. The process is sent a SIGSTOP when the unlock screen is displayed,
obviously a SIGCONT when it is dismissed, and when the pointing device is
moved or the screen gets unlocked XScreenSaver sends a SIGTERM. This means
that no event handling is required by your screenhack whatsoever. This again
keeps the design of a screenhack dead simple.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
OpenGL
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
Made 2010 by Lars Stoltenow.
OpenGL::XScreenSaver is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.