Changes between Version 36 and Version 37 of GraphicsApi

Timestamp:

Aug 7, 2014, 10:12:14 AM (10 years ago)

Author:

davea

Comment:

--

GraphicsApi

@@ -10 +10 @@
 == Graphics apps ==
 
-The most general way of providing graphics involves
-using a 'graphics app' program (separate from your main application).
+Graphics are generated by a 'graphics app' program (separate from the main application).
 This graphics app must have the properties that:
 
@@ -98 +97 @@
 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);
+}}}
+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).
+
+{{{
 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.
+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.
+The contents of the shared memory segment are application-dependent;
+typically it contains numeric information describing the state of the computation.
+
 You may want to include the following items:
 {{{
@@ -115 +122 @@
     double cpu_time;
     BOINC_STATUS status;
+    int countdown;
 };
 }}}
 
-This structure should be updated by the main app once per second,
+These items should be updated by the main app once per second,
 using [BasicApi#timer 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 instead display an "application suspended" message.
+ update_time::
+   The current time (dtime()).
+   The graphics app should exit if the current time exceeds this by 5 seconds or so,
+   so that it exits if the main app exits.
+ fraction_done::
+   The last fraction done reported by the main app.
+ cpu_time::
+   The current CPU time, as returned by '''boinc_worker_thread_cpu_time()'''.
+ status::
+   The BOINC status, as returned by '''boinc_get_status()'''.
+   If the 'suspended' flag is set,
+   the graphics app should stop changing its display,
+   and instead show an "application suspended" message.
+ countdown::
+   See below.
 
 Keep in mind that multiple instances of the graphics app may run simultaneously;
@@ -134 +150 @@
 use a semaphore to synchronize access so that the graphics app
 doesn't see an inconsistent state.
+
+=== Efficiency ===
+
+Updating the shared memory structure uses CPU time,
+and it's desirable to avoid this overhead if no graphics app is running.
+
+One way to do this is to include a '''countdown''' field in the shared memory structure, as above.
+ * The graphics sets this to 5 (say) in its '''app_graphics_render()''' function.
+ * The main app decrements this (if positive) once per second.
+ * The main app updates the application-specific data in shared memory
+   only when '''countdown''' is nonzero.
+
+See [ExampleApps the example application] for an example.
 
 === Creating an icon for your applications ===