= Screensaver enhancements =

== Organization ==

The BOINC screensaver (Win, Mac) will be divided into two parts:

 * A '''screensaver coordinator''' program that doesn't do graphics (with a few exceptions). Instead, the coordinator will run separate programs (project-supplied graphics apps, and a default graphics app bundled with the installer).  The order and timing of these apps will be configurable.
 * A '''default graphics app''', which the coordinator runs if no project apps are available.  

Organizations that make their own installers (!GridRepublic) might develop
their own default graphics apps, and bundle them with the installer.

The  screensaver coordinator program will display its own graphics only:
 * in preview mode, which will just display a logo.
 * during initialization (establishing contact with the BOINC Client, etc.)
 * when loading the next graphics application.

== Configuration file ==

The '''screensaver coordinator''' can be customized by including an optional XML configuration file named {{{ss_config.xml}}}.  If used, it must be located in the BOINC data directory on both Mac and Windows.

The format is:

{{{
#!xml
<default_ss_first>0</default_ss_first>
<default_gfx_duration>600</default_gfx_duration>
<science_gfx_duration>1800</science_gfx_duration>
<science_gfx_change_interval>600</science_gfx_change_interval>
}}}

This would say to run science app graphics (if any are available) for 30 minutes, changing among science apps every 10 minutes (if multiple tasks are running), 
then run the default graphics app for 10 minutes (600 seconds),
then repeat the entire sequence.

If the {{{<default_ss_first>}}} flag is `1`, the sequence would first run the default graphics app for 10 minutes, 
then continue as above.

Each of the four fields is optional, and the file itself is optional.  If not otherwise specified, the default values for the four fields are the ones shown in the example above.  

 
== Default Graphics Application ==

On Windows, the default graphics app must be named ''boinscr.exe'' and located in the BOINC executable directory (the same directory which contains ''boinc.exe'').  
On the Mac, it must be named ''boincscr'' and located in the directory ''/Library/Application Support/BOINC Data/''.  
Additional support files needed by the default graphics app, such as logos and fonts, should be in the same directory.  


The default graphics app will usually be called with the command-line argument '''--fullscreen''', which may be ignored.  However, it must respond to either of two possible additional command-line arguments:
 * '''--retry_connect''' means that if the default graphics app is unable to connect to the BOINC Client via RPC, it should continue running and retry periodically.
 * '''--test''' means that it should try to connect to the BOINC Client via RPC once, then exit immediately whether or not it succeeded. It should not open a window or draw anything to the screen.  This is used by the BOINC Manager to test whether the RPC is blocked by a local software firewall; if so, most firewalls will then display a dialog so the user can approve it.
 * When neither the '''--retry_connect''' or '''--test''' argument is passed, the default graphics app must return immediately with an error code of {{{-107}}} if it can't connect to the BOINC Client via RPC. 

The default graphics app will be implemented using OpenGL,
using the BOINC graphics library framework.
It will be configurable via a local XML file,
and also via general preferences.


The screensaver coordinator program will run the default graphics app instead of science graphics when no project graphics are available.  This can occur for a number of reasons, such as when BOINC is suspended or idle, when the running science applications don't support graphics, etc.  In these cases, the default graphics app should indicate the reason for not displaying science graphics.


Optional components:

 * Jobs in progress, with 3-D progress bars
 * Logos and slide shows of running projects
 * User-supplied logo
 * User-supplied background image
 * User name, team, credit
 * RSS feeds