diff --git a/GraphicsApi.md b/GraphicsApi.md index 852c09c..99d66bf 100644 --- a/GraphicsApi.md +++ b/GraphicsApi.md @@ -1,60 +1,60 @@ -[[PageOutline]] +# Using OpenGL The [BOINC graphics API](#api) provides cross-platform support for developing graphics apps. A complete example can be found in [boinc/samples/example_app](ExampleApps). -# The BOINC Graphics API #api +# 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); - +``` +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(); - +``` +void app_graphics_init(); +``` Called once, after the window has been created. - - void app_graphics_render(int xs, ys, double time_of_day); - +``` +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. +`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); - +``` +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 - ) - +``` +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 @@ -62,17 +62,17 @@ Called when the window size changes. 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. + Represents a JPEG image displayed in 3 dimensions. `PROGRESS` and `PROGRESS_2D` - Represent progress bars, depicted in 3 or 2 dimensions. + 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). + 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. + 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. + 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. + 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. @@ -94,33 +94,33 @@ BOINC supports the display of text using TrueType fonts. * Link with the [FreeType2](http://www.freetype.org) and [FTGL](http://sourceforge.net/projects/ftgl/files/FTGL%20Source/) 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. + For Windows, prebuilt libraries are available; see https://boinc.berkeley.edu/boinc_depends/. To build these libraries on the Mac, please see MacBuild. * Include the desired TrueType fonts in your [ app versions](AppVersionNew). - The set of free [fonts](Liberation)(https://fedorahosted.org/liberation-fonts) in included the `api/ttf/` directory. + The set of free [Liberation fonts](https://fedorahosted.org/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 [Freefont project](GNU)(http://www.gnu.org/software/freefont).) + (Another source of free fonts is the [GNU Freefont project](http://www.gnu.org/software/freefont).) * 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) - ); - - +``` +float white[4] = {1., 1., 1., 1.}; +APP_INIT_DATA aid; +boinc_get_init_data(aid); -Other parameters to *ttf_render_string()* let you specify rotation; see ttfont.h. +// 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.