Changes between Initial Version and Version 1 of GraphicsApps


Ignore:
Timestamp:
01/26/15 11:50:29 (3 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GraphicsApps

    v1 v1  
     1[[PageOutline]]
     2
     3= Providing graphics for BOINC applications =
     4
     5A BOINC application may provide graphics (e.g. visualizations) to volunteers.
     6These graphics are shown in two contexts:
     7
     8 * As a screensaver, if selected by the user.
     9 * In a window, opened using the Show Graphics button in the BOINC Manager.
     10
     11Graphics are generated by a 'graphics app' program (separate from the main application).
     12This graphics app must have the properties that:
     13
     14 * If invoked with `--fullscreen`, it opens a full-screen borderless window.
     15  It must exit on mouse or keyboard input
     16  (if you use the [#api BOINC graphics API] library this is handled automatically).
     17 * Otherwise it opens a standard window, and may handle mouse/keyboard input.
     18
     19The logical name of the program must be 'graphics_app'.
     20When you set up your [AppVersionNew application version directory], use an entry like
     21{{{
     22<file>
     23   <physical_name>uppercase_graphics_6.14_windows_intelx86.exe</physical_name>
     24   <logical_name>graphics_app</logical_name>
     25</file>
     26}}}
     27in your version.xml file.
     28
     29The graphics app is launched by the BOINC Manager and/or by the screensaver.
     30It may be killed at any time.
     31Multiple instances of the graphics app may run at the same time
     32(e.g. if the user opens a graphics window via the Manager,
     33and then the screensaver runs and launches another instance).
     34
     35
     36== Communication between main and graphics apps ==
     37
     38The graphics app may want to get information from the main app.
     39This can be done using either shared memory or a file.
     40
     41=== Shared memory ===
     42
     43Communicating large amounts of data
     44can be done efficiently using shared memory.
     45The BOINC library supplies the following functions to facilitate this:
     46
     47{{{
     48void* boinc_graphics_make_shmem(char* appname, int size);
     49}}}
     50Called from the main app.
     51Creates a shared memory segment of the given size.
     52 'appname' should be the name of this application (used to ensure uniqueness of the shared-memory segment name).
     53
     54{{{
     55void* boinc_graphics_get_shmem(char* appname);
     56}}}
     57Called from the graphics app.
     58Attaches to an existing segment.
     59It must be called AFTER boinc_parse_init_data_file().
     60
     61The contents of the shared memory segment are application-dependent;
     62typically it contains numeric information describing the state of the computation.
     63
     64You may want to include the following items:
     65{{{
     66struct UC_SHMEM {
     67    double update_time;
     68    double fraction_done;
     69    double cpu_time;
     70    BOINC_STATUS status;
     71    int countdown;
     72};
     73}}}
     74
     75These items should be updated by the main app once per second,
     76using [BasicApi#timer boinc_set_timer_handler()].
     77The items are:
     78 update_time::
     79   The current time (dtime()).
     80   The graphics app should exit if the current time exceeds this by 5 seconds or so,
     81   so that it exits if the main app exits.
     82 fraction_done::
     83   The last fraction done reported by the main app.
     84 cpu_time::
     85   The current CPU time, as returned by '''boinc_worker_thread_cpu_time()'''.
     86 status::
     87   The BOINC status, as returned by '''boinc_get_status()'''.
     88   If the 'suspended' flag is set,
     89   the graphics app should stop changing its display,
     90   and instead show an "application suspended" message.
     91 countdown::
     92   See below.
     93
     94Keep in mind that multiple instances of the graphics app may run simultaneously;
     95avoid having the graphics app write to the shared memory.
     96If you use shared memory to store a data structure,
     97use a semaphore to synchronize access so that the graphics app
     98doesn't see an inconsistent state.
     99
     100Updating the shared memory structure uses CPU time,
     101and it's desirable to avoid this overhead if no graphics app is running.
     102
     103One way to do this is to include a '''countdown''' field in the shared memory structure, as above.
     104 * The graphics sets this to 5 (say) in its '''app_graphics_render()''' function.
     105 * The main app decrements this (if positive) once per second.
     106 * The main app updates the application-specific data in shared memory
     107   only when '''countdown''' is nonzero.
     108
     109See [ExampleApps the example application] for an example.
     110
     111=== File ===
     112
     113Alternatively, you can communicate data from main app to graphics app via a file.
     114The BOINC library provides two functions for this purpose.
     115The main program can call
     116{{{
     117int boinc_write_graphics_status(
     118    const char* filename, double cpu_time, double elapsed_time,
     119    double fraction_done
     120);
     121}}}
     122to write a file containing its status in XML format.
     123The graphics app can call
     124{{{
     125int boinc_parse_graphics_status(
     126    const char* filename, double* update_time, double* cpu_time,
     127    double* elapsed_time, double* fraction_done, BOINC_STATUS* status
     128);
     129}}}
     130to read and parse this file.
     131
     132== Creating an icon for graphics applications ==
     133
     134For Windows:
     135
     136 *  make Icons (there's a tool for this in Visual Studio),
     137  say "boincAppIcon16x16.ico", "boincAppIcon32x32.ico" and "boincAppIcon48x48.ico".
     138 * create a simple resource description file "boincAppIcon.rc" in the same directory
     139  as the icon files pointing to the icon filenames,
     140  the first entry is the resource name that is later passed to setWinIcon():
     141{{{
     142boinca16 ICON boincAppIcon16x16.ico
     143boinca32 ICON boincAppIcon32x32.ico
     144boinca48 ICON boincAppIcon48x48.ico
     145}}}
     146 * compile the resource (I do this on a Visual Studio Command Prompt):
     147{{{
     148rc.exe boincAppIcon.rc
     149}}}
     150 * when linking the App, add the resulting file boincAppIcon.RES to the objects
     151
     152 * we call setWinIcon("boinca16","boinca48") in app_graphics_init()