==========================================================================
+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
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 GL programs, "DangerBall" is a good
-example.
+since they are so very simple. For OpenGL programs, "DangerBall" is a
+good example.
==========================================================================
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 "reshape" and "event" functions are only
- called when running in a window (not as a
- screen saver). It's ok for them to do nothing.
+
+ 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.
hacks like "Flag". The XLockMore ones are the ones that begin with
"#ifdef STANDALONE" and #include "xlockmore.h".
- All of the OpenGL screen savers follow the XLockMore API.
+ 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
- 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.
+ directly. In particular, you can't make assumptions about whether
+ pixels are RGB, RGBA, ARGB, ABGR, or even whether they are 32, 24,
+ 16 or 8 bits. 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.)
+ - If you use double-buffering, have a resource to turn it off. (MacOS,
+ iOS and Android have double-buffering built in, so you'd end up
+ triple-buffering.)
- Understand the differences between Pixmaps and XImages, and keep in
mind which operations are happening in client memory and which are in
==========================================================================
-The MacOS X Port
+MacOS, iOS and Android
==========================================================================
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
+ on MacOS, iOS and Android, due to a maniacal collection of compatibility
+ shims. 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.
+ it to also work on MacOS and on phones.
- 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 2.2 or newer are
- required.
+ See the READMEs in the OSX/ and android/ directories for instructions on
+ compiling for those platforms.
==========================================================================
projects / xscreensaver / blobdiff