Changes between Version 3 and Version 4 of GraphicsApi

Timestamp:

Aug 22, 2007, 2:29:09 PM (18 years ago)

Author:

davea

Comment:

--

GraphicsApi

@@ -6 +6 @@
 
  * If invoked with --fullscreen, it must open a full-screen borderless window, and must exit when mouse or keyboard input occurs.
- * Otherwise it must open a standard window; in this case it may handle mouse/keyboard input.
+ * If not invoked with --fullscreen, it must open a standard window; in this case it may handle mouse/keyboard input.
 
 The BOINC graphics API (described below) provides cross-platform support for
@@ -20 +20 @@
 == The BOINC Graphics 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_render(int xs, ys, double time_of_day);
+void app_graphics_resize(int x, int y);
+void boinc_app_mouse_move();
+void boinc_app_mouse_button();
+void boinc_app_key_press();
+void boinc_app_key_release();
+}}}
+These functions are described [GraphicsApi here].
+
+== Communicating with the main application ==
+
+Typically the graphics app will 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.
+
+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;
+};
+}}}
+
+ update_time:: the time of day when this structure was last modified.  This can be used to implement a 'heartbeat' mechanism so that the graphics app will exit if the main app dies.
+ fraction_done:: the last fraction done reported by the main app.
+ cpu_time:: the last CPU time reported by the main app.
+ 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.