Changes between Initial Version and Version 1 of GraphicsApiOld


Ignore:
Timestamp:
Apr 19, 2007, 8:46:52 PM (17 years ago)
Author:
KSMarksPsych
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GraphicsApiOld

    v1 v1  
     1= The BOINC graphics API =
     2       
     3
     4BOINC applications can optionally provide graphics, which are displayed either in an application window or in a full-screen window (when the BOINC screensaver is selected).
     5
     6You are encouraged to implement graphics using OpenGL. This makes it easy for your application to show graphics on all platforms.
     7
     8== Integrated graphics ==
     9
     10Graphics can either be integrated in your main application or generated by a separate program. The integrated approach is recommended, and we'll describe it first. In this approach, instead of boinc_init(), an application calls
     11
     12{{{
     13#if defined(_WIN32) || defined(__APPLE__)
     14    retval = boinc_init_graphics(worker);
     15#else
     16    retval = boinc_init_graphics_lib(worker, argv[0]);
     17#endif
     18}}}
     19
     20where worker() is the main function of your application. Your application must supply rendering and input-handling functions (see below).
     21
     22These functions creates a '''worker thread''' that runs the main application function. The original thread becomes the '''graphics thread''', which handles GUI events and does rendering.
     23
     24On Unix, your graphics code must be put in a separate shared library (.so) file. This is because Unix hosts may not have the needed libraries (OpenGL, GLUT, X11). If an application is linked dynamically to these libraries, it will fail on startup if the libraries are not present. On the other hand, if an application is linked statically to these libraries, graphics will be done very inefficiently on most hosts.
     25
     26The shared library must have the same name as the executable followed by '.so'. It must be linked with libboinc_graphics_impl.a, with your rendering and input-handling functions, and (dynamically) with glut and opengl. You must bundle the main program and the shared library together as a [http://boinc.berkeley.edu/tool_update_versions.php multi-file application version]. Unix/Linux applications that use graphics should compile all files with -D_REENTRANT, since graphics uses multiple threads.
     27
     28The [http://boinc.berkeley.edu/example.php BOINC example application] uses this technique, and shows the Makefile command that are needed to produce the shared library on Unix.
     29
     30== Rendering and input-handling functions ==
     31
     32Programs that use integrated graphics must supply the following functions:
     33
     34{{{
     35    void app_graphics_render(int xs, ys, double time_of_day);
     36}}}
     37
     38This will be called periodically in the graphics thread. 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. Applications that don't do graphics must also supply a dummy ''app_graphics_render()'' to link with the API.
     39
     40{{{
     41    void app_graphics_init();
     42}}}
     43
     44This is called in the graphics thread when a window is created. It must make any calls needed to initialize graphics in the window.
     45
     46{{{
     47    void app_graphics_resize(int x, int y);
     48}}}
     49
     50Called when the window size changes.
     51
     52{{{
     53    void app_graphics_reread_prefs();
     54}}}
     55
     56This is called, in the graphics thread, whenever the user's project preferences change. It can call
     57
     58{{{
     59    boinc_parse_init_data_file();
     60    boinc_get_init_data(APP_INIT_DATA&);
     61}}}
     62
     63to get the new preferences.
     64
     65The application must supply the following input-handling functions:
     66
     67{{{
     68void boinc_app_mouse_move(
     69    int x, int y,       // new coords of cursor
     70    int left,          // whether left mouse button is down
     71    int middle,
     72    int right
     73);
     74
     75void boinc_app_mouse_button(
     76    int x, int y,       // coords of cursor
     77    int which,          // which button (0/1/2)
     78    int is_down        // true iff button is now down
     79);
     80
     81void boinc_app_key_press(
     82    int, int            // system-specific key encodings
     83)
     84
     85void boinc_app_key_release(
     86    int, int            // system-specific key encodings
     87)
     88}}}
     89
     90= Limiting frame rate =
     91
     92The following global variables control frame rate:
     93
     94'''boinc_max_fps''' is an upper bound on the number of frames per second (default 30).
     95
     96'''boinc_max_gfx_cpu_frac''' is an upper bound on the fraction of CPU time used for graphics (default 0.5).
     97
     98= Support classes =
     99
     100Several graphics-related classes were developed for SETI@home. They may be of general utility.
     101
     102REDUCED_ARRAY
     103    Represents a two-dimensional array of data, which is reduced to a smaller dimension by averaging or taking extrema. Includes member functions for drawing the reduced data as a 3D graph in several ways (lines, rectangles, connected surface).
     104PROGRESS and PROGRESS_2D
     105    Represent progress bars, depicted in 3 or 2 dimensions.
     106RIBBON_GRAPH
     107    Represents of 3D graph of a function of 1 variable.
     108MOVING_TEXT_PANEL
     109    Represents a flanged 3D panel, moving cyclically in 3 dimentions, on which text is displayed.
     110STARFIELD
     111    Represents a set of randomly-generated stars that move forwards or backwards in 3 dimensions.
     112TEXTURE_DESC
     113    Represents an image (JPEG, Targa, BMP, PNG, or RGB) displayed in 3 dimensions.
     114
     115The file api/txf_util.C has support functions from drawing nice-looking 3D text.
     116
     117= Static graphics =
     118
     119An application can display a pre-existing image file (JPEG, GIFF, BMP or Targa) as its graphic. This is the simplest approach since you don't need to develop any code. You must include the image file with each workunit. To do this, link the application with api/static_graphics.C (edit this file to use your filename). You can change the image over time, but you must change the (physical, not logical) name of the file each time.
     120
     121= Graphics in a separate program =
     122
     123In this approach, an application bundles a 'main program' and a 'graphics program'. The main program executes the graphics program, and kills it when done. The main and graphics programs typically communicate using shared memory; you can use the functions in boinc/lib/shmem.C for this.
     124
     125The main program should initialize using
     126
     127{{{
     128    int boinc_init_options_graphics(BOINC_OPTIONS&, WORKER_FUNC_PTR worker);
     129}}}
     130
     131The graphics application can be implemented using the BOINC framework, in which case it must initialize with
     132
     133{{{
     134    int boinc_init_options_graphics(BOINC_OPTIONS&, NULL);
     135}}}
     136
     137and supply rendering and input-handling functions.
     138
     139Either the graphics or the main program can handle graphics messages from the core client. It's easiest to have the graphics program handle them; if the main program handles them, it must convey them to the graphics program.