Parent Directory
| 
Revision Log
Revision 1098 - (view) (download) (as text)
| 1 : | eile | 742 | #define S_DOCUMENTATION |
| 2 : | #define S_DOCUMENTATION_DEVELOPER | ||
| 3 : | #define PAGE Documentation | ||
| 4 : | #define SUBPAGE Developer | ||
| 5 : | #define TITLE Task Methods | ||
| 6 : | |||
| 7 : | #include "header.shtml" | ||
| 8 : | |||
| 9 : | <p> | ||
| 10 : | eile | 992 | Author: <a href="mailto:[email protected]">[email protected]</a><br/> |
| 11 : | State: Implemented in 0.3 beta | ||
| 12 : | eile | 742 | </p> |
| 13 : | |||
| 14 : | <a href="#overview">Overview</a><br> | ||
| 15 : | <a href="#nodefactory">NodeFactory</a><br> | ||
| 16 : | <a href="#config">Config</a><br> | ||
| 17 : | <a href="#node">Node</a><br> | ||
| 18 : | <a href="#pipe">Pipe</a><br> | ||
| 19 : | <a href="#window">Window</a><br> | ||
| 20 : | <a href="#channel">Channel</a><br> | ||
| 21 : | |||
| 22 : | <hr><a name="overview"></a> | ||
| 23 : | eile | 799 | <h2>Overview</h2> |
| 24 : | eile | 828 | <div class="float_right"> |
| 25 : | <a href="documents/design/images/mainloop.png"> | ||
| 26 : | eile | 883 | <img src="documents/design/images/mainloop-small.jpg" |
| 27 : | eile | 828 | alt="Application and render client main loops"/></a> |
| 28 : | <div class="label">Application and render client main loops</div> | ||
| 29 : | </div> | ||
| 30 : | eile | 742 | <p> |
| 31 : | The application developer overrides methods on Equalizer classes to plug in | ||
| 32 : | eile | 828 | the application's rendering code. The <a href="api.html">programming interface |
| 33 : | overview</a> describes the concept on a high level. This document lists all | ||
| 34 : | currently implemented task methods, their typical use case and default | ||
| 35 : | implementation. Some methods related to the task methods are described as | ||
| 36 : | well. Task methods invoked by Equalizer start with a noun declaring the | ||
| 37 : | context, followed by a verb for the action to implement, | ||
| 38 : | e.g., <code>Channel::frameInit</code>. All other Equalizer methods start with | ||
| 39 : | a verb, e.g., <code>Channel::applyFrustum</code>. The <code>eqPly</code> | ||
| 40 : | example can be used as a reference. | ||
| 41 : | </p> | ||
| 42 : | |||
| 43 : | <hr><a name="nodefactory"></a> | ||
| 44 : | <h2>NodeFactory</h2> | ||
| 45 : | <p> | ||
| 46 : | The <code>NodeFactory</code> is the place where the subclassed Equalizer | ||
| 47 : | objects are created by the application. It consists of virtual methods to | ||
| 48 : | instanciate new instances of all classes mentioned below. The methods in the | ||
| 49 : | base class <code>eq::NodeFactory</code> instanciate base Equalizer | ||
| 50 : | objects, allowing selective subclassing. The node factory is created by the | ||
| 51 : | application and passed to <code>eq::init</code>. | ||
| 52 : | </p> | ||
| 53 : | |||
| 54 : | <hr><a name="config"></a> | ||
| 55 : | <h2>Config</h2> | ||
| 56 : | <p> | ||
| 57 : | The config represents an Equalizer session and controls frame generation. It | ||
| 58 : | is instanciated on the application node | ||
| 59 : | by <code>eq::Server::chooseConfig</code> and on the render nodes | ||
| 60 : | during <code>eq::Config::init</code>. | ||
| 61 : | </p> | ||
| 62 : | |||
| 63 : | eile | 1014 | <a name="configinit"></a> |
| 64 : | eile | 828 | <h3>Config::init</h3> |
| 65 : | <p> | ||
| 66 : | This method is called directly by the application on the application node to | ||
| 67 : | initialize the configuration. The application can override it to update | ||
| 68 : | application-specific data before or after | ||
| 69 : | calling <code>eq::Config::init</code>. | ||
| 70 : | </p> | ||
| 71 : | |||
| 72 : | <h3>Config::exit</h3> | ||
| 73 : | <p> | ||
| 74 : | This method is called directly by the application on the application node to | ||
| 75 : | exit a running configuration. The application can override it to update | ||
| 76 : | application-specific data before or after | ||
| 77 : | calling <code>eq::Config::exit</code>. | ||
| 78 : | </p> | ||
| 79 : | |||
| 80 : | eile | 1014 | <a name="configstartframe"></a> |
| 81 : | eile | 828 | <h3>Config::startFrame</h3> |
| 82 : | <p> | ||
| 83 : | This method is called directly by the application on the application node to | ||
| 84 : | request a new frame to be rendered. The application can override it to update | ||
| 85 : | frame-specific data before or after | ||
| 86 : | calling <code>eq::Config::startFrame</code>. | ||
| 87 : | </p> | ||
| 88 : | |||
| 89 : | eile | 1014 | <a name="configfinishframe"></a> |
| 90 : | eile | 828 | <h3>Config::finishFrame</h3> |
| 91 : | <p> | ||
| 92 : | This method is called directly by the application on the application node to | ||
| 93 : | request a frame to be finished. The frame finished can be older than the last | ||
| 94 : | frame started, depending on the config's latency. The application can override | ||
| 95 : | it to update frame-specific data before or after | ||
| 96 : | calling <code>eq::Config::finishFrame</code>. | ||
| 97 : | </p> | ||
| 98 : | |||
| 99 : | <h3>Config::finishAllFrames</h3> | ||
| 100 : | <p> | ||
| 101 : | This method is called directly by the application on the application node to | ||
| 102 : | finish all started frames. The application can override it to update | ||
| 103 : | frame-specific data before or after | ||
| 104 : | calling <code>eq::Config::finishAllFrames</code>. | ||
| 105 : | </p> | ||
| 106 : | |||
| 107 : | <h3>Config::handleEvents</h3> | ||
| 108 : | <p> | ||
| 109 : | This method is called on the application node from | ||
| 110 : | within <code>Config::finishFrame</code> to process all pending events. Its | ||
| 111 : | purpose is to implement custom event handling, for example event-driven | ||
| 112 : | execution. The default implementation does not block and calls | ||
| 113 : | <code>Config::handleEvent</code> for each queued event. See also | ||
| 114 : | <a href="documents/design/eventHandling.html">Event Handling</a>. | ||
| 115 : | </p> | ||
| 116 : | |||
| 117 : | eile | 1014 | <a name="confighandleevent"></a> |
| 118 : | eile | 828 | <h3>Config::handleEvent</h3> |
| 119 : | <p> | ||
| 120 : | This method is called by <code>Config::handleEvents</code> to process a single | ||
| 121 : | event. Its purpose is to update the application's state depending on the | ||
| 122 : | received event. The default implementation does nothing. | ||
| 123 : | </p> | ||
| 124 : | |||
| 125 : | <hr><a name="node"></a> | ||
| 126 : | <h2>Node</h2> | ||
| 127 : | <p> | ||
| 128 : | The node represent a single machine in the cluster. It is instanciated on the | ||
| 129 : | render clients during <code>Config::init</code>. | ||
| 130 : | </p> | ||
| 131 : | |||
| 132 : | <a name="nodeinit"></a> | ||
| 133 : | <h3>Node::configInit</h3> | ||
| 134 : | <p> | ||
| 135 : | This method is called during <code>Config::init</code> on the render | ||
| 136 : | clients. Its purpose is to initialize node-specific application data. It is | ||
| 137 : | called in the node's main thread. The default implementation does nothing. A | ||
| 138 : | return value of <code>false</code> causes the config initialization to fail. | ||
| 139 : | </p> | ||
| 140 : | |||
| 141 : | <h3>Node::configExit</h3> | ||
| 142 : | <p> | ||
| 143 : | This method is called during <code>Config::exit</code> on the render | ||
| 144 : | clients. Its purpose is to de-initialize node-specific application data. It is | ||
| 145 : | called in the node's main thread. The default implementation does nothing. A | ||
| 146 : | return value of <code>false</code> causes the config exit to fail. | ||
| 147 : | </p> | ||
| 148 : | |||
| 149 : | <h3>Node::frameStart</h3> | ||
| 150 : | <p> | ||
| 151 : | This method is the first method called for a given frame on the node. Its | ||
| 152 : | purpose is to update all frame-specific per-node data, and to unlock all | ||
| 153 : | resources underneath the node by calling <code>Node::startFrame</code>. The | ||
| 154 : | default implementation calls <code>Node::startFrame</code>. | ||
| 155 : | </p> | ||
| 156 : | |||
| 157 : | <h3>Node::frameFinish</h3> | ||
| 158 : | <p> | ||
| 159 : | This method is the last method called for a given frame in the node | ||
| 160 : | thread. Its purpose is to update frame-specific data after a frame has been | ||
| 161 : | finished rendering, and to unlock the parent by | ||
| 162 : | eile | 838 | calling <code>Node::releaseFrame</code>. The frame finishing can be older than the |
| 163 : | eile | 828 | last frame started, depending on the config's latency. The default |
| 164 : | eile | 838 | implementation calls <code>Node::releaseFrame</code>. |
| 165 : | eile | 828 | </p> |
| 166 : | |||
| 167 : | <hr><a name="pipe"></a> | ||
| 168 : | <h2>Pipe</h2> | ||
| 169 : | <p> | ||
| 170 : | The pipe represents a graphic card. It is instanciated | ||
| 171 : | during <code>Config::init</code> on the render nodes. All pipe, window and | ||
| 172 : | channel task methods are currently called from the pipe thread. | ||
| 173 : | </p> | ||
| 174 : | |||
| 175 : | <h3>Pipe::configInit</h3> | ||
| 176 : | <p> | ||
| 177 : | This method is called during <code>Config::init</code> on the render | ||
| 178 : | clients. Its purpose is to initialize pipe-specific application data and the | ||
| 179 : | handle to the graphic card, if applicable for the current window system. The | ||
| 180 : | default implementation calls a windows-system specific task method, | ||
| 181 : | e.g. <code>configInitGLX</code>, which initializes the handle to the graphic | ||
| 182 : | card. The application typically allocates a renderer and other | ||
| 183 : | rendering-specific data for each pipe, since each pipe runs in a separate | ||
| 184 : | thread. A return value of <code>false</code> causes the config initialization | ||
| 185 : | to fail. | ||
| 186 : | </p> | ||
| 187 : | |||
| 188 : | <h3>Pipe::configExit</h3> | ||
| 189 : | <p> | ||
| 190 : | This method is called during <code>Config::exit</code> on the render | ||
| 191 : | clients. Its purpose is to de-initialize pipe-specific application data and | ||
| 192 : | the handle to the graphic card, if applicable. The default implementation | ||
| 193 : | calls a window-system specific task method, e.g. <code>configExitGLX</code>, | ||
| 194 : | which closes the handle to the graphic card. A return value | ||
| 195 : | of <code>false</code> causes the config exit to fail. | ||
| 196 : | </p> | ||
| 197 : | |||
| 198 : | <a name="pipestartframe"></a> | ||
| 199 : | <h3>Pipe::frameStart</h3> | ||
| 200 : | <p> | ||
| 201 : | This method is the first method called for a given frame in the pipe | ||
| 202 : | thread. Its purpose is to update all frame-specific data to the version | ||
| 203 : | corresponding to the started frame, and to unlock all resources underneath the | ||
| 204 : | pipe by calling <code>Pipe::startFrame</code>. The default implementation | ||
| 205 : | calls <code>Pipe::startFrame</code>. | ||
| 206 : | </p> | ||
| 207 : | |||
| 208 : | <h3>Pipe::frameFinish</h3> | ||
| 209 : | <p> | ||
| 210 : | This method is the last method called for a given frame in the pipe | ||
| 211 : | thread. Its purpose is to update frame-specific data after a frame has been | ||
| 212 : | finished rendering, and to unlock the parent by | ||
| 213 : | eile | 838 | calling <code>Pipe::releaseFrame</code>. The default implementation |
| 214 : | calls <code>Pipe::releaseFrame</code>. | ||
| 215 : | eile | 828 | </p> |
| 216 : | |||
| 217 : | <hr><a name="window"></a> | ||
| 218 : | <h2>Window</h2> | ||
| 219 : | <p> | ||
| 220 : | The window represents an OpenGL drawable. It is instanciated | ||
| 221 : | during <code>Config::init</code> on the render nodes. All window and | ||
| 222 : | channel task methods are called from the pipe thread, with the exception of | ||
| 223 : | <code>processEvent</code>, which might be called from a separate event thread. | ||
| 224 : | </p> | ||
| 225 : | |||
| 226 : | <a name="windowinit"></a> | ||
| 227 : | <h3>Window::configInit</h3> | ||
| 228 : | <p> | ||
| 229 : | This method is called during <code>Config::init</code> on the render | ||
| 230 : | clients. Its purpose is to initialize an OpenGL drawable and context, to setup | ||
| 231 : | the OpenGL state, as well as to initialize window-specific application | ||
| 232 : | data. The default implementation calls a windows-system specific task method, | ||
| 233 : | e.g. <code>configInitGLX</code>, which creates a drawable and context | ||
| 234 : | according to the window's attributes, and then calls <code>configInitGL</code> | ||
| 235 : | if the context creation was successful. A return value of <code>false</code> | ||
| 236 : | causes the config initialization to fail. | ||
| 237 : | </p> | ||
| 238 : | |||
| 239 : | <h3>Window::configExit</h3> | ||
| 240 : | <p> | ||
| 241 : | This method is called during <code>Config::exit</code> on the render | ||
| 242 : | clients. Its purpose is to destroy the OpenGL context and drawable, as wall as | ||
| 243 : | to de-initialize window-specific application data. The default implementation | ||
| 244 : | calls a windows-system specific task method, e.g. <code>configExitGLX</code>, | ||
| 245 : | which destroyes the context and drawable. A return value of <code>false</code> | ||
| 246 : | causes the config exit to fail. | ||
| 247 : | </p> | ||
| 248 : | |||
| 249 : | <h3>Window::frameStart</h3> | ||
| 250 : | <p> | ||
| 251 : | This method is the first window task method called for a given frame. Its | ||
| 252 : | purpose is to update all frame-specific data for this window, and to unlock | ||
| 253 : | the resources underneath by calling <code>Window::startFrame</code>. The | ||
| 254 : | default implementation calls <code>Window::startFrame</code>. | ||
| 255 : | </p> | ||
| 256 : | |||
| 257 : | <h3>Window::frameFinish</h3> | ||
| 258 : | <p> | ||
| 259 : | This method is the last method called for a given frame in the window | ||
| 260 : | thread. Its purpose is to update frame-specific data after the window has | ||
| 261 : | finished rendering a frame, and to unlock its parent by | ||
| 262 : | eile | 838 | calling <code>Window::releaseFrame</code>. The default implementation |
| 263 : | calls <code>Window::releaseFrame</code>. | ||
| 264 : | eile | 828 | </p> |
| 265 : | |||
| 266 : | <h3>Window::makeCurrent</h3> | ||
| 267 : | <p> | ||
| 268 : | Makes the OpenGL context for the window current. The default implementation | ||
| 269 : | calls a window-specific method to attach the OpenGL context, e.g., | ||
| 270 : | <code>glXMakeCurrent</code>. | ||
| 271 : | </p> | ||
| 272 : | |||
| 273 : | eile | 1014 | <a name="windowswap"></a> |
| 274 : | eile | 828 | <h3>Window::swapBuffers</h3> |
| 275 : | <p> | ||
| 276 : | Swap the back and front rendering buffer. The default implementation | ||
| 277 : | calls a window-specific method to swap the buffers, e.g., | ||
| 278 : | <code>glXSwapBuffers</code>. | ||
| 279 : | </p> | ||
| 280 : | |||
| 281 : | <h3>Window::finish</h3> | ||
| 282 : | <p> | ||
| 283 : | Complete the rendering of all OpenGL commands. The purpose of this method is to | ||
| 284 : | ensure that the rendering has been finished, for example to ensure a | ||
| 285 : | simultaneous buffer swap of multiple windows. The default implementation | ||
| 286 : | calls a <code>glFinish</code>. | ||
| 287 : | </p> | ||
| 288 : | |||
| 289 : | eile | 1014 | <a name="windowprocessevent"></a> |
| 290 : | eile | 828 | <h3>Window::processEvent</h3> |
| 291 : | <p> | ||
| 292 : | Process a single event received by this window. The default implementation | ||
| 293 : | either processes the event locally or converts it to | ||
| 294 : | a <code>ConfigEvent</code>, which is send application thread by | ||
| 295 : | using <code>Config::sendEvent</code>. This method may be called from the | ||
| 296 : | window thread or from a seperate event thread, depending on the window system. | ||
| 297 : | </p> | ||
| 298 : | |||
| 299 : | |||
| 300 : | <hr><a name="channel"></a> | ||
| 301 : | <h2>Channel</h2> | ||
| 302 : | <p> | ||
| 303 : | The channel is a viewport in a window. It executes the rendering tasks. All | ||
| 304 : | channel methods are called from the pipe thread. The channel rendering methods | ||
| 305 : | are given contextual information which are to be used during rendering, either | ||
| 306 : | by using the convenience apply functions, e.g., <code>applyViewport</code>, or | ||
| 307 : | by getting the values and calling the appropriate OpenGL functions. | ||
| 308 : | </p> | ||
| 309 : | |||
| 310 : | <h3>Channel::configInit</h3> | ||
| 311 : | <p> | ||
| 312 : | This method is called during <code>Config::init</code> on the render | ||
| 313 : | clients. Its purpose is to initialize channel-specific application data. The | ||
| 314 : | default implementation is empty. A return value of <code>false</code> causes | ||
| 315 : | the config initialization to fail. | ||
| 316 : | </p> | ||
| 317 : | |||
| 318 : | <h3>Channel::configExit</h3> | ||
| 319 : | <p> | ||
| 320 : | This method is called during <code>Config::exit</code> on the render | ||
| 321 : | clients. Its purpose is to de-initialize channel-specific application | ||
| 322 : | data. The default implementation is empty. A return value | ||
| 323 : | of <code>false</code> causes the config exit to fail. | ||
| 324 : | </p> | ||
| 325 : | |||
| 326 : | <h3>Channel::frameStart</h3> | ||
| 327 : | <p> | ||
| 328 : | This method is the first channel task method called for a given frame. Its | ||
| 329 : | purpose is to unlock the resources underneath by | ||
| 330 : | calling <code>Channel::startFrame</code>. The default implementation | ||
| 331 : | calls <code>Channel::startFrame</code>. | ||
| 332 : | </p> | ||
| 333 : | |||
| 334 : | <h3>Channel::frameFinish</h3> | ||
| 335 : | <p> | ||
| 336 : | This method is the last method called for a given frame in the channel | ||
| 337 : | thread. Its purpose is to update frame-specific data after the channel has | ||
| 338 : | finished rendering a frame, and to unlock its parent by | ||
| 339 : | eile | 838 | calling <code>Channel::releaseFrame</code>. The default implementation |
| 340 : | calls <code>Channel::releaseFrame</code>. | ||
| 341 : | eile | 828 | </p> |
| 342 : | |||
| 343 : | eile | 1014 | <a name="channelclear"></a> |
| 344 : | eile | 828 | <h3>Channel::frameClear</h3> |
| 345 : | <p> | ||
| 346 : | Clear the frame buffer. The function has to use the provided draw buffer | ||
| 347 : | (see <code>getBuffer</code>) and viewport (see <code>getViewport</code>). The | ||
| 348 : | default method applies the draw buffer and viewport and clears the color and | ||
| 349 : | depth buffer. | ||
| 350 : | </p> | ||
| 351 : | |||
| 352 : | <a name="channeldraw"></a> | ||
| 353 : | <h3>Channel::frameDraw</h3> | ||
| 354 : | <p> | ||
| 355 : | Render the scene. The function has to use the provided draw buffer | ||
| 356 : | (see <code>getBuffer</code>), viewport (see <code>getViewport</code>), frustum | ||
| 357 : | (see <code>getFrustum</code>, head transformation | ||
| 358 : | (see <code>getHeadTransform</code>) and range for sort-last rendering | ||
| 359 : | (see <code>getRange</code>). The default implementation applies the buffer, | ||
| 360 : | viewport, frustum and head transform and draw a quad. | ||
| 361 : | </p> | ||
| 362 : | |||
| 363 : | <h3>Channel::frameAssemble</h3> | ||
| 364 : | <p> | ||
| 365 : | Assemble all provided input frames. The function has to use the provided draw | ||
| 366 : | buffer (see <code>getBuffer</code>), viewport (see <code>getViewport</code>) | ||
| 367 : | and input frames (see <code>getInputFrames</code>). The default method applies | ||
| 368 : | the draw buffer and viewport, calls <code>setupAssemblyState</code>, assembles | ||
| 369 : | the input frames using <code>glDrawPixels</code> and | ||
| 370 : | calls <code>resetAssemblyState</code>. If the input frame has depth | ||
| 371 : | information, it is z-composited using the stencil buffer with the information | ||
| 372 : | in the channel's frame buffer. The frames are assembled in an arbitrary order | ||
| 373 : | as they become available. | ||
| 374 : | </p> | ||
| 375 : | |||
| 376 : | <h3>Channel::frameReadback</h3> | ||
| 377 : | <p> | ||
| 378 : | Readback the frame buffer. The function has to use the provided draw buffer | ||
| 379 : | (see <code>getBuffer</code>), viewport (see <code>getViewport</code>) and | ||
| 380 : | output frames (see <code>getOutputFrames</code>). The output frames specify | ||
| 381 : | the frame buffer attachments (color, depth) to read back. The default method | ||
| 382 : | applies the draw buffer and viewport, calls <code>setupAssemblyState</code>, | ||
| 383 : | reads back the output frames using <code>glReadPixels</code> and | ||
| 384 : | calls <code>resetAssemblyState</code>. | ||
| 385 : | </p> | ||
| 386 : | |||
| 387 : | <h3>Channel::setupAssemblyState</h3> | ||
| 388 : | <p> | ||
| 389 : | Setup the OpenGL state for a readback or assemble operation. The default | ||
| 390 : | implementation is very conservative and saves any state which is potentially | ||
| 391 : | changed by the assembly routines. This method is always called in conjunction | ||
| 392 : | with a later <code>resetAssemblyState</code>. | ||
| 393 : | </p> | ||
| 394 : | |||
| 395 : | <h3>Channel::resetAssemblyState</h3> | ||
| 396 : | <p> | ||
| 397 : | Reset the OpenGL state after an assembly operation. | ||
| 398 : | </p> | ||
| 399 : | |||
| 400 : | eile | 742 | #include "footer.shtml" |
| 401 : | <!-- $Id$ --> |
| Back to Equalizer website | ViewVC Help |
| Powered by ViewVC 1.0.3 |