= Application graphics =

A BOINC application may produce graphics 
with a separate 'graphics app' program having the properties that:

 * If invoked with `--fullscreen`, it opens a full-screen borderless window.  It must exit on mouse or keyboard input; this is handled automatically by `boinc_graphics_loop()` if you use the [#api BOINC graphics API] library.
 * Otherwise it opens a standard window, and may handle mouse/keyboard input.

The logical name of the program must be 'graphics_app'.
When you set up your application version directory, give it a filename like
{{{
graphics_app=uc2_graphics_5.10_windows_intelx86.exe
}}}

The graphics app is launched by the BOINC Manager and by the screensaver.
It may be killed at any time.
Multiple instances of the graphics app may run at the same time
(e.g. if the user opens a graphics window via the Manager,
and then the screensaver runs and launches another instance).

The [#api BOINC graphics API] provides cross-platform support for
developing graphics apps; however, you need not use it.

A complete example can be found in [ExampleApps boinc_samples/example_app].

== Compatibility == #compatibility

Let's call this the "new" way of doing graphics.
There is also an "old" way, in which graphics are generated by
a separate thread in the main application process
(see [GraphicsApiOld old API description]).

New and old applications types interact with client software versions as follows:

 || || old apps || new apps ||
 || client version 5 || * || * ||
 || client version 6+ || * || ** ||

* graphics work except with service-mode install
[[BR]]** graphics work in all situations

== The BOINC Graphics API == #api

BOINC supplies a library (libboinc_graphics2.a) that makes it easy to develop graphics apps.
To use this library, the graphics app must call
{{{
boinc_graphics_loop(int argc, char** argv);
}}}
after its initialization.
This function executes an event loop, and does not return.

The application must supply the following functions:
{{{
void app_graphics_init();
}}}
Called once, after the window has been created.
{{{
void app_graphics_render(int xs, ys, double time_of_day);
}}}

This will be called periodically.
It should generate the current graphic.
`xs` and `ys` are the X and Y sizes of the window, and `time_of_day` is the relative time in seconds. 

{{{
void app_graphics_resize(int x, int y);
}}}

Called when the window size changes.

{{{
void boinc_app_mouse_move(
    int x, int y,       // new coords of cursor
    int left,          // whether left mouse button is down
    int middle,
    int right
);

void boinc_app_mouse_button(
    int x, int y,       // coords of cursor
    int which,          // which button (0/1/2)
    int is_down        // true iff button is now down
);

void boinc_app_key_press(
    int, int            // system-specific key encodings
)

void boinc_app_key_release(
    int, int            // system-specific key encodings
)
}}}

== Communicating with the main application ==

The graphics app may want to get information from the main app.
This can be done efficiently using shared memory.
The BOINC library supplies the following functions to facilitate this:
{{{
void* boinc_graphics_make_shmem(char* appname, int size);
void* boinc_graphics_get_shmem(char* appname);
}}}
`boinc_graphics_make_shmem()` (called from the main app) creates a shared memory segment of the given size.
'appname' should be the name of this application (used to ensure uniqueness of the shared-memory segment name). `boinc_graphics_get_shmem()` (called from the graphics app) attaches to an existing segment.
It must be called AFTER boinc_parse_init_data_file().

The contents of the shared memory segment are up to you.
You may want to include the following items:
{{{
struct UC_SHMEM {
    double update_time;
    double fraction_done;
    double cpu_time;
    BOINC_STATUS status;
};
}}}

This structure should be updated by the main app once per second,
using [BasicApi#Registeringatimerhandler boinc_set_timer_handler()].
The items are:
 update_time:: The current time (dtime()).  The graphics app should exit if the current time exceeds this by 5 seconds or so.
 fraction_done:: The last fraction done reported by the main app.
 cpu_time:: The current CPU time.
 status:: The BOINC status.  If the 'suspended' flag is set, the graphics app should stop changing its display, and simply display an "application suspended" message.

Keep in mind that multiple instances of the graphics app may run simultaneously;
avoid having the graphics app write to the shared memory.
If you use shared memory to store a data structure,
use a semaphore to synchronize access so that the graphics app
doesn't see an inconsistent state.

== Creating an icon for your applications ==

(The following instructions, for Windows, are from Bernd Machenschalk):

 *  make Icons (honestly I don't remember much about this - I vaguely remember there was a tool for this in Visual Studio), say "boincAppIcon16x16.ico", "boincAppIcon32x32.ico" and "boincAppIcon48x48.ico".

 * create a simple resource description file "boincAppIcon.rc" in the same directory as the icon files pointing to the icon filenames, the first entry is the resource name that is later passed to setWinIcon():
{{{
boinca16 ICON boincAppIcon16x16.ico
boinca32 ICON boincAppIcon32x32.ico
boinca48 ICON boincAppIcon48x48.ico
}}}
 * compile the resource (I do this on a Visual Studio Command Prompt):
{{{
rc.exe boincAppIcon.rc
}}}
 * when linking the App, add the resulting file boincAppIcon.RES to the objects

 * we call setWinIcon("boinca16","boinca48") in app_graphics_init()