forked from stebulus/xscreensaver
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.hacking
180 lines (130 loc) · 8.07 KB
/
README.hacking
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
==========================================================================
Writing new XScreenSaver modules
==========================================================================
Any program that can be made to render on an X window created by another
process can be used as a screen saver. Just get the window ID out of
$XSCREENSAVER_WINDOW, draw on that, and you're done.
In theory, you can write a screen saver in any language you like. In
practice, however, languages other than C or C++ tend not to allow you to
draw to windows that they did not create themselves. Unfortunately, this
means that if you want to write a screen saver, you must write it in C.
Given that you're going to be writing in C, you might as well take
advantage of the various utility functions that I have written to make
that easier. Writing a new screen saver in C using the frameworks
included with xscreensaver simplifies things enormously.
Generally, the best way to learn how to do something is to find a similar
program, and play around with it until you understand it. Another
approach is to not worry about understanding it, but to just hack it out.
Either way, your best bet is probably to start with one of the existing
xscreensaver demos, included in the "hacks/" directory, rename the file,
and edit it until it does what you want.
The "Greynetic" and "Deluxe" hacks are probably good ones to start with,
since they are so very simple. For OpenGL programs, "DangerBall" is a
good example.
==========================================================================
Requirements for inclusion with the XScreenSaver collection
==========================================================================
If you come up with anything, send it to me! If it's good, I'd love to
include it in the xscreensaver distribution. However, there are a few
requirements for me to distribute it:
- Write in portable ANSI C. No C++. No nonstandard libraries.
- Write a .man page describing all command-line options.
- Write an .xml file describing the graphical configuration dialog box.
- Include a BSD-like copyright/license notice at the top of each source
file (preferably, just use the one from "screenhack.h", and include
your name and the current year). The GNU GPL is not compatible with
the rest of XScreenSaver.
==========================================================================
The XScreenSaver API
==========================================================================
- Start with #include "screenhack.h"
- Define 2 global variables:
yoursavername_defaults -- Default values for the resources you use.
yoursavername_options -- The command-line options you accept.
- Define 5 functions:
yoursavername_init -- Return an object holding your global state.
yoursavername_draw -- Draw a single frame, quickly.
yoursavername_free -- Free everything you've allocated.
yoursavername_reshape -- Called when the window is resized.
yoursavername_event -- Called when a keyboard or mouse event happens.
The "event" function will only be called when running in a window
(not as a screen saver). The "reshape" event will be called when the
window size changes, or (as a screen saver) when the display size
changes as a result of a RANDR event (e.g., plugging in a new monitor).
It's ok for both the "event" and "resize" functions to do nothing.
- All other functions should be static.
- The last line of the file should be
XSCREENSAVER_MODULE ("YourSaverName", yoursavername)
- Finally, edit the Makefile to add a rule for your program.
Just cut-and-paste one of the existing rules.
Your "draw" must not run for more than a fraction of a second without
returning. This means "don't call usleep()". Everything has to be a
state machine.
You may not store global state in global variables, or in function-local
static variables. All of your runtime state must be encapsulted in the
"state" object created by your "init" function. If you use global or
static variables, your screen saver will not work properly on MacOS.
Do not call XSync() or XFlush(). If you think you need to do that, it
probably means that you are you are relying on the speed of the graphics
card for timing, which probably means that your "draw" function is
taking too long.
==========================================================================
The XLockMore API
==========================================================================
Some of the display modes that come with xscreensaver were ported from
XLock, and so, for historical reasons, they follow a slightly different
programming convention. For newly-written Xlib programs, you'd be
better off following the pattern used in hacks like "Deluxe" than in
hacks like "Flag". The XLockMore ones are the ones that begin with
"#ifdef STANDALONE" and #include "xlockmore.h".
But, all OpenGL screen savers have to follow the XLockMore API.
The XLockMore API is similar to the XScreenSaver API, in that you define
(roughly) the same set of functions, but the naming conventions are
slightly different. Instead of "hackname_init", it's "init_hackname",
and it should be preceeded with the pseudo-declaration ENTRYPOINT.
One annoying mis-feature of the XLockMore API is that it *requires* you
to make use of global variables for two things: first, for each of your
command line options; and second, for an array that holds your global
state objects. These are the only exceptions to the "never use global
variables" rule.
==========================================================================
Programming Tips
==========================================================================
- Your screen saver should look reasonable at 20-30 frames per second.
That is, do not assume that your "draw" function will be called more
than 20 times a second. Even if you return a smaller requested delay
than that, you might not get it. Likewise, if your "draw" function
takes longer than 1/20th of a second to run, your screen saver may be
consuming too much CPU.
- Don't make assumptions about the depth of the display, or whether it
is colormapped. You must allocate all your colors explicitly: do not
assume you can construct an RGB value and use that as a pixel value
directly. Use the utility routines provided by "utils/colors.h" to
simplify color allocation.
- It is better to eliminate flicker by double-buffering to a Pixmap
than by erasing and re-drawing objects. Do not use drawing tricks
involving XOR.
- If you use double-buffering, have a resource to turn it off. (MacOS
has double-buffering built in, so you'd be triple-buffering.)
- Understand the differences between Pixmaps and XImages, and keep in
mind which operations are happening in client memory and which are in
server memory, and which cause latency due to server round-trips.
Sometimes using the Shared Memory extension can be helpful, but
probably not as often as you might think.
- On modern machines, OpenGL will always run faster than Xlib. It's
also more portable. Consider writing in OpenGL whenever possible.
==========================================================================
The MacOS X Port
==========================================================================
Though XScreenSaver started its life as an X11 program, it also now runs
on MacOS X. If you do your development on an X11 system, and follow the
usual XScreenSaver APIs, you shouldn't need to do anything special for
it to also work on MacOS.
The preprocessor macro HAVE_COCOA will be defined when being compiled in
a MacOS (Cocoa/Quartz) environment, and will be undefined when compiling
against "real" Xlib.
To compile on MacOS, use the XCode project included in the source
distribution. You shouldn't need to have X11 installed, and shouldn't
need to run "configure" first. MacOS 10.4.0 and XCode 3.1 or newer are
required.
==========================================================================