|
发表于 2006-5-5 15:44:37
|
显示全部楼层
THE BOINC GRAPHICS API
http://boinc.berkeley.edu/graphics.php
[原文]
BOINC 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).
You are encouraged to implement graphics using OpenGL. This makes it easy for your application to show graphics on all platforms.
Integrated graphics
Graphics 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
#if defined(_WIN32) || defined(__APPLE__)
retval = boinc_init_graphics(worker);
#else
retval = boinc_init_graphics_lib(worker, argv[0]);
#endif
where worker() is the main function of your application. Your application must supply rendering and input-handling functions (see below).
These 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.
On 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.
The 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 multi-file application version. Unix/Linux applications that use graphics should compile all files with -D_REENTRANT, since graphics uses multiple threads.
The BOINC example application uses this technique, and shows the Makefile command that are needed to produce the shared library on Unix.
Rendering and input-handling functions
Programs that use integrated graphics must supply the following functions:
void app_graphics_render(int xs, ys, double time_of_day);
This 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.
void app_graphics_init();
This is called in the graphics thread when a window is created. It must make any calls needed to initialize graphics in the window.
void app_graphics_resize(int x, int y);
Called when the window size changes.
void app_graphics_reread_prefs();
This is called, in the graphics thread, whenever the user's project preferences change. It can call
boinc_parse_init_data_file();
boinc_get_init_data(APP_INIT_DATA&);
to get the new preferences.
The application must supply the following input-handling functions:
void boinc_app_mouse_move(
int x, int y, // new coords of cursor
bool left, // whether left mouse button is down
bool middle,
bool right
);
void boinc_app_mouse_button(
int x, int y, // coords of cursor
int which, // which button (0/1/2)
bool 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
)
Limiting frame rate
The following global variables control frame rate:
boinc_max_fps is an upper bound on the number of frames per second (default 30).
boinc_max_gfx_cpu_frac is an upper bound on the fraction of CPU time used for graphics (default 0.5).
Support classes
Several graphics-related classes were developed for SETI@home. They may be of general utility.
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).
PROGRESS and PROGRESS_2D
Represent progress bars, depicted in 3 or 2 dimensions.
RIBBON_GRAPH
Represents of 3D graph of a function of 1 variable.
MOVING_TEXT_PANEL
Represents a flanged 3D panel, moving cyclically in 3 dimentions, on which text is displayed.
STARFIELD
Represents a set of randomly-generated stars that move forwards or backwards in 3 dimensions.
TEXTURE_DESC
Represents an image (JPEG, Targa, BMP, PNG, or RGB) displayed in 3 dimensions.
The file api/txf_util.C has support functions from drawing nice-looking 3D text.
Static graphics
An 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.
Graphics in a separate program
In 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.
The main program should initialize using
int boinc_init_options_graphics(BOINC_OPTIONS&, WORKER_FUNC_PTR worker);
The graphics application can be implemented using the BOINC framework, in which case it must initialize with
int boinc_init_options_graphics(BOINC_OPTIONS&, NULL);
and supply rendering and input-handling functions.
Either 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.
[译文]
BOINC程序可以随意的产生图形,这些图形或者在一个程序窗口或者在一个全屏窗口显示(当BOINC的全屏按钮被选中)。
你可以利用OpenGL实现图形。这可以使你的程序在任何平台上显示图形变得容易。
集成图形算法
图形算法既可以集成在主程序中,又可以由一个独立的程序产生。我们推荐使用集成算法,并将首先介绍该用法。在该方法中,一个程序并不调用boinc_init(), 而是调用
#if defined (_WIN32) || defined (__APPLE__)
retval = boinc_init_graphics(worker);
#else
retval = boinc_init_graphics_lib (worker, argv[0]);
#endif
其中worker()是你的程序中的主函数。你的程序必须提供显示和输入处理程序(见下)。
这些函数产生一个worker线程来运行住程序函数。最初的线程变为图形线程,处理GUI事件并显示。
在Unix上,你的图形代码必须放入一个独立的共享库(.so)文件中。这是因为Unix主机不一定有需要的库(OpenGL, GLUT, X11)。如果一个程序动态链接到这些库,若库不存在它不能开始运行。另外,如果一个程序静态链接到这些库,在大多主机上图形处理将非常缓慢。
共享库必须和可执行库具有相同名字的“.so”文件。它必须链接到libboinc_graphics_impl.a,链接到你的显示和输入处理程序,并且要(动态)连接到glut和opengl。你必须将主程序和共享库打包成一个多文件应用程序。由于Unix/Linux图形算法利用多线程技术,因此Unix/Linux程序使用可以用-D_REENTRANT编译所有文件的图形算法。
BOINC示例程序应用这项技术,并且展示了在Unix上产生共享库所需的Makefile命令。
显示和输入处理程序
集成图形算法程序必须提供如下的函数:
void app_graphics_render(int xs, ys, double time_of_day);
该函数将在图形算法线程中被周期调用。该函数将显示当前图形。xs和ys是窗口X轴和Y轴的大小,time_of_day是以秒为单位的相对时间。不执行图形处理的程序也必须提供一个虚app_graphics_render()函数链接到API。
void app_graphics_init();
当一个窗口被创建时调用该函数。它使任何必须的调用在窗口中初始化图形。
void app_graphics_resize(int x, int y);
该函数当窗口大小变化时被调用。
void app_graphics_reread_prefs();
当用户的项目参数发生变化时,图像算法线程调用该函数。它可以调用
boinc_parse_init_data_file();
boinc_get_init_data(APP_INIT_DATA&);
得到新参数。
程序必须提供如下的输入处理函数:
void boinc_app_mouse_move(
int x, int y, // 新鼠标指针坐标
bool left, // 鼠标左键是否按下
bool middle,
bool right
);
void boinc_app_mouse_button(
int x, int y, // 新鼠标指针坐标
int which, //哪一个键(0/1/2)
bool is_down // 如果现在鼠标键按下为真
);
void boinc_app_key_press(
int, int // 某系统键编码
)
void boinc_app_key_release(
int, int //某系统键编码
)
限制帧频率
下面的全局变量控制帧频率:
boinc_max_fps 是每秒帧数的上界(默认30)。
boinc_max_gfx_cpu_frac 是执行图形算法的CPU时间片的上界(默认0.5)。
支撑类
我们为SETI@home开发了一些和图形算法相关的类。他们也许比较通用。
REDUCED_ARRAY
表示一个二维数据向量,这些数据平均或取极值后变成更小的维。该向量包含用不同方法(直线,矩形, 连接面)将简化的数据绘制为3D图形的成员函数。
PROGRESS 和 PROGRESS_2D
表示进度条,用2维或3维描述。
RIBBON_GRAPH
表示单变量函数的3D图形。
MOVING_TEXT_PANEL
表示一个显示文本的凸边3D面板,在3个维度循环移动。
STARFIELD
表示一个在3个维度向前或向后移动的随机产生的星号的集合。
TEXTURE_DESC
表示一个3维显示的图像(JPEG, Targa, BMP, PNG, or RGB)。
文件api/txf_util.C有绘制漂亮的3D文本的支撑函数。
静态图像
一个程序可以显示一个先于图像文件(JPEG, Targa, BMP, PNG, or RGB)而存在的图形。这是最简单的应用,因为你不需要编写任何代码。你必须在每个工作单元中包含图像文件。为了做到这一点,可以把应用程序链接到api/static_graphics.C(用你自己的文件名编辑这个文件)。随着时间的推移,你可以改变这个图像,但你必须每次改变(物理,而不是逻辑)文件名。
单独程序中的图形算法
在这种用法中,一个程序由“主程序”和“图形算法程序”打包而成。主程序执行图形算法程序,并且在每次执行完成后将其吊销。主程序和图形算法程序主要通过共享内存进行通信;你可以利用boinc/lib/shmem.C里的函数实现。
主程序应该利用如下函数初始化:
int boinc_init_options_graphics(BOINC_OPTIONS&, WORKER_FUNC_PTR worker);
图形程序可以利用BOINC框架实现,在此情况下它必须利用如下函数初始化:
int boinc_init_options_graphics(BOINC_OPTIONS&, NULL);
并且提供显示和输入处理程序。
无论是图形程序还是主程序都可以处理来自核心客户端的图形信息。应用图形程序处理这些图形信息最简单;如果由主程序处理,它必须将这些图形信息传递给图形程序。
初学乍练,多多指教。 |
评分
-
查看全部评分
|