Using OpenGL

The BOINC graphics API provides cross-platform support for developing graphics apps.

A complete example can be found in boinc/samples/example_app.

The BOINC Graphics API

BOINC supplies a library (libboinc_graphics2.a) with support for 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_init();

Called once, after the window has been created.

void app_graphics_render(int xs, ys, double time_of_day);

This will be called periodically. 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.

void app_graphics_resize(int x, int y);

Called when the window size changes.

void boinc_app_mouse_move(
    int x, int y,       // new coords of cursor
    int left,          // whether left mouse button is down
    int middle,
    int right
);

void boinc_app_mouse_button(
    int x, int y,       // coords of cursor
    int which,          // which button (0/1/2)
    int is_down        // true iff button is now down
);

void boinc_app_key_press(
    int, int            // system-specific key encodings
)

void boinc_app_key_release(
    int, int            // system-specific key encodings
)

Support classes

Several graphics-related classes were developed for SETI@home. They may be of general utility.

TEXTURE_DESC

Represents a JPEG image displayed in 3 dimensions.

PROGRESS and PROGRESS_2D

Represent progress bars, depicted in 3 or 2 dimensions.

REDUCED_ARRAY

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).

RIBBON_GRAPH

Represents of 3D graph of a function of 1 variable.

MOVING_TEXT_PANEL

Represents a flanged 3D panel, moving cyclically in 3 dimensions, on which text is displayed.

STARFIELD

Represents a set of randomly-generated stars that move forwards or backwards in 3 dimensions.

The file api/ttfont.cpp has support functions from drawing nice-looking 3D text.

Displaying a static image

An application can display a pre-existing JPEG file 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.cpp (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.

Displaying text

BOINC supports the display of text using TrueType fonts.

• Add the files api/ttfont.cpp and api/ttfont.h to your application (they are not included in any BOINC library.)
• Link with the ​FreeType2 and ​FTGL libraries. Depending on how you build the FreeType2 library, FreeType2 may require the libz and libbz2 libraries. For Windows, prebuilt libraries are available in the boinc_depends_win_vs2005 repository. To build these libraries on the Mac, please see MacBuild.
• Include the desired TrueType fonts in your app versions. The set of free ​Liberation fonts in included the api/ttf/ directory. If you wish to use other TrueType fonts, you'll need to adjust the list of font names in ttfont.cpp. (Another source of free fonts is the ​GNU Freefont project.)
• To display text, use the following API functions:

  float white[4] = {1., 1., 1., 1.};
  APP_INIT_DATA aid;
  boinc_get_init_data(aid);
  
  // read font files; they're in the project directory
  //
  ttf_load_fonts(aid.project_dir);
  ...
  ttf_render_string(
     x, y, z,            // where to display string
     500,                // size
     white,              // color
     "App suspended"     // the text
     0,                  // which font (see ttfont.cpp)
                         // default is Sans-Regular (0)
  );
  
  

Other parameters to ttf_render_string() let you specify rotation; see ttfont.h. For examples, see the clientscr/ss_app.cpp and samples/exampple_app/uc2_graphics.cpp in the BOINC trunk.