Changes between Version 37 and Version 38 of GraphicsApi

Timestamp:

Jan 5, 2015, 2:18:53 PM (10 years ago)

Author:

davea

Comment:

--

GraphicsApi

@@ -3 +3 @@
 
 A BOINC application may provide graphics (e.g. visualizations) to volunteers.
-These graphics appear in two contexts:
-
- * As a screensaver.
- * In a window (opened using the Show Graphics button in the BOINC Manager).
+These graphics are shown in two contexts:
+
+ * As a screensaver, if selected by the user.
+ * In a window, opened using the Show Graphics button in the BOINC Manager.
 
 == Graphics apps ==
@@ -14 +14 @@
 
  * 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.
+  It must exit on mouse or keyboard input
+  (if you use the [#api BOINC graphics API] library this is handled automatically).
  * 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 [AppVersionNew application version directory],
-use an entry like
+When you set up your [AppVersionNew application version directory], use an entry like
 {{{
 <file>
@@ -29 +28 @@
 in your version.xml file.
 
-The graphics app is launched by the BOINC Manager and by the screensaver.
+The graphics app is launched by the BOINC Manager and/or by the screensaver.
 It may be killed at any time.
 Multiple instances of the graphics app may run at the same time
@@ -35 +34 @@
 and then the screensaver runs and launches another instance).
 
-The [#api BOINC graphics API] provides cross-platform support for
-developing graphics apps.
+The [#api BOINC graphics API] provides cross-platform support for developing graphics apps.
 
 A complete example can be found in [ExampleApps boinc/samples/example_app].
@@ -42 +40 @@
 === The BOINC Graphics API === #api
 
-BOINC supplies a library (libboinc_graphics2.a) that makes it easy to develop graphics apps.
+BOINC supplies a library (libboinc_graphics2.a) with support for graphics apps.
 To use this library, the graphics app must call
 {{{
@@ -92 +90 @@
 }}}
 
-=== Communicating with the main application ===
+=== Communication between main and graphics apps ===
 
 The graphics app may want to get information from the main app.
-This can be done efficiently using shared memory.
+This can be done using either shared memory or a file.
+
+==== Shared memory ====
+
+Communicating large amounts of data
+can be done efficiently using shared memory.
 The BOINC library supplies the following functions to facilitate this:
 
@@ -151 +154 @@
 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.
@@ -163 +164 @@
 
 See [ExampleApps the example application] for an example.
+
+==== File ====
+
+Alternatively, you can communicate data from main app to graphics app via a file.
+The BOINC library provides two functions for this purpose.
+The main program can call
+{{{
+int boinc_write_graphics_status(
+    const char* filename, double cpu_time, double elapsed_time,
+    double fraction_done
+);
+}}}
+to write a file containing its status in XML format.
+The graphics app can call
+{{{
+int boinc_parse_graphics_status(
+    const char* filename, double* update_time, double* cpu_time,
+    double* elapsed_time, double* fraction_done, BOINC_STATUS* status
+);
+}}}
+to read and parse this file.
 
 === Creating an icon for your applications ===
@@ -236 +258 @@
 
  * Add the files `api/ttfont.cpp` and `api/ttfont.h` to your application (they are not included in any BOINC library.)
- * Link with the [http://www.freetype.org FreeType2]
+ * Link with the [http://www.freetype.org FreeType2]
   and [http://sourceforge.net/projects/ftgl/files/FTGL%20Source/ FTGL] libraries.
   Depending on how you build the FreeType2 library, FreeType2 may require the libz and libbz2 libraries.