Lightworks Author 9.0
Lightworks Real-time Lightworks Real-time
Master Doc
Title Page
Contents
First Last
J I
Page1 of 119
Go Back
Part No: D195-800-1409 Search This Doc February 27, 2014 Search All Docs
Full Screen Copyright of Lightwork Design Ltd. 2013. All Rights Reserved.
Reproduction of any part of this document in any form may only be undertaken with the written permission of Lightwork Design Ltd.
Lightwork Design Ltd. reserves the right to make changes in specifications at any time and without notice. The information furnished by Lightwork Design Ltd. in this publication is believed to be accurate; however, no responsibility is assumed for its use, nor for any infringement of patents or other rights of third parties resulting from its use. Lightworks Author 9.0 Lightworks, the Lightworks logo, LWA and LWA-Enabled are registered trademarks of Lightwork Design Ltd. The LWA-Enabled logo, Interactive Image Regeneration, IIR, A-Cubed, Feature-Following Anti-Aliasing and FFAA are all trademarks of Lightwork Design Ltd. All other trademarks, images and logos remain the property Lightworks of their respective owners. Real-time
Credits
Master Doc
Title Page
Contents
First Last
Lightwork Design Rutledge House J I 78 Clarkehouse Road Sheffield S10 2LJ Page2 of 119 United Kingdom
Tel. (0114) 266 8404 UK +44 114 266 8404 International Go Back Fax (0114) 266 1383 +44 114 266 1383 Search This Doc Electronic mail: [email protected] Search All Docs World Wide Web: (General) http://www.lightworkdesign.com (Support) http://www.lightworkdesign.com/support.html Full Screen
Title: Credits Type: Lightworks Real-time Ref: D131-210-3894 Doc date: 14 Sep 94 Generated: at 15:18 RCS info: $Source: /home/docs/lads/credits/RCS/credits.tex,v $Author: simon $Date: 2013/05/31 Contents Lightworks Author 9.0
Lightworks I Overview6 Real-time
1 Lightworks Real-time 7 1.1 Benefits...... 10 Contents II Concepts 11
2 Introduction 12 2.1 About Lightworks Real-time Plus...... 13 2.2 Initialisation...... 13 2.2.1 Win32...... 14 Master Doc 2.2.2 Macintosh...... 14 2.3 About this manual...... 14 Title Page
III Programming Guide—GUI Framework 15 Contents 3 Using Real-time Rendering via the Framework Library 16 First Last IV Programming Guide—Session Manager 17 4 Using Real-time Rendering via the Session Manager 18 J I 4.1 Rendering...... 18 Page3 of 119 V Programming Guide—Core 20
5 Using Real-time Rendering via the Core-Lightworks API 21 Go Back 5.0.1 Macintosh-Specific Initialisation...... 22 5.1 Performing rendering...... 23 5.1.1 Rendering using render styles...... 24 Search This Doc 5.1.2 The scene level API...... 25 5.1.3 Object level API...... 26 Search All Docs 5.1.3.1 Multi-pass rendering...... 28 5.1.3.2 Advanced multi-pass rendering...... 29 5.1.4 Primitive level API...... 32 Full Screen 5.2 Telling liopengl when material or primitive information has changed...... 33 5.2.1 Invalidation of geometry...... 33 5.2.1.1 All geometry...... 33 5.2.1.2 Individual primitives...... 34 5.2.2 Invalidation of materials...... 35 5.2.3 Invalidation of shaders...... 36 5.2.4 Light Group support...... 37 5.2.5 Generalised Invalidation...... 37 5.3 Querying Lightworks Real-time specific information...... 38 Lightworks Author 5.4 Windows API...... 40 5.4.1 Win32 (Wgl)...... 40 9.0
6 Advanced usage 42 Lightworks 6.1 OpenGL shadows...... 42 Real-time 6.1.1 Shadow resolution...... 43 6.1.2 Shadow depth...... 44 6.1.3 Soft shadows...... 44 6.1.4 OpenGL shadow limitations...... 46 6.2 Annotation support...... 46 Contents 6.3 Procedural rendering...... 47 6.3.1 OpenGL primitive rendering function...... 48 6.3.2 Invalidate primitive cached state function...... 49 6.3.3 Primitive destroy function...... 51 6.3.4 Vertex property flags inquiry function...... 51 Master Doc 6.3.5 Procedural rendering context...... 52 6.4 Environment Mapping in Real-time...... 57 6.4.1 Material Reflectance...... 57 Title Page 6.4.1.1 Non-programmable shading...... 57 6.4.1.2 Programmable Shading...... 58 6.4.2 Backgrounds...... 58 Contents 6.4.3 Lighting...... 58 6.5 User Defined Clipping Planes...... 60 6.6 User Defined Line Types...... 61 First Last 6.7 Hidden Line Rendering...... 61 6.8 Anti-aliasing...... 62 6.9 Gamma Correction...... 62 J I 6.10 Accessing OpenGL extensions...... 62 6.11 Mixing liopengl and OpenGL API calls...... 63 6.12 Screen Space Ambient Occlusion...... 64 Page4 of 119 6.12.1 SSAO Requirements...... 64 6.12.2 Using SSAO...... 64 6.12.3 Caveats...... 66 Go Back 6.13 Stereoscopic Rendering...... 66 6.13.1 Stereo Requirements...... 66 Search This Doc 6.13.2 Using Stereo...... 66 6.13.2.1 View manipulation in stereo rendering...... 68 6.13.2.2 Display of stereo images...... 69 Search All Docs 6.13.3 Controlling the Stereo Effect...... 69 6.13.4 Caveats...... 70 Full Screen 7 Using Lightworks materials with your own interactive rendering (via the Material API) 71 7.1 Creating an OpenGL material from a Lightworks material...... 72 7.2 Querying an OpenGL Material...... 72 7.3 Using an OpenGL Material definition...... 73 7.4 Invalidating materials...... 74 7.5 Blended materials...... 76 7.6 Invalidating the OpenGL state...... 76
8 Programmable shading 80 8.1 Current restrictions...... 81 Lightworks Author 8.2 Environment reflections in Real-time...... 81 9.0 8.3 Decals in programmable shading...... 82 8.4 Lights in programmable shading...... 83 Lightworks 8.5 Shaders supported by programmable shading real-time hardware...... 83 Real-time
9 CgFX Support 85 9.1 Semantics and Annotations...... 85 9.2 Texture Annotations...... 87 9.3 ShadowMap Semantics...... 87 Contents 9.4 Editing CgFX Parameters...... 89 9.5 Resource Loading/Unloading...... 91
10 Control Variables for Real-time 92 10.1 Context variables...... 92 10.2 Geometry variables...... 93 Master Doc 10.3 Material variables...... 95 10.4 Render variables...... 96 Title Page
VI Appendix 106 Contents A Notes 107 A.1 Features...... 107 A.2 OpenGL Limitations...... 108 First Last A.3 Usage of Geometry Data...... 110 A.3.1 Data caching...... 110 A.3.2 Geometry expansion...... 111 J I A.3.3 Incremental update of geometry...... 111 A.3.4 Presentation of geometry for Real-time Plus...... 111 Page5 of 119 A.4 Known Problems...... 111 A.5 OpenGL Compatibility...... 112 A.6 Tested Configurations...... 112 Go Back A.7 System Requirements...... 114
Index 115 Search This Doc
Search All Docs
Full Screen Lightworks Author 9.0
Lightworks Real-time
Part I
Overview Master Doc
Title Page
Contents
First Last
J I
Page6 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 1 Lightworks Author 9.0
Lightworks Lightworks Real-time Real-time
Lightworks Real-time
Master Doc Lightworks Real-time offers hardware assisted rendering of the Lightworks scene for interactive navigation and scene editing. Title Page
Contents
First Last
J I
Page7 of 119
Go Back
Search This Doc
Search All Docs
Figure 1.1: Materials and lighting in real time Full Screen Lightworks Real-time is designed to make the best possible use of the available graphics hardware, Lightworks Author 9.0
Lightworks Real-time
Lightworks Real-time
Figure 1.2: Environments and reflections in real time Master Doc producing images which are as close to a full Lightworks software renderer as it is possible to achieve using any given graphics card. For example, the new generation of graphics cards support Title Page real-time procedural textures, and Lightworks Real-time supports these by using specially written real-time versions of the regular Lightworks software shaders. Where such advanced hardware is not available, Lightworks Real-time instead pre-calculates a suitable texture map based on the Contents Lightworks software shader, and uses that for real-time rendering.
The result is that Lightworks Real-time allows real-time rendering which is as close as it is possible First Last to get to full Lightworks software rendering quality using any given graphics hardware, without any need for users to alter materials, lights, or other scene data. J I If you already have your own OpenGL rendering solution in place, Lightworks Real-time enables you to access Lightworks materials for OpenGL use so that your interactive rendering will match Lightworks rendering as closely as the hardware will allow. Page8 of 119
Lightworks Real-time goes beyond direct use of low-level hardware APIs, by producing significantly Go Back higher quality images using multi-pass techniques at interactive rates, including real-world light intensities, shadows, self- shadowing, and an unlimited number of lights. Adding Lightworks Real- time to an existing Real-time OpenGL-based framework is very easy. Just three function calls for Search This Doc an application that already uses Lightworks and just a few more for an application which does not. Lightworks Real-time can be integrated either as a complete Real-time rendering framework or as a high-quality Real-time procedural shading add-on to the application’s own Real-time core rendering Search All Docs framework, to be used during the modelling process.
Lightworks Real-time is the easiest and most effective way to exploit the increasing rendering power Full Screen of modern graphics cards. The following features are supported by Lightworks Real-time in conjunction with the Foundation product:
• High quality hardware assisted interactive rendering.
• Flat colour, smooth colour, textured, wireframe and hidden line render modes. Lightworks Author • Shaded and vector (wireframe or hidden line) can be overlaid. 9.0 • Geometry edge rendering for highlighting selected geometry. Lightworks • Shadows from spot and distant light sources, including curved surfaces and self shadowing. Real-time • Incremental scene updates and control of render modes for specific objects. • Lightworks Real-time can support any number of light sources, up to the limit of the OpenGL card being used. Lightworks Real-time • Intensity values greater than 1.0 can be supported (albeit without hardware acceleration).
• Backgrounds including plain colour, graduated, clouds, environment, and images. • Support for environment reflection mapping (all OpenGL cards will support environment maps in the ‘spherical’ form, and most modern cards also support the ‘cubic’, ‘panorama’ and Master Doc ‘angular’ forms of environment map).
• High quality sorted and blended transparency. Title Page • Full texture space support.
• Range of controls for optimal performance and quality. Contents • Lightworks Real-time also provides access to Lightworks materials for use in other OpenGL renderers, allowing you to make use of Lightworks programmable shaders directly in your own First Last OpenGL rendering.
The following features are supported by Lightworks Real-time in conjunction with other Lightworks J I products: Page9 of 119 • Emulation of Lightworks solid and wrapped procedural colour shaders.
• Support for physical lighting models (lumens/candela). Go Back • Support for pre-lighting of the scene using radiosity processing. Search This Doc • Support for decals. • Support for RPC. Search All Docs • Support for environment lighting effects.
Full Screen Please note that Lightworks Real-time is currently available for Windows and Macintosh only. 1.1. Benefits
Lightworks Real-time provides the following benefits over producing your own OpenGL 2.0 or Cg solution:
• The power of the Lightworks shading infrastructure and the Lightworks shader writing tools. Lightworks Author 9.0 • The packaging and distribution inside the LWA format of Lightworks shaders that run on Cg and OpenGL 2.0. Lightworks • Cg and OpenGL 2.0 shading integrated into Lightworks. Real-time
• A smooth path for users to switch back-and-forth between hardware and software rendering. • Physically accurate rendering of real-world materials (provided by the LWA format). Lightworks Real-time • A practical toolkit for the integration of hardware rendering into CAD applications.
By rendering materials, effects and lighting not supported by low-level hardware APIs, Lightworks Real-time produces significantly higher quality images than can be produced by the direct use of OpenGL or Direct3D. Master Doc
Title Page
Contents
First Last
J I
Page 10 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Lightworks Author 9.0
Lightworks Real-time
Part II
Concepts Master Doc
Title Page
Contents
First Last
J I
Page 11 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 2 Lightworks Author 9.0
Lightworks Introduction Real-time
Introduction
Master Doc Lightworks Real-time and Lightworks Real-time Plus are optional add-ons for Lightworks which allow you to add interactive rendering to your Lightworks-enhanced product. Title Page • Lightworks Real-time With only three extra API calls, an existing Lightworks-based application can provide OpenGL Contents rendering of Lightworks geometry, lighting and materials. This enables you to provide your users with an interactive display mode for scene navigation, for example. Lightworks Real-time also provides access to Lightworks materials (via the Material API) for use First Last in other OpenGL renderers, allowing you to make use of Lightworks programmable shaders directly in your own OpenGL rendering. • Lightworks Real-time Plus J I Extremely large scenes can be slow to render, even when using hardware assisted OpenGL rendering. By rendering geometry according to its visual importance, Real-time Plus can Page 12 of 119 provide interactive rendering of very large models at guaranteed frame rates. The most visually-important geometry is rendered first, then the next most important, and so on, until the time available for rendering each frame runs out. Go Back
These two products therefore allow you to provide interactive OpenGL rendering which uses Search This Doc Lightworks lighting and materials information. This means that the interactive rendering will be representative of the final image to be rendered by Lightworks. Search All Docs The rest of this manual is concerned mainly with Lightworks Real-time only—Lightworks Real-time Plus is described in the Lightworks Real-time Plus manual. Full Screen Please note that you should complete your integration of Lightworks Real-time before beginning work on Lightworks Real-time Plus. 2.1. About Lightworks Real-time Plus
Even with hardware accelerated OpenGL rendering, extremely large models will cause a reduced frame-rate, simply because of the amount of geometry data. There is some evidence to suggest that, even though computing speed is constantly increasing, users’ expectations (in terms of the size of models being produced) are rising even faster. Lightworks Author Real-time Plus sorts geometry in the scene according to the visual impact each element will have. 9.0 The most visually important geometry is rendered first, followed by the next most visually important, and so on. When the renderer runs out of time for rendering a given frame, it stops and begins Lightworks rendering the next frame. Real-time
In this way a guaranteed frame rate can be provided for interactive rendering—small objects far away may not get rendered whilst the user is ‘flying’ through the model, but it is not important to the user that they are. Once the user stops interacting, all the geometry will be rendered. Introduction
2.2. Initialisation
Master Doc The Lightworks Real-time (OpenGL) Renderer is supplied as two modules, liopengl and liogldrv. Real-time Plus is supplied as a further module, lirtplus. Title Page The API is declared through the inclusion of:
Contents #include
... Page 13 of 119
LiInstallModule(LiEntryOGLDrv); // Real-time Go Back LiInstallModule(LiEntryOpenGL); // Real-time LiInstallModule(LiEntryRTPlus); // Real-time Plus Search This Doc ...
LiSystemStart(); Search All Docs If you have written your own version of LiInitialise, you can insert these LiInstallModule calls after all other Lightworks modules are installed. Note that Session Manager libraries, if Full Screen appropriate, should be initialised after the Real-time libraries. You should add the libraries liopengl.lib and liogldrv.lib, (and lirtplus.lib, if appli- cable), to your application’s link line, together with your system’s OpenGL libraries as identified below.
2.2.1. Win32 Lightworks Author Link with glu32.lib and opengl32.lib. These libraries and their accompanying run time DLLs 9.0 are installed as standard on Windows. For versions pre-Windows 95 OSR2, Microsoft has made redistributable versions of the OpenGL DLLs available. They can be found at the following ftp site: Lightworks Real-time
ftp://ftp.microsoft.com/softlib/mslfiles/opengl95.exe
Introduction 2.2.2. Macintosh
Unless you use your own screen driver, the Lightworks Macintosh driver lidrvcca is required for 64-bit Macintosh builds: macintel64/osx/gcc4. Currently, this driver is incompatible with Lightworks Real-time—it relies on AGL to provide OpenGL functionality, which is incompatible with Master Doc Cocoa.
Title Page 2.3. About this manual Contents
Sections3,4 and5 explain how to add Real-time OpenGL rendering to your application, for users of the Framework Library, Session Manager, and core Lightworks APIs respectively. First Last
Users of the Real-time Plus product should be sure to read and understand the relevant Real-time rendering material before going to on to read the Real-time Plus material. J I
Finally, SectionA contains notes that users of both Real-time and Real-time Plus should be aware of, for example the graphics cards that have been tested, how limitations of OpenGL rendering may Page 14 of 119 affect how you wish to present geometry, and so on.
Go Back
Search This Doc
Search All Docs
Full Screen Lightworks Author 9.0
Lightworks Real-time
Part III
Programming Guide—GUI Framework Master Doc
Title Page
Contents
First Last
J I
Page 15 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 3 Lightworks Author 9.0
Lightworks Using Real-time Rendering via the Real-time Framework Library Using Real-time Rendering via the Framework Library
Master Doc
This section explains what steps need to be taken to integrate Real-time rendering if you are using Title Page the GUI Framework interface to Lightworks.
The Framework Library provides the preview widget class LcWidgetPreview, which handles all Contents interactive rendering automatically. By default, the session-view’s interactive method of rendering is used (each preview widget has a session-view). See Section4. Interactive mode is used for First Last rendering during a mouse operation which alters the viewpoint (e.g., left-click and drag to perform an orbit operation).
You must remember to enable the preview widget’s interactive rendering mode by using the function J I LcWidgetPreview::EnableActiveUpdate (see the on-line Framework API reference for details). Page 16 of 119 Interactive mode can also be used for ‘update’ renders (for example in response to material or lighting changes) as an alternative to using standard Lightworks or IIR rendering. Go Back
Search This Doc
Search All Docs
Full Screen Lightworks Author 9.0
Lightworks Real-time
Part IV
Programming Guide—Session Manager Master Doc
Title Page
Contents
First Last
J I
Page 17 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 4 Lightworks Author 9.0
Lightworks Using Real-time Rendering via the Real-time Session Manager Using Real-time Rendering via the Session Manager
Master Doc
This section explains what steps need to be taken to integrate Real-time rendering if you are using Title Page the Session Manager interface to Lightworks. Contents By using the Session Manager API, rather than the core API, much of the work is handled for you. In essence, both the ‘object’ and ‘primitive’ levels of API discussed in Section5 of this manual are handled automatically. First Last This means that it is quite a straightforward job to add interactive rendering to your application if you use the Session Manager. The default behaviour can be over-ridden to a certain extent, but note that if you want fine control over every aspect of the behaviour of your interactive rendering then you J I should probably investigate using the core API for your integration instead. Page 18 of 119
4.1. Rendering Go Back
The Session Manager needs to be told to use an OpenGL-based render style for the render methods Search This Doc which require it. Typically this will be the ‘active’ method, but it could be any or all of the rendering methods. For the ‘active’ method, this is achieved by setting the control variable LI_SESSION_- VIEW_VAR_ACTIVE_STYLE for the relevant session-view. This should be set to a render style entity Search All Docs which wraps up a render style of type "real time shaded" or "real time vector".
For example, for a "real time shaded" render style; Full Screen LtData data; LtEntity style_entity;
style_entity = LiEntityCreateRenderStyle( "real time", (LtInterface)LI_RENDER_STYLE_REAL_TIME_SHADED );
LiDataSetEntity( &data, style_entity ); Lightworks Author LiSessionViewSetVariable( my_session_view, 9.0 LI_SESSION_VIEW_VAR_ACTIVE_STYLE, &data ); Lightworks Real-time Note that the constant LI_RENDER_STYLE_REAL_TIME_SHADED is defined in the header file lishidx.h. Passing this value to LiEntityCreateRenderStyle avoids the need to first create a core Lightworks LtInterface object to be passed to the function. Using Real-time The Session Manager will now use OpenGL rendering as its interactive rendering mode (i.e., the Rendering via the mode of rendering which is used whilst responding to mouse events). Session Manager As the Session Manager itself handles all such events, you will not need to make any explicit API calls to perform an OpenGL render. The Session Manager API function LiSessionViewUpdate will also use the rendering method specified by the control variable above. Master Doc
Note that, as long as you are using Session Manager entities such as session-views, material entities, light studios, and so on, it will not be necessary for you to explicitly invalidate any aspect of Title Page the OpenGL state (so you will not need to make calls to API functions such as LiOpenGLPrimi- tiveListInvalidate or LiOpenGLPrimitiveInvalidate or LiOpenGLShaderInvalidate after any of these elements alter, which core API users will have to do). All such operations will be Contents handled automatically, behind the scenes, by the Session Manager.
First Last
J I
Page 19 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Lightworks Author 9.0
Lightworks Real-time
Part V
Programming Guide—Core Master Doc
Title Page
Contents
First Last
J I
Page 20 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 5 Lightworks Author 9.0
Lightworks Using Real-time Rendering via the Real-time Core-Lightworks API Using Real-time Rendering via the Core-Lightworks API
Master Doc
The liopengl module offers the application three different window modes, which can be set Title Page through the control variable LI_CONTROL_OPENGL_WINDOW_MODE, which should be set to one of the following LtEnum values: Contents
• LI_OPENGL_WINDOW_MODE_LW First Last In this mode, the module will take the currently enabled drivers, create a corresponding rendering context, and pass all OpenGL commands to this rendering context • LI_OPENGL_WINDOW_MODE_APP J I In this mode, the application can set its own window or image handle independent of the current driver, via the windowing API described in Section 5.4. This is particularly useful when Page 21 of 119 providing multiple window support from within a multiple document application. • LI_OPENGL_WINDOW_MODE_CURRENT Go Back This mode allows the application to create and set the OpenGL rendering context, and will output all OpenGL commands to this context. In this mode the application is responsible for all platform-specific OpenGL setup; liopengl only issues platform-independent OpenGL calls. Search This Doc
Having chosen the desired windowing mode, liopengl should be initialised using the following Search All Docs function:
LtStatus Full Screen LiOpenGLInitialise(LtVoid none) This function initialises the module for rendering, allocating any window system independent state needed.
Having specified the windowing mode, and initialised liopengl, an interactive (i.e., OpenGL) render can be performed by simply creating and executing an appropriate Real-time render style.
Once all interactive rendering is complete, liopengl can be terminated, using the following function: Lightworks Author 9.0 LtStatus LiOpenGLTerminate(LtVoid none) Lightworks Real-time This function destroys all state associated with the set of windows used for OpenGL rendering and all state associated with the active primitive list. After termination no other API calls can be made until the liopengl module is re-initialised by a further call to LiOpenGLInitialise. Using Real-time Note of course that, generally speaking it will not be desirable to perform a single OpenGL rendering Rendering via the between the initialisation and termination of the liopengl module. It is most likely in practice that Core-Lightworks API liopengl will be initialised at the beginning of the Lightworks session, and terminated at the end of the Lightworks session, with LiOpenGLRender being called in response to various user interface events (the execution of a real-time render style) in between. Master Doc Note that if you are using the Session Manager, it is not necessary to initialise and terminate liopengl yourself, since this is done automatically by the session. Title Page Once the liopengl module has been initialised, it can be used in the following ways:
Contents 1. Interactive rendering can be carried out by liopengl. You can choose to control this process at various levels of detail depending on the amount of control you need. You should read Section 5.1 and then the sections which follow (including Section6). First Last 2. You can keep your own interactive rendering solution if you already have one, but make use of Lightworks material definitions. To do this you will have to use the ‘Material API’, so you should read Section7 next (skip the rest of this section and Section6). J I
Note that details of programmable shading support are given in Section8; you should read this Page 22 of 119 section if you want to support the latest programmable graphics hardware, whether or not you use Lightworks interactive rendering or use the Material API to enhance your own interactive rendering Go Back with Lightworks materials.
Section 10 lists all the control variables provided by liopengl. Search This Doc
5.0.1. Macintosh-Specific Initialisation Search All Docs
The control variable, LI_CONTROL_OGLDRV_MAC_DRIVER_MODE, type LtEnum, default LI_OGL- Full Screen DRV_MAC_DRIVER_MODE_COCOA enables the Real- time module to be run in either Carbon (LI_- OGLDRV_MAC_DRIVER_MODE_CARBON) (provided for legacy system compatibility) or Cocoa modes. By default, all WindowRef parameters passed to the LiOGLDrvWindowInitialise / LiOGL- DrvWindowSetCurrent / LiOGLDrvWindowTerminate functions will be interpreted as of type NSView*. In addition, the pixel_format parameter to LiOGLDrvWindowInitialise() will be interpreted as of type NSOpenGLPixelFormat*.
This control variable operates only when LI_CONTROL_OPENGL_WINDOW_MODE is set to LI_- OPENGL_WINDOW_MODE_APP. Lightworks Author 9.0 5.1. Performing rendering Lightworks Real-time
Once liopengl has been initialised, you are able to render interactively.
Lightworks provides four ways of doing this: Using Real-time Rendering via the • Render styles (i.e., using LiRenderStyleExecute with an appropriate real-time style). Core-Lightworks API The currently set view, primitive list, light list, materials, background, foreground, etc., are used. Different render styles are provided (for shaded and vector output, for example) which each expose a number of arguments to provide control over the style of rendering (just as with any other render style). Master Doc • The ‘scene level’ rendering API, LiOpenGLRender. Again, the currently set view, primitive list, light list, materials, background, foreground, Title Page etc., are used, the main difference is just that LiOpenGLRender is called in place of LiRenderStyleExecute, and control over the rendering is provided via control variables (which should be set before the render call), rather than via render style arguments. Contents The ‘scene level’ was provided prior to the introduction of render styles, and is kept for backward compatibility reasons. We would normally expect new users to make use of render First Last styles (and ideally the Session Manager, which simplifies usage further). • The ‘object level’ API, where lower level calls are embedded between LiOpenGLImageBegin and LiOpenGLImageEnd. J I In this case more detailed control over the rendering is provided in that you can specify the view, primitive list, light list, background, foreground, etc. explicitly, rather than simply using Page 23 of 119 the current Lightworks settings. It is also possible to perform ‘multi-pass rendering’ - see Section 5.1.3.1. Go Back • The ‘primitive level’ API, where each primitive can be rendered individually using LiOpenGL- PrimitiveRender, and lights can be set on an individual basis too. This provides the highest level of control over real-time rendering. Search This Doc It is also possible to perform ‘multi-pass rendering’ - see Section 5.1.3.1.
Search All Docs Note that, whichever approach is used, it is the application’s responsibility to ensure that a render operation is undertaken whenever necessary (for example in response to a mouse event which changes the view point). If materials, lights, or geometry are altered at any stage the application Full Screen must inform liopengl so that the corresponding OpenGL data is updated; this is described in Section 5.2. 5.1.1. Rendering using render styles
The easiest way to perform Real-time renders is by using render styles. When using render styles, the liopengl module translates the active Lightworks primitive list, view, lighting, and materials directly.
There are three render styles available for Real-time rendering, "real time shaded", "real Lightworks Author time vector" and "real time shaded and vector". These three render styles are described 9.0 in more detail below. For more information on render styles in general see the Foundation Rendering documentation. Lightworks Real-time The "real time shaded" render style allows shaded renders to be performed in Real-time whilst the "real time vector" render style allows vector renders to be performed in Real-time. The "real time shaded and vector" render style allows either a shaded render, a vector render or a shaded render overlaid by a vector render. For full details on these render styles please refer to the appropriate reference pages. Using Real-time Rendering via the As with any other render style, a "real time shaded" style is created using LiInterfaceCre- Core-Lightworks API ate, destroyed using LiInterfaceDestroy and executed using LiRenderStyleExecute.
The following example code illustrates how to perform a Real-time render using a "real time shaded" render style. Master Doc LtStatus status; LtInterface rstyle; Title Page LtData data;
LiDataSetEnum( &data, LI_OPENGL_WINDOW_MODE_LW ); Contents status = LiControlSet( LI_CONTROL_OPENGL_WINDOW_MODE, &data );
rstyle = LiInterfaceCreate( "real time shaded" ); First Last
status |= LiOpenGLInitialise(); J I while (handling_UI_events) { Page 24 of 119 status |= LiRenderStyleExecute( rstyle ); } Go Back status |= LiOpenGLTerminate();
The Real-time render styles provide a simpler interface to the numerous control variables which Search This Doc modify the behaviour of Real-time rendering. Note that in almost all cases the setting of control variables will not affect the behaviour of these render styles as the values of their arguments will override the control variable settings. It is therefore recommended that, in general, using control Search All Docs variables is not mixed with using render styles. Control variables which are exceptions to this rule are indicated in later sections. Full Screen Additionally the lower-level API functions described in the following sections should not, in general, be used in conjunction with render styles. Functions which can safely be used with render styles are indicated in the accompanying text.
The exception to this rule is of course that it is the application’s responsibility to tell liopengl if any materials, lights, or have been altered by explicitly ‘invalidating’ the data in question. This is described in Section 5.2.
Lightworks Author 5.1.2. The scene level API 9.0
The scene level API also uses the currently active Lightworks primitive list, view, lighting and Lightworks materials directly, just as in the render style case. This style of integration will suit those customers Real-time who have not used render styles elsewhere in their application and who just need the simplest form of integration.
Having specified the windowing mode, and initialised liopengl, as described above, an interactive Using Real-time (i.e., OpenGL) render can be performed using the following API function: Rendering via the Core-Lightworks API LtStatus LiOpenGLRender(LtVoid none) Master Doc This function renders the current Lightworks scene. At this point the current Lightworks scene is translated including the current view, lights, background, and primitive list. Title Page Note that, just as with render styles, in general it will not be desirable to perform a single OpenGL rendering between the initialisation and termination of the module. Contents An example of Real-time rendering using the scene-level API:
LtData data; First Last
LiDataSetEnum( &data, LI_OPENGL_WINDOW_MODE_LW ); LiControlSet( LI_CONTROL_OPENGL_WINDOW_MODE, &data ); J I
LiOpenGLInitialise(); Page 25 of 119 while (handling_UI_events) { Go Back LiOpenGLRender(); } Search This Doc LiOpenGLTerminate();
Remember that it is the application’s responsibility to tell liopengl if any materials, lights, or have Search All Docs been altered by explicitly ‘invalidating’ the data in question. This is described in Section 5.2.
Full Screen 5.1.3. Object level API
At this API level the application has control over which parts of the scene are rendered. This layer replaces the LiOpenGLRender functionality in the Scene Level API, allowing the following commands to be called repeatedly between the LiOpenGLInitialise and LiOpenGLTerminate calls of the level above. Lightworks Author LtStatus 9.0 LiOpenGLImageBegin(LtVoid none) Lightworks Real-time This function prepares for the generation of a new image. An OpenGL rendering context will be initialised ready to accept a new set of OpenGL calls. LiOpenGLImageBegin should be called once for each render. Using Real-time LtStatus Rendering via the LiOpenGLViewSet(LtView view) Core-Lightworks API
This function sets up the OpenGL projection matrix, model-view matrix and viewport dimensions, based on the given view. If a NULL parameter is supplied, the current Lightworks view will be Master Doc converted.
LtStatus Title Page LiOpenGLBackgroundSet(LtShader bg_shader) Contents This function clears the OpenGL colour and depth buffers, then sets the colour based on the supplied background shader. If a NULL parameter is supplied, this function uses the current Lightworks background shader. If no background is available on the Lightworks side, the default First Last liopengl background colour will be used. This can be set using the control variable LI_CONTROL_- OPENGL_CLEAR_COLOUR described below. J I Note: for the background to be correctly drawn, this API call must be made after the view has been set. Page 26 of 119
LtStatus LiOpenGLLightListSet(LtSref light_list) Go Back
This function sets up the OpenGL lighting environment based on the supplied light list. If a NULL Search This Doc parameter is supplied, the current Lightworks lights will be converted. Lightworks point, spot, eye, distant, sun and ambient lights are supported. Search All Docs This function will export up to the OpenGL implementation-dependent maximum number of lights (OpenGL supports a global ambient light plus at least 8 other lights. Some implementations may support more). Full Screen Note: for the Lightworks lights to be correctly placed in an OpenGL scene, this API call must be made after the view has been set.
The following function sets the list of tone mapping shaders to be applied to the image:
LtStatus LiOpenGLToneListSet(LtSref tone_list) Lightworks Author 9.0
It is an optional function call, and should only be used in the cases when tone mapping needs to be Lightworks applied to a radiosity solution. Real-time The function:
LtStatus LiOpenGLToneListInvalidate(LtSref tone_list, Using Real-time LtBitfield inv_flags) Rendering via the Core-Lightworks API informs the liopengl module that the tone mapping shader list has been altered in some way, and to discard any cached data associated with the tone mapping list. If a NULL parameter is passed, as the tone_list then the Lightworks active tone shader list will be used. The inv_flags parameter Master Doc indicates what has changed. Currently this must be set to LI_OPENGL_TONE_INVALIDATE_ALL.
Note: LiOpenGLToneListInvalidate can be used in conjunction with render styles. Title Page
LtStatus Contents LiOpenGLPrimitiveListRender(LtPref prim_list)
First Last This function converts and sends the supplied primitive list to OpenGL. If a NULL parameter is supplied, the Lightworks active primitive list will be used. J I LtStatus LiOpenGLImageEnd(LtVoid none) Page 27 of 119
This function finishes rendering the current image, ensures that the image is actually displayed in Go Back the window, and that any associated frame state is released.
The following two functions allow access to OpenGL’s polygon offset functionality. They can be Search This Doc used to move the rendered geometry towards or away from the camera (for example to resolve depth buffer issues when highlighting geometry). Each call to LiOpenGLPolygonOffsetEnable should be matched with a call to LiOpenGLPolygonOffsetDisable. Search All Docs
Full Screen LtStatus LiOpenGLPolygonOffsetEnable(LtOpenGLPolyOffsetType type, LtOpenGLPolyOffset offset)
The type flag can be one of: Lightworks Author • LI_OPENGL_POLYGON_TYPE_LINE 9.0 • LI_OPENGL_POLYGON_TYPE_FILL Lightworks Real-time LI_OPENGL_POLYGON_TYPE_LINE offsets all lines, i.e., all primitives rendered in LI_OPENGL_- REN_METHOD_WIRE and LI_OPENGL_REN_METHOD_EDGE modes.
LI_OPENGL_POLYGON_TYPE_FILL offsets all filled polygons, i.e., all primitives rendered in LI_- Using Real-time OPENGL_REN_METHOD_FLAT and LI_OPENGL_REN_METHOD_SMOOTH modes. Rendering via the Core-Lightworks API The offset flag can be one of:
• LI_OPENGL_POLYGON_OFFSET_NEARER Master Doc • LI_OPENGL_POLYGON_OFFSET_FURTHER Title Page LI_OPENGL_POLYGON_OFFSET_NEARER offsets the primitive so that it is rendered closer to the view point, and LI_OPENGL_POLYGON_OFFSET_FURTHER offsets the primitive so that it is rendered Contents further away from the view point.
First Last LtStatus LiOpenGLPolygonOffsetDisable(LtOpenGLPolyOffsetType type) J I The parameter type should be the same value as passed into LiOpenGLPolygonOffsetEnable. Page 28 of 119
5.1.3.1. Multi-pass rendering Go Back Certain effects in OpenGL require the geometry to be rendered multiple times. For example, the shadow mapping algorithm requires the geometry to be rendered at least once for each light casting Search This Doc shadows. To accommodate this functionality, there are three API functions that can now be used to achieve a multi-pass effect: Search All Docs LtNat32 LiOpenGLSceneGetNumPasses(LtVoid) Full Screen This function returns the number of times the geometry must be sent to OpenGL to render the scene correctly. Geometry is sent to OpenGL by using the LiOpenGLPrimitiveListRender or LiOpenGLPrimitiveRender functions.
LtStatus LiOpenGLSceneBeginPass(LtNat32 pass) Lightworks Author 9.0 Initialises the OpenGL state for the given render pass. Lightworks LtStatus Real-time LiOpenGLSceneEndPass(LtNat32 pass)
Informs the liopengl module to terminate a given pass, allowing it to clear up any per pass state. Using Real-time These functions must be used with the Object level API to ensure correct rendering. For example, Rendering via the the following code shows how the Scene Level API function LiOpenGLRender is implemented: Core-Lightworks API
LtNat32 pass, nr_passes; Master Doc LiOpenGLImageBegin();
LiOpenGLViewSet( LI_VIEW_CURRENT ); Title Page LiOpenGLBackgroundSet( NULL ); LiOpenGLLightListSet( NULL ); LiOpenGLToneListSet( NULL ); Contents nr_passes = LiOpenGLSceneGetNumPasses();
for ( pass = 0; pass < nr_passes; pass++ ) First Last { LiOpenGLSceneBeginPass( pass ); LiOpenGLPrimitiveListRender( NULL ); J I LiOpenGLSceneEndPass( pass ); } Page 29 of 119 LiOpenGLImageEnd();
Go Back
5.1.3.2. Advanced multi-pass rendering Search This Doc
NEW Lightworks also supports advanced user control over the multi-pass Real-time rendering. Multi-pass rendering allows you to produce a high-quality render, incorporating effects such as: Search All Docs
• Ambient lighting (ambient/eye), in particular SSAO; Full Screen • A single sun or distant light for the sun; • Soft shadows; • Environment reflections.
As can be seen in the simplified code example for LiOpenGLRender - Section 5.1.3 above - by default, Lightworks Real-time manages these effects but adheres to the graphics hardware limit for the number of lights allowed in one pass. By default, if there are more lights than the hardware can Lightworks Author handle then these lights do not get rendered. 9.0
So, for example, if you want to extend the number of lights that are displayed in a Real-time render, Lightworks or modify how these or other effects are displayed, then you need to supply your own multi-pass Real-time rendering function using the call-back LI_CALL_OPENGL_MULTIPASS_RENDER.
The prototype for the call-back is:
Using Real-time typedef LtStatus (*LtFuncOpenGLMultipassRender) PROTO(( Rendering via the LtVoid Core-Lightworks API ));
This call-back allows the user to override the system API LiOpenGLRender. Using a call-back Master Doc rather than directly calling this function allows the GUI Framework and Session Manager layers to automatically use this functionality too. Title Page Note: Many Real-time passes reduce navigation speed considerably and there may be caveats as to how certain features are displayed. The best usage of multi-pass real-time, may therefore be as a beauty pass, i.e. to perform a fill-in render, once the user stops navigating. User requirements Contents vary depending on which features of Real-time are being used and the type of lights in the scene, so please contact Lightworks Support for guidance on using this functionality. First Last Previous generation graphics cards, along with Cg, were limited to 3 shadow casting lights and 6 lights in total. More recent cards, using GLSL, can support 10 shadow casting lights and 20 lights in total. Typically, Lightworks Real-time will ignore any lights it encounters, once these limits have J I been reached. Multi-pass, however, circumvents these limitations, by rendering all the lights using a number of passes. Page 30 of 119 Note that it is possible to query the graphics card to determine how many shadow casting and non-shadow casting lights are supported using the API LiOpenGLQuery. See Section 8.4 and Section 5.3. Go Back
A multi-pass render works by splitting the render passes up into two main groups: The first pass will render any ambient/eye lights and SSAO; the second pass handles all the other types of lights in the Search This Doc scene. It is important to note that both passes will share the same light list, but with manipulation of the intensity. The inclusion of the SSAO calculation is also toggled between the two passes. Search All Docs It is important to note that the light type determines how an object will be illuminated and hence shaded, therefore it has to be compiled into the opengl programs; something that takes time. This Full Screen means that the types of lights in the light list cannot change between passes. Note the sequencing that happens during a multi-pass render and particularly the wrapping of the LiOpenGLImageBegin and LiOpenGLImageEnd APIs around the two groups of passes. In practice, this is structured as follows:
/* create shadow maps */
/* set intensity of any sun or distant lights to zero */ Lightworks Author / render ambient/eye light and SSAO / * * 9.0 /* set ignoring of transparent primitives to true */ LiOpenGLImageBegin render() Lightworks LiOpenGLImageEnd Real-time
/* reset ignoring of transparent primitives */ /* clear the opengl buffer */ /* switch-off SSAO */ LiOpenGLImageBegin Using Real-time /* begin blending */ Rendering via the /* render all the other lights */ Core-Lightworks API render() LiOpenGLImageEnd
Master Doc Where the implementation of "render()" would be structured as follows:
LiOpenGLSceneGetNumPasses Title Page LiOpenGLSceneBeginPass LiOpenGLPrimitiveListRender LiOpenGLSceneEndPass Contents
While it is difficult to write a generic multi-pass routine for any arbitrary light list, it is relatively easy First Last to write a routine if you broadly know the type of lights you will be using as this will determine the number of passes etc.
If you need to support an application, whereby the user has total control over lists of arbitrary light J I types, the best approach may be to sort the lights and calculate the frequency ratio for each type and then allocate the available hardware resources accordingly. Any logic should ensure that the Page 31 of 119 number of passes is always kept to the minimum, in order to maximise performance.
Projector lights can be used to simulate point lights, but this is unadvisable as it would require a Go Back lot of passes. Additionally, goniometric lights can’t be easily simulated, therefore we advise that goniometric, and point lights, are set to be non-shadow casting and to use inverse sq fall off. Search This Doc Note that if tone mapping is included in the photo-realistic render, then the correlation between the photo-realistic render and the real-time render will vary somewhat. Search All Docs Because of the way in which OpenGL accumulates the final image, the control variable, LI_- CONTROL_OPENGL_IGNORE_TRANSPARENT_PRIMS, can used to tell Lightworks Real-time to group transparent primitives, otherwise this can lead to darkening of such geometry. Full Screen For a complete working example, please see the example application in the examples/LaSessManRTMultipass sub-directory.
5.1.4. Primitive level API Lightworks Author At this API level the application has control over individual primitives and lights. These conversion routines may be called repeatedly between the LiOpenGLImageBegin and LiOpenGLImageEnd 9.0 calls of the level above. Lightworks Real-time LtStatus LiOpenGLLightSet(LtShader light, LtNat32 gl_light_num)
This function converts a Lightworks light to an OpenGL equivalent. Lightworks point, spot, eye Using Real-time distant and sun lights are supported. OpenGL supports a limited set of lights. The gl_light_num Rendering via the argument specifies which OpenGL light you wish to set. OpenGL does not support individual ambient Core-Lightworks API lights, instead it has a single global ambient light value. Use LiOpenGLLightListSet to convert ambient lights.
Note: for the Lightworks lights to be correctly placed in an OpenGL scene, this API call must be Master Doc made after the view has been converted
Title Page LtStatus LiOpenGLPrimitiveRender(LtPrim prim) Contents This function sends a Lightworks primitive to OpenGL. For composite primitives, all sub-primitives are also sent to OpenGL. Any associated materials, transforms and texture spaces are taken into First Last account and sent to OpenGL if necessary.
J I
Page 32 of 119
Go Back
Search This Doc
Search All Docs
Full Screen 5.2. Telling liopengl when material or primitive information has changed
If you are not using the Session Manager then it is up to your application to handle the situation of materials or geometry being altered, so that the cached data on the graphics card can be overridden. Lightworks Author Basically your application needs to tell liopengl that certain information is now invalid, so that it 9.0 can fetch the correct information from Lightworks data structures and update the information on the graphics card. Lightworks Real-time 5.2.1. Invalidation of geometry
Either the entire primitive list can be declared as invalid, or this can be done on an individual primitive Using Real-time basis. Rendering via the Core-Lightworks API
5.2.1.1. All geometry Master Doc
LtStatus LiOpenGLPrimitiveListInvalidate(LtPref prim_list, Title Page LtBitfield inv_flags)
Contents This function informs the liopengl module that the list of primitives has changed in some way and that it should discard any state cached with the primitives. Such state could include polygons created from faceting a surface within Lightworks, or an OpenGL display list created if running First Last in LI_OPENGL_CONV_MODE_LIST mode. It is the responsibility of the application to notify the liopengl module if any primitive property has changed. J I If a NULL parameter is supplied, the active primitive list is used. For composite primitives, this function invalidates all sub-primitives too. This function can be used as part of an incremental geometry update scheme or simply to release resources. The inv_flags parameter is a combination of the Page 33 of 119 following flags, see LiOpenGLPrimitiveInvalidate for details: Go Back • LI_OPENGL_INVALIDATE_GEOMETRY
• LI_OPENGL_INVALIDATE_TRANSFORM Search This Doc • LI_OPENGL_INVALIDATE_MATERIAL
• LI_OPENGL_INVALIDATE_TEXTURE_SPACE Search All Docs • LI_OPENGL_INVALIDATE_CONTEXT Full Screen • LI_OPENGL_INVALIDATE_TONE • LI_OPENGL_INVALIDATE_LIGHTING • LI_OPENGL_INVALIDATE_MATERIAL_REF • LI_OPENGL_INVALIDATE_ALL
Note: LiOpenGLPrimitiveListInvalidate can be used in conjunction with render styles. Lightworks Author 9.0
5.2.1.2. Individual primitives Lightworks Real-time Rather than invalidating an entire primitive list, it is possible to invalidate a single primitive using the following function:
LtStatus Using Real-time LiOpenGLPrimitiveInvalidate(LtPrim prim, Rendering via the LtBitfield inv_flags) Core-Lightworks API
This function informs the liopengl module that the primitive has changed in some way and that it should discard any state cached with the primitive. For composite primitives, this function must be Master Doc called on each sub-primitive that has changed and on each parent composite primitive. This function can be used as part of an incremental geometry update scheme or simply to release resources. The inv_flags parameter comprises a combination of the following flags: Title Page
• LI_OPENGL_INVALIDATE_GEOMETRY Contents • LI_OPENGL_INVALIDATE_TRANSFORM First Last • LI_OPENGL_INVALIDATE_MATERIAL • LI_OPENGL_INVALIDATE_TEXTURE_SPACE J I • LI_OPENGL_INVALIDATE_CONTEXT
• LI_OPENGL_INVALIDATE_TONE Page 34 of 119 • LI_OPENGL_INVALIDATE_LIGHTING • LI_OPENGL_INVALIDATE_MATERIAL_REF Go Back • LI_OPENGL_INVALIDATE_ALL Search This Doc GEOMETRY invalidates any cached data derived from the primitive geometry. TRANSFORM invalidates any cached data derived from the primitive’s transform. MATERIAL invalidates any cached data Search All Docs derived from the primitive’s material. TEXTURE_SPACE invalidates any cached data derived from the primitive’s texture space. CONTEXT invalidates any cached data that is stored in the current OpenGL context. The context data should be invalidated when switching the destination for rendering to Full Screen an incompatible context (for example, from a window to an image). TONE invalidates all cached data associated with tone mapping. LIGHTING invalidates all cached data associated with lighting. MATERIAL_REF invalidates a primitives association with a material, but does not invalidate the material itself. ALL invalidates all cached data used by the primitive.
Note: LiOpenGLPrimitiveInvalidate can be used in conjunction with render styles.
5.2.2. Invalidation of materials Lightworks Author 9.0 Material cached state may also be invalidated using the following function: Lightworks Real-time LtStatus LiOpenGLMaterialInvalidate(LtMaterial material, LtBitfield inv_flags)
Using Real-time This function informs the liopengl module that the given material has changed in some way. The Rendering via the inv_flags parameter comprises a combination of the following flags: Core-Lightworks API
• LI_OPENGL_MATERIAL_INVALIDATE_COLOUR Master Doc • LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_SCALE • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY Title Page • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_SCALE
• LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE Contents • LI_OPENGL_MATERIAL_INVALIDATE_ALL • LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_PARAMS First Last • LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_SHADER J I • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_PARAMS • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_SHADER Page 35 of 119 • LI_OPENGL_MATERIAL_INVALIDATE_REFLECTANCE_PARAMS • LI_OPENGL_MATERIAL_INVALIDATE_REFLECTANCE_SHADER Go Back
• LI_OPENGL_MATERIAL_INVALIDATE_DISPLACEMENT_PARAMS Search This Doc • LI_OPENGL_MATERIAL_INVALIDATE_DISPLACEMENT_SHADER • LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE_PARAMS Search All Docs • LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE_SHADER
• LI_OPENGL_MATERIAL_INVALIDATE_VERTEX_PARAMS Full Screen • LI_OPENGL_MATERIAL_INVALIDATE_VERTEX_SHADER • LI_OPENGL_MATERIAL_INVALIDATE_PIPELINE_PARAMS • LI_OPENGL_MATERIAL_INVALIDATE_PIPELINE_SHADER • LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_SCALE • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_SCALE • LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE Lightworks Author 9.0
_PARAMS indicates that a parameter on the appropriate shader has been changed, and any cached Lightworks data will need to be updated. _SHADER indeicates that the given shader has changed, and the material should be updated to reflect this change. COLOUR invalidates any cached data derived from Real-time the material’s colour shader. COLOUR_SCALE invalidates any cached data derived from the scale parameter of a material’s colour shader. TRANSPARENCY invalidates any cached data derived from the material’s transparency shader. TRANSPARENCY_SCALE invalidates any cached data derived from the scale parameter of a material’s transparency shader. TEXTURE_SPACE invalidates any Using Real-time cached data derived from the material’s Texture Space shader. ALL invalidates all cached data used Rendering via the by the material. Core-Lightworks API
Note: LiOpenGLMaterialInvalidate can be used in conjunction with render styles.
Master Doc 5.2.3. Invalidation of shaders Title Page The following function informs the liopengl module that the shader has changed in some way and that it should discard any state cached with the shader: Contents
LtStatus LiOpenGLShaderInvalidate(LtShader shader, First Last LtBitfield inv_flags) J I The inv_flags parameter currently only supports the following flag:
Page 36 of 119 • LI_OPENGL_SHADER_INVALIDATE_SHADER
• LI_OPENGL_SHADER_INVALIDATE_PARAMS Go Back • LI_OPENGL_SHADER_INVALIDATE_SHADOW_MAP • LI_OPENGL_SHADER_INVALIDATE_DESTROY Search This Doc • LI_OPENGL_SHADER_INVALIDATE_ALL Search All Docs
_PARAMS indicates that a parameter on the appropriate shader has been changed, and any cached data will need to be updated. _SHADER indicates that the given shader has changed, and the Full Screen material should be updated to reflect this change. _SHADOW_MAP indicates that any associated realtime shadow map for the given light shader should be marked as invalid. _DESTROY indicates that any cached state associated with the given shader should not only be marked as invalid, but should be destroyed as well. _ALL is a synonym for _SHADER, _PARAMS and _SHADOW_MAP.
Currently, only background and light shaders have any cached state. A shader should be invalidated if it is altered. Colour, transparency and reflectance shaders must be invalidated with respect to the primitive and/or material they are associated with through a call to LiOpenGLPrimitiveInvali- date or LiOpenGLMaterialInvalidate. Lightworks Author Note: LiOpenGLShaderInvalidate can be used in conjunction with render styles. 9.0 Lightworks 5.2.4. Light Group support Real-time
Lightworks Real-time supports the use of Light Groups in rendering. Any light contained within a Light Group will have its intensity and colour scaled by the light groups intensity and colour, as in Using Real-time standard Lightworks rendering. Rendering via the Core-Lightworks API Note that any change to a Light Groups intensity or colour will have to be registered with the Lightworks Real-time before the changes will take effect. This is done by invalidating the Light Groups using the following functions: Master Doc LtStatus LiOpenGLLightGroupInvalidate(LtLightGroup light_group, Title Page LtBitfield inv_flags) and Contents
LtStatus First Last LiOpenGLLightGroupReferenceInvalidate( LtLGref light_group_ref, LtBitfield inv_flags) J I
The inv_flags parameter currently only supports the following flag: Page 37 of 119
• LI_OPENGL_SHADER_INVALIDATE_ALL Go Back
Note: These functions can be used in conjunction with render styles. Search This Doc
5.2.5. Generalised Invalidation Search All Docs
There is a single, convenient API function, through which all objects can be invalidated. NB The Full Screen function LiOpenGLGeneralInvalidate could also be used. These functions are in fact the same. LtStatus LiOpenGLInvalidate(LtGenericPtr object, LtEnum object_type, LtBitfield inv_flags)
Table 5.1 describes what properties can be invalidated. Lightworks Author OpenGL Invalidation Data 9.0 Object Data Type Object Type Description (prefix: LI_OPENGL_INVALIDATE...) Lightworks LtEnvironment _ENVIRONMENT_MAP The following flags can be used (prefix with Real-time LI_OPENGL_INVALIDATE_ENVMAP): • _IMAGE - When the image has been changed • _ORIENTATION - when the orienta- Using Real-time tion parameters have changed ("up" Rendering via the and "twist") Core-Lightworks API • _ALL - Is the same as setting both _IMAGE and _ORIENTATION
LtShader _BACKGROUND See LiOpenGLShaderInvalidate Master Doc LtShader _LIGHT See LiOpenGLShaderInvalidate LtLightGroup _LIGHT_GROUP See LiOpenGLLightGroupInvalidate LtLGRef _LIGHT__GROUP_REF See LiOpenGLLightGroupReferen- Title Page ceInvalidate LtSref _TONE_LIST See LiOpenGLToneListInvalidate LtPrim _PRIMITIVE LiOpenGLPrimitiveInvalidate See Contents LtPref _PRIMITIVE_LIST See LiOpenGLPrimitiveListInvali- date N/A _STATE See LiOpenGLInvalidateState First Last LtMaterial _MATERIAL_LW See LiOpenGLMaterialInvalidate LtOpenGLMaterial _MATERIAL_GL See LiOpenGLMaterialRepInvali- date J I Table 5.1: OpenGL data which can be invalidated Page 38 of 119
5.3. Querying Lightworks Real-time specific information Go Back
General information about the capabilities of Lightworks Real-time can be queried using the following Search This Doc API function:
LtStatus Search All Docs LiOpenGLQuery(LtOpenGLQuery query, LtGenericPtr info, LtData *answer) Full Screen Currently available queries (all require NULL as the info parameter unless otherwise stated) are:
• LI_OPENGL_QUERY_VENDOR • LI_OPENGL_QUERY_RENDERER
• LI_OPENGL_QUERY_VERSION Lightworks Author • LI_OPENGL_QUERY_PROGRAMMABLE_LANGUAGES 9.0
• LI_OPENGL_QUERY_MAX_PROG_LIGHTS Lightworks • LI_OPENGL_QUERY_MAX_PROG_SHADOW_LIGHTS Real-time
• LI_OPENGL_QUERY_SHADOW_DEPTHS • LI_OPENGL_QUERY_LIGHT_SUPPORT_SHADOWS Using Real-time • LI_OPENGL_QUERY_MAX_CLIP_PLANES Rendering via the • LI_OPENGL_QUERY_SSAO_SUPPORT Core-Lightworks API
Note: Master Doc
1. LI_OPENGL_QUERY_VENDOR—LtString returns OpenGL Vendor String. Title Page 2. LI_OPENGL_QUERY_RENDERER—LtString return OpenGL Renderer String.
3. LI_OPENGL_QUERY_VERSION—LtString returns OpenGL Version String. Contents 4. LI_OPENGL_QUERY_PROGRAMMABLE_LANGUAGES—returns which programmable shading languages are supported as an LtBitfield with LI_OPENGL_LANGUAGE_SUPPORT_CG bit First Last set if Cg is supported and LI_OPENGL_LANGUAGE_SUPPORT_GLSLANG bit set if the OpenGL Shading Language is supported. 5. LI_OPENGL_QUERY_MAX_PROG_LIGHTS—LtNat32 returns the maximum number of lights J I supported in programmable shading based on the current choice of shading language. The value returned may not be the same with Cg and GLSL. Page 39 of 119 6. LI_OPENGL_QUERY_MAX_PROG_SHADOW_LIGHTS—LtNat32 returns the maximum number of shadow lights supported in programmable shading based on the current choice of shading language. The value returned may not be the same with Cg and GLSL. Go Back 7. LI_OPENGL_QUERY_SHADOW_DEPTHS—LtBitfield returns supported shadow depths. Search This Doc 8. LI_OPENGL_QUERY_LIGHT_SUPPORT_SHADOWS—requires a light shader as info, and returns an LtBoolean indicating if the given light supports shadows or not. Search All Docs 9. LI_OPENGL_QUERY_MAX_CLIP_PLANES—returns the maximum number of user defined clip- ping planes that are supported. 10. LI_OPENGL_QUERY_SSAO_SUPPORT—LtBoolean returns whether Screen Space Ambient Full Screen Occlusion is supported. 5.4. Windows API
For the management of windows used by the liopengl module in LI_OPENGL_WINDOW_MODE_- APP, three API calls are available. They are used to create, make current and destroy per window rendering contexts, required for OpenGL rendering. Any number of windows may be used concurrently while the module is running, allowing for multiple rendering contexts to be switched Lightworks Author between whilst the module is active. 9.0 Windows may be initialised, set current and terminated at any time before the module has been terminated. Upon calling LiOpenGLTerminate the module will delete all cached state for windows, Lightworks if not previously done so with the LiOpenGLWindowTerminate call. It is invalid to initialise Real-time a new window or make an existing window current between the LiOpenGLImageBegin and LiOpenGLImageEnd pairs of scene generation.
A complementary set of three API calls is available for rendering OpenGL into images. State cached with primitives may not be compatible between windows and images. Using Real-time Rendering via the The liopengl module automatically invalidates the cached state when switching between incom- Core-Lightworks API patible contexts.
The window API calls are window system specific, with variants appropriate to the local window Master Doc system available on each platform.
Title Page 5.4.1. Win32 (Wgl)
Contents The following API function prepares a window for OpenGL rendering:
First Last LtStatus LiOpenGLWindowInitialise(HWND window, LtInt32 pixel_format) J I The pixel format is specified by pixel_format and defines which OpenGL buffers to use. If passed 0, the module will pick the most appropriate pixel format dependent upon the type of OpenGL Page 40 of 119 hardware available. If a windows pixel format has already been set, the pixel_format argument will be ignored. Go Back Notes:
• Some OpenGL state (display lists, texture objects) are shared between windows. This is only Search This Doc guaranteed to work if the same pixel format is used for all windows. This state is not compatible with that cached and shared between images. Primitives previously rendered to images must be invalidated before use. The liopengl module now automatically invalidates states when Search All Docs switching between incompatible contexts.
• A window used for OpenGL rendering should be created with the WS_CLIPCHILDREN and Full Screen WS_CLIPSIBLINGS styles. Additionally, the window class attribute should not include the CS_PARENTDC style. The function LiOpenGLWindowSetCurrent sets the window as the one to use for OpenGL rendering. If initialise hasn’t been called for the window, it will initialise using pixel format 0. This call should be made for the target window before rendering commences for that window.
LtStatus LiOpenGLWindowSetCurrent(HWND window) Lightworks Author 9.0 LiOpenGLWindowTerminate cleans the OpenGL state, and should be called before the window is destroyed: Lightworks Real-time LtStatus LiOpenGLWindowTerminate(HWND window)
An additional API function is provided to query the current rendering context. Using Real-time Rendering via the Core-Lightworks API LtStatus LiOGLDrvContextGetData(LtEnum request, LtData * data)
Master Doc Table 5.2 describes what information can be enquired of the current rendering context.
Title Page OpenGL Rendering Context Data Data field Data type Description Prefix: LI_OPENGL_CONTEXT... Contents _DEPTH_BITS LtNat32 Precision of the depth buffer in bits, or 0 if it is unavailable in the current mode. _RED_BITS LtNat32 Depth of the red channel in bits, or 0 if it is First Last unavailable in the current mode. _GREEN_BITS LtNat32 Depth of the green channel in bits, or 0 if it is unavailable in the current mode. _BLUE_BITS LtNat32 Depth of the blue channel in bits, or 0 if it J I is unavailable in the current mode. _ALPHA_BITS LtNat32 Depth of the alpha channel in bits, or 0 if it Page 41 of 119 is unavailable in the current mode. _STENCIL_BITS LtNat32 Depth of the stencil buffer in bits, or 0 if it is unavailable in the current mode. Go Back _PIXEL_TYPE LtNat32 The pixel type used by the current ren- dering context. This will always return GL_RGBA in the current implementation of Search This Doc liogldrv.
Table 5.2: OpenGL rendering context data which can be queried Search All Docs
Full Screen Chapter 6 Lightworks Author 9.0
Lightworks Advanced usage Real-time
Advanced usage
Master Doc This section explains how advanced users can override standard liopengl behaviour.
Title Page 6.1. OpenGL shadows Contents
The liopengl module supports shadows for spot, distant, sun and projector lights through a shadow map algorithm. The shadow mapping algorithm requires the use of OpenGL extensions, First Last and is thus only supported on certain graphics cards. Supported cards include TNT2 based cards and any of the GeForce family of cards. Note: OpenGL shadows are not supported in software accelerated OpenGL. J I
To enable shadows, a shadow map must first be created for a light, using the following function: Page 42 of 119
LtStatus LiOpenGLShadowMapCreate(LtShader light, LtPref prims) Go Back
Where light is the light which is to cast shadows, and prims is a list of primitives from which to Search This Doc generate the shadow map. Note, any primitive which is flagged as not casting shadows will not be rendered in the shadow map. Shadow maps will only be created for spot, distant, sun and projector lights. Search All Docs
The resolution of the shadow map is taken from the "resolution" parameter of the light shader. Full Screen A shadow map will always be created, if possible, for a spot, distant, sun or projector light. However, the shadow map will only be used if the "shadows" parameter of the light shader is set to TRUE.
For convenience, another API call is available to create shadow maps for a list of lights.
LtStatus LiOpenGLLightListShadowMapCreate(LtSref lights, LtPref prims) Lightworks Author 9.0
Any light which does not support shadows (any except spot, distant, sun and projector) will not be Lightworks affected. Real-time Note: both LiOpenGLShadowMapCreate and LiOpenGLLightListShadowMapCreate must be called outside of LiOpenGLImageBegin and LiOpenGLImageEnd.
If a parameter of the light shader which affects the shadow map is altered, then the shadow map Advanced usage must be recreated (for example, if the location of the light is altered). A function is available to check if the current shadow map for a light is still valid.
LtBoolean LiOpenGLShadowMapIsValid(LtShader light) Master Doc
This function will check to see if any of the light’s parameters which would affect the shadow map Title Page has changed, returning TRUE if the shadow map is still valid, and FALSE otherwise.
LtBoolean Contents LiOpenGLShadowMapIsAvailable(LtShader light) First Last This function checks to see if a shadow map is attached to the given light, and that it is compatible with the current rendering context. J I
6.1.1. Shadow resolution Page 43 of 119
The resolution of the shadowmap is based on the "resolution" parameter of the light shader. Go Back Lightworks Real-time only supports power of two resolution shadowmaps, so the resolution will be clamped to the nearest power of two. Search This Doc If the graphics card supports PBuffers (with the WGL_ARB_pbuffer extension) then a PBuffer will be used to create the shadowmap. The resolution of the shadow map will be the nearest power of two below the light shaders "resolution" parameter. Search All Docs
If Pbuffers are not supported by the graphics card, or PBuffer rendering has been switched off via the LI_CONTROL_OPENGL_SHADOW_OPTIONS control var, the the maximum size of depth map, as Full Screen given by the "resolution" parameter of the light shader, is limited by the current window size. A depth map cannot be created which is larger than the current window size in this case. 6.1.2. Shadow depth
There are three shadow mapping algorithms, differing in the precision of the depth map used, and the required OpenGL extensions needed to implement the algorithm. The algorithms can be selected using the LI_CONTROL_OPENGL_SHADOW_DEPTH. If a shadow depth is selected which is not supported by the graphics card, then the most appropriate one will be used. (For example, selecting LI_OPENGL_SHADOW_DEPTH_16 for a graphics card which only supports 8 bit mode, will Lightworks Author result in 8 bit mode being used). 9.0
The three shadow algorithms, and the extension required to support them are given in the table Lightworks below: Real-time
Depth Map Precision Required Extensions 8 Bit GL_ARB_multitexture GL_EXT_texture_env_combine Advanced usage 16 bit GL_ARB_multitexture GL_EXT_texture_env_combine GL_NV_register_combiners A stencil buffer 24 bit GL_ARB_shadow GL_ARB_depth_texture Master Doc
Title Page 6.1.3. Soft shadows
Soft shadows are available with graphics cards that support programmable shading to Unified Contents Shader Model standard1 (in DirectX terminology, Shader Model 4.0). Programmable shading is discussed further in Section8. First Last Soft shadows can be selected using the control variable LI_CONTROL_OPENGL_ENABLE_SOFT_- SHADOWS, or via the "soft shadows" parameter of the "real time shaded" or "real time shaded and vector" render styles. J I
Note that programmable shading must also be enabled at the same time (so the control variable Page 44 of 119 LI_CONTROL_OPENGL_ENABLE_PROGRAMMABLE_SHADING must be set to TRUE, or the "pro- grammable shading" parameter of the "real time shaded" or "real time shaded and vector" render style must be set to TRUE). Go Back
If soft shadows are selected, the following four control variables (and associated render style arguments) can be used to further control the appearance of the shadows: Search This Doc
• LI_CONTROL_OPENGL_SHADOW_FILTER_SIZE (LtNat32) Search All Docs Controls the quality of soft shadows when using programmable shading. Increasing the filter size will lead to a smoother transition between lit and shadowed areas, at the cost of slower rendering speeds. Setting the filter size to 1 will have the same effect as disabling soft shadows. Full Screen
1Usually such cards will be classified as providing support for Direct3D 10 or DirectX 10 by the manufacturer. Note that some older or less capable graphics cards may struggle to run correctly with high values for this setting. The default is 5. This control variable maps to the "shadow filter size" argument of the "real time shaded" and "real time shaded and vector" render styles. This control is also mapped to CgFX by the ShadowMapFilterSize semantic which can be used in a CgFX shader by including the following: Lightworks Author float smFilter : ShadowMapFilterSize < 9.0 string Object = "DirectionalLight0"; string UIWidget = "None"; Lightworks >; Real-time
• LI_CONTROL_OPENGL_SHADOW_PENUMBRA_WIDTH (LtNat32) Controls the width of the transition between lit and shadowed areas when soft shadows are enabled in programmable shading. Advanced usage This control variable maps to the "penumbra width" argument of the "real time shaded" and "real time shaded and vector" render styles. This control is also mapped to CgFX by the ShadowMapPenumbraWidth semantic which can be used in a CgFX shader by including the following: Master Doc float smWidth : ShadowMapPenumbraWidth < string Object = "DirectionalLight0"; string UIWidget = "None"; Title Page >;
• LI_CONTROL_OPENGL_SHADOW_DEPTH_BIAS (LtFloat) Contents This control permits the depth bias of the shadow map look-up to be altered to alleviate shadow-mapping artifacts. It is of type LtFloat; range: infinite; initial value: 0.005. The value First Last isn’t clamped to any range, but should probably be restricted to positive values. The maximum value will be scene-dependent; we would be surprised to see it go over 1.0, but the option is there, just in case. J I This control variable maps to the "shadow map bias" argument of the "real time shaded" and "real time shaded and vector" render styles. Page 45 of 119 This control is also mapped to CgFX by the ShadowMapDepthBias semantic which can be used in a CgFX shader by including the following: Go Back float smBias : ShadowMapDepthBias < string Object = "DirectionalLight0"; string UIWidget = "None"; Search This Doc >;
• LI_CONTROL_OPENGL_SHADOW_GRADIENT_CLAMP (LtFloat) Search All Docs This control can be used to tweak the soft shadows effect to reduce artifacts when light hits a surface at a shallow angle. It is of type LtFloat; range [0, 90]; initial value: 85 (degrees). Full Screen When we perform a Real-time programmable render with soft shadows, the OpenGL/Cg code calculates the depth gradient at each point on shadowed surfaces, from the point of view of the shadow-casting light. That is, we work out how quickly the depth of the surface appears to vary as we move across the light’s field of view. A surface that is almost face-on to the light will have a small gradient. (The angle between the surface normal and the surface-to-light-source vector is near 0.) A surface that is almost edge- on to the light will have a large gradient. (The angle between the surface normal and the surface-to-light-source vector is near 90 degrees.) This gradient value is used to adjust the soft shadow effect at each point, to prevent self-shadowing artifacts. Lightworks Author This control allows the user to clamp the gradient value before it is used in the soft shadow 9.0 calculation. This may help to reduce other types of shadow artifacts. The control is an angle between 0 and 90 degrees. If the gradient at a point is calculated as being larger than this Lightworks value, it is clamped down to the specified value. Real-time Setting the maximum permissible value (89.99) recreates the pre-Lightworks 8.2 soft shadow behaviour. That is, there is effectively no clamping. Although the effect will be scene-dependent, typically you should find that a value between 80 and 85 is adequate. This control variable maps to the "shadow gradient clamp" argument of the "real time Advanced usage shaded" and "real time shaded and vector" render styles. This control is also mapped to CgFX by the ShadowMapGradientClamp semantic which can be used in a CgFX shader by including the following:
float smClamp : ShadowMapGradientClamp < string Object = "DirectionalLight0"; Master Doc string UIWidget = "None"; >; Title Page
Note that as global controls, the control variables listed above will affect all materials, including Lightworks programmable materials, not just CgFX materials. CgFX materials will only be affected if Contents you include and use the CgFX semantics, as described above.
First Last 6.1.4. OpenGL shadow limitations J I Note the following limitations:
Page 46 of 119 • There are some inherent problems with shadow maps and OpenGL. The algorithms are prone to artifacts due to the limited precision available for the depth map (this is more apparent when using the 8 bit depth maps). Go Back • Real-time rendering does not currently support the per-primitive shadow receive flag (i.e., LiPrimitiveSetShadowReceive is not honoured). Search This Doc
Search All Docs 6.2. Annotation support
Full Screen Lightworks Real-time allows user specified OpenGL based functions to be called at the end of rendering to annotate the Real-time render. This functionality can be used to provide such effects as watermarking and text annotation. Several annotation functions may be specified, and will be executed in the order they are passed to the Real-time module. Additionally, data may be passed to these functions, to provide any necessary information.
The annotation functions will only be called if the _HOLD_IMAGE control variable is set to FALSE.
To set an annotation function, the following API function must be used: Lightworks Author 9.0 LtStatus LiOpenGLSetAnnotationFunction(LtFuncGLAnnotate func, Lightworks LtGenericPtr data, Real-time LtBoolean append)
• func is the actual annotation function Advanced usage • data is the data to be passed to the annotation function when it is called
• append specifies if the function is to be added to the end of the list of annotation functions (TRUE), or to replace the current list of annotation functions (FALSE).
Master Doc And the prototype for the annotation function is defined as:
LtStatus (*LtFuncGLAnnotate) (LtGenericPtr data); Title Page
• data is the annotation function specific data Contents
The list of annotation functions can be reset by passing a NULL function pointer to the LiOpenGLSe- First Last tAnnotationFunction with the append parameter set to FALSE.
Note: LiOpenGLSetAnnotationFunction can be used in conjunction with render styles. J I
Page 47 of 119 6.3. Procedural rendering
Go Back The following liopengl API functions allow customised OpenGL rendering of primitives. A procedural rendering class can be created and assigned to a primitive, to override the default liopengl rendering. Client software which requires procedural rendering must supply implementations of the Search This Doc required call-back functions.
A procedural rendering class is created by a call to: Search All Docs
LtOpenGLProcClass Full Screen LiOpenGLProceduralClassCreate(LtVoid) A pointer to the class record is returned as the value of the function. A class record contains pointers to the class’s call-back functions. These call-back functions are set by the following API call:
LtStatus LiOpenGLProceduralClassSetCallback( LtOpenGLProcClass pclass, LtOpenGLProcClassFunc cback, Lightworks Author LtFunc func) 9.0
Lightworks The allowed call-backs and their prototypes are: Real-time
6.3.1. OpenGL primitive rendering function Advanced usage This function is called by the liopengl module to render the primitive.
Call-back function: LI_OPENGL_PROC_CLASS_CALL_RENDER
Prototype: Master Doc LtStatus (*LtOpenGLFuncProcRender) ( LtPrim prim, LtGenericPtr data, Title Page LtBitfield render_props, LtOpenGLProcRenContext context ); Contents
• prim is the specific primitive which is to be rendered First Last • data is the per-primitive specific data • render_props specifies which of the vertex properties need to be sent to OpenGL J I • context contains rendering specific data which can be used by the call-back
Page 48 of 119 The following bits may be set in the render_props parameter :
Go Back • LI_OPENGL_RENDER_PROP_NORMAL • LI_OPENGL_RENDER_PROP_USE_OWN_COLOUR Search This Doc • LI_OPENGL_RENDER_PROP_CALC_COLOUR
• LI_OPENGL_RENDER_PROP_USE_OWN_TEXCOORD Search All Docs • LI_OPENGL_RENDER_PROP_CALC_TEXCOORD • LI_OPENGL_RENDER_PROP_USE_OWN_TEXDERIV Full Screen • LI_OPENGL_RENDER_PROP_CALC_TEXDERIV • LI_OPENGL_RENDER_PROP_CALC_LIGHTING • LI_OPENGL_RENDER_PROP_TWO_SIDED
Notes:
Lightworks Author 1. The ..._NORMAL property may be included even if the class definition doesn’t specify it. In this 9.0 case the call-back must calculate normals itself. 2. The ..._USE_OWN_COLOUR property will never be included if the class definition doesn’t specify Lightworks it. Real-time 3. The ..._CALC_COLOUR property may be included even if the class definition doesn’t specify it. In this case the colour must be calculated with a call to LiOpenGLProcRenEvalColour.
4. The ..._USE_OWN_TEXCOORD property will never be included if the class definition doesn’t Advanced usage specify it. 5. The ..._CALC_TEXCOORD property may be included even if the class definition doesn’t specify it. In this case the texture coords must be calculated with a call to LiOpenGLEvaluateTex- CoordsInfo. 6. The ..._USE_OWN_TEXDERIV property will only be included if the class definition specifies the Master Doc LI_OPENGL_VERTEX_PROP_TEXCOORD property. If texture derivatives are not available, then they may be calculated using the LiOpenGLEvaluateTexDerivs API function Title Page 7. The ..._CALC_TEXDERIV property may be included even if the class definition doesn’t specify it. In this case the texture derivatives must be calculated with a call to LiOpenGLEvaluate- TexCoordsInfo NB in this case a single call to LiOpenGLEvaluateTexCoordsInfo will Contents calculate both texture coordinates and texture derivatives. 8. The ..._CALC_LIGHTING property may be included. In this case, the colour must be calculated First Last with a call to LiOpenGLProcRenEvalLighting J I A procedural rendering call-back function example is shown in Listing 6.1.
Page 49 of 119 6.3.2. Invalidate primitive cached state function Go Back This function is called when the primitive is invalidated.
Call-back function: LI_OPENGL_PROC_CLASS_CALL_INVALIDATE Search This Doc
Prototype: Search All Docs LtStatus (*LtOpenGLFuncProcInvalidate) ( LtPrim prim, LtGenericPtr data, Full Screen LtBitfield inv_flags ); LtStatus RenderCallback(LtPrim prim, LtGenericPtr data, LtBitfield render_props, LtOpenGLProcRenContext context ) { /* * OpenGL default texture coords. */ Lightworks Author LtColour colour = {1, 1, 1}; 9.0 LtFloat alpha = 1.0; Glfloat gl_colour[4] = {1,1,1,1}; Lightworks glBegin(...); Real-time ... if (render_props & LI_OPENGL_RENDER_PROP_USE_OWN_COLOUR) { glColor3f(my_color); Advanced usage } else if ( render_props & LI_OPENGL_RENDER_PROP_CALC_COLOUR) { LiOpenGLProcRenEvalColour( context, my_vertex, my_normal, colour, &alpha ); gl_colour[0] = colour[LI_R]; gl_colour[1] = colour[LI_G]; Master Doc gl_colour[2] = colour[LI_B]; gl_colour[3] = alpha; glColor4f( gl_colour ); Title Page }
if (vertex_props & LI_OPENGL_VERTEX_PROP_NORMAL) Contents glNormal3f(my_normal);
if (render_props & LI_OPENGL_RENDER_PROP_USE_OWN_TEXCOORD) First Last { glTexCoord2fv(my_texcoord); } else if (render_props & LI_OPENGL_RENDER_PROP_CALC_TEXCOORD) J I { LtOpenGLTexCoords texcoords = NULL; Page 50 of 119 if (LiStatusOk(LiOpenGLTexCoordsCreate(context, &texcoords, TRUE))) { LiOpenGLEvaluateTexCoordsInfo( context, vertex, texcoords ); Go Back LiOpenGLSetTexCoordsInfo( context, texcoords ); LiOpenGLTexCoordsDestroy( context, texcoords ); } Search This Doc }
glVertex3f( my_vertex ); Search All Docs ... glEnd(); } Full Screen
Listing 6.1: Procedural rendering call-back example • prim is the specific primitive which is to be rendered • data is the per-primitive specific data • inv_flags defines the specific cached state to invalidate, which is a combination of the following flags:
– LI_OPENGL_INVALIDATE_GEOMETRY Lightworks Author – LI_OPENGL_INVALIDATE_TRANSFORM 9.0 – LI_OPENGL_INVALIDATE_MATERIAL – LI_OPENGL_INVALIDATE_TEXTURE_SPACE Lightworks – LI_OPENGL_INVALIDATE_CONTEXT Real-time – LI_OPENGL_INVALIDATE_TONE – LI_OPENGL_INVALIDATE_ALL Advanced usage 6.3.3. Primitive destroy function
This function is called when the primitive is destroyed. Master Doc Call-back function: LI_OPENGL_PROC_CLASS_CALL_DESTROY
Prototype: Title Page LtStatus (*LtOpenGLFuncProcDestroy)( LtPrim prim, Contents LtGenericPtr data );
• prim is the specific primitive which is to be rendered First Last • data is the per-primitive specific data J I
6.3.4. Vertex property flags inquiry function Page 51 of 119
This function is use by the liopengl module to query the properties which the procedural rendering class can handle. Go Back
Call-back function: LI_OPENGL_PROC_CLASS_CALL_FLAGS Search This Doc Prototype:
LtBitfield (*LtOpenGLFuncProcFlags) ( Search All Docs LtPrim prim, LtGenericPtr data ); Full Screen
• prim is the specific primitive which is to be rendered • data is the per-primitive specific data
The returned LtBitfield describes which per-vertex properties this class maintains. Defined values for the bit-field are:
• LI_OPENGL_VERTEX_PROP_NONE Lightworks Author 9.0 • LI_OPENGL_VERTEX_PROP_NORMAL • LI_OPENGL_VERTEX_PROP_COLOUR Lightworks Real-time • LI_OPENGL_VERTEX_PROP_TEXCOORD
To attach a procedural class together with application specific, per-primitive data to a primitive, the following API function must be used: Advanced usage
LtStatus LiOpenGLPrimitiveSetProceduralClass(LtPrim prim, LtOpenGLProcClass pclass, LtGenericPtr data) Master Doc
Upon termination of the application, a procedural rendering class can be destroyed with a call to: Title Page
LtStatus LiOpenGLProceduralClassDestroy(LtOpenGLProcClass pclass) Contents
First Last 6.3.5. Procedural rendering context J I The procedural rendering context (of type LtOpenGLProcRenContext) is used to pass relevant information to the rendering routine. Page 52 of 119 Elements of the procedural rendering context may be accessed through the following API function: Go Back LtStatus LiOpenGLProcRenContextQuery( Search This Doc LtOpenGLProcRenContext context, LtEnum query, LtData *data) Search All Docs The context argument must be the same context as passed into the call-back rendering function.
Possible values for query are described in Table 6.1; the relevant result will be returned via the Full Screen data parameter. Query (prefix Data Type Description LI_OPENGL_PROC_REN_QUERY) _PASS LtNat32 The current rendering pass number. the first pass is returned as 0. The pass number indicates which pass in a multi-pass render the module is per- forming, in order to correctly cache colour/texture co-ordinates on a per Lightworks Author pass basis. 9.0 _COLOUR LtFloat[4] The current material average colour _NR_TEXCOORDS LtNat32 The number of texture coordinates to Lightworks calculate. Querying this parameter Real-time gives the number of sets of texture coordinates that will be calculated on a call to LiOpenGLEvaluateTexCo- ords. Advanced usage _CURRENT_TEXCOORD LtNat32 The current texture coordinate to start calculating from. Allows correct caching of texture coordinates as mul- tiple sets of texture coordinates may be required to be calculated for each pass Master Doc Table 6.1: Possible values for query parameter of LiOpenGLProcRenContextQuery Title Page
A set of API functions are available for calculating the colour, texture co-ordinates and lighting values. In general, these functions return values to the caller, instead of sending them to OpenGL Contents directly. This allows the caller can cache them, alter or manipulate them before passing to OpenGL. These API functions are defined over the next couple of pages. First Last Firstly, the API function LiOpenGLProcRenEvalColour evaluates the colour and transparency value at a given vertex: J I
LtStatus LiOpenGLProcRenEvalColour(LtOpenGLProcRenContext context, Page 53 of 119 LtPoint vertex, LtVector normal, LtColour colour, LtFloat alpha) * Go Back
The vertex argument is the co-ordinate of the vertex for which colour and/or texture co-ordinates are needed. normal is the surface normal at the vertex. If the ..._NORMAL vertex property isn’t Search This Doc included, this argument is ignored.
The generated RGB colour is returned in the colour argument, and the alpha transparency value is Search All Docs returned in the alpha argument. Full Screen The function LiOpenGLEvaluateTexCoordsInfo is used to calculate one or more sets of texture coordinates. The texture coordinates are encapsulated in an LtOpenGLTexCoords structure, which must first be created with a call to LiOpenGLTexCoordsCreate.
LtStatus LiOpenGLTexCoordsCreate(LtOpenGLProcRenContext context, LtOpenGLTexCoords* texcoords, LtBoolean alloc_mem) Lightworks Author 9.0 If the alloc_mem parameter is TRUE, then LiOpenGLTexCoordsCreate will automatically allocate enough memory to store all need texture coordinate information for the current pass. Lightworks Passing a value of FALSE will require the application to allocate the memory for the texture coordinate Real-time information. This is useful for efficiently caching texture coordinate information. In this case, the application will have to do a number of things:
Advanced usage • Enquire of the LtOpenGLTexCoords structure the actual texture coordinate data pointer. • Enquire of the LtOpenGLProcRenContext structure the texture info defining the size, texture unit and type of data required. • Allocate the required data and assign to the texture coordinate data pointer Master Doc
The following API function is used to query the LtOpenGLTexCoords structure: Title Page
LtStatus LiOpenGLTexCoordsGet(LtOpenGLTexCoords texcoords, Contents LtEnum query, LtData* data)
First Last Using the query LI_OPENGL_TEXCOORDS_DATA will return a pointer to an array of pointers to GLfloat* elements. J I GLfloat **tex_data;
status |= LiOpenGLTexCoordsGet(TexCoords, LI_OPENGL_TEXCOORDS_DATA, &data); Page 54 of 119
if (LiStatusOk(status)) tex_data = (GLfloat **)LiDataGetGenericPtr(&data); Go Back
The number of elements in the data array can be obtained by querying the LtOpenGLProcRenCon- Search This Doc text, with the LI_OPENGL_PROC_REN_QUERY_NR_TEXCOORDS query. Search All Docs
Full Screen LtNat32 nr_coords;
status |= LiOpenGLProcRenContextQuery( context, LI_OPENGL_PROC_REN_QUERY_NR_TEXCOORDS, &data);
if (LiStatusOk(status)) nr_coords = LiDataGetNat32(&data); Lightworks Author 9.0
The actual size, type and texture unit for each element can be retrieved from the LtOpenGLPro- Lightworks cRenContext with the LI_OPENGL_PROC_REN_QUERY_TEX_INFO query. This will return a pointer to a 2D array of LtNat32 elements, one row for each texture coordinates detailing the size, which Real-time texture unit to bind to, and the type. Once the texture coordinate information, as well as the pointer to the array to hold the data, has been obtained then we can assign the memory to be used in the calculation: Advanced usage LtNat32 **tex_info;
status |= LiOpenGLProcRenContextQuery( context, LI_OPENGL_PROC_REN_QUERY_TEX_INFO, &data); Master Doc if (LiStatusOk(status)) { LtNat32 idx, size, unit; Title Page LtEnum type;
tex_info = (LtNat32 **)LiDataGetGenericPtr(&data); Contents for (idx = 0; idx < nr_coords; idx++) { First Last size = tex_info[idx][LI_OPENGL_TEXCOORDS_INFO_SIZE]; unit = tex_info[idx][LI_OPENGL_TEXCOORDS_INFO_UNIT]; type = (LtEnum)tex_info[idx][LI_OPENGL_TEXCOORDS_INFO_TYPE]; J I /* * Allocate memory, or assign from a predeclared array */ Page 55 of 119 tex_data[idx] = (GLfloat *)LiAllocate(LiSizeOf(GLfloat) * size); } } Go Back
The advantage of this method, is that the texture coordinates can be calculated just once, and Search This Doc cached for reuse in subsequent rendering passes. Additionally, blocks of memory can be allocated to allow for more efficient passing of data to OpenGL (such as with vertex arrays and vertex buffer objects). Search All Docs
Once the memory has been allocated/assigned then the LtOpenGLTexCoord structure can be used in a call to LiOpenGLEvaluateTexCoordsInfo to calculate the texture coordinate information. Full Screen LtStatus LiOpenGLEvaluateTexCoordsInfo( LtOpenGLProcRenContext context, LtPoint vertex, LtVector normal, LtOpenGLTexCoords texcoords) Lightworks Author 9.0 Evaluates all the necessary texture coordinate information for the current rendering pass. Lightworks The structure may be cached, or may be re-used in subsequent calls to LiOpenGLEvaluateTex- CoordsInfo during the current pass. Real-time
The function LiOpenGLSetTexCoordsInfo Passes the texture coordinate information previously calculated by LiOpenGLEvaluateTexCoordsInfo, to OpenGL. Advanced usage LtStatus LiOpenGLSetTexCoords(LtOpenGLProcRenContext context, LtOpenGLTexCoords texcoords)
Once an LtOpenGLTexCoords has been finished with, it may be destroyed with a call to Li- Master Doc OpenGLTexCoordsDestroy: Title Page LtStatus LiOpenGLTexCoordsDestroy(LtOpenGLProcRenContext context, LtOpenGLTexCoords texcoords) Contents
If texture derivatives are needed, as indicated by the _USE_OWN_TEXDERIV property, then the First Last following function can be used to calculate them. (NB: This function should not be used if the calculate texture derivative property is set (_CALC_TEXDERIV). In this case, the call to LiOpenGL- EvaluateTexCoordsInfo will calculate the necessary data.) J I
The _USE_OWN_TEXDERIV property will only be set if the class defines the LI_OPENGL_VERTEX_- PROP_TEXCOORD property. Page 56 of 119
LtStatus Go Back LiOpenGLEvaluateTexDerivs(LtOpenGLProcRenContext context, LtPoint vertices[3], LtVector the_normal, Search This Doc LtFloat the_coords[6], LtOpenGLTexCoords texcoords) Search All Docs
Texture derivatives are calculated on a per triangle basis. Thus the vertices parameter requires 3 vertices making a triangle, the the_normal parameter is the normal for the triangle, the the_coords Full Screen parameter are the texture coords associated with the vertices, and the texcoords parameter is where the calculated texture derivatives will be stored.
The function LiOpenGLProcRenEvalLighting calculates the lit vertex value at the given vertex:
LtStatus LiOpenGLProcRenEvalLighting( LtOpenGLProcRenContext context, Lightworks Author LtPoint vertex, 9.0 LtVector normal, LtColour vertex_colour, Lightworks LtColour lighting) Real-time
6.4. Environment Mapping in Real-time Advanced usage
The Real-time module can make use of environment maps to simulate reflections and advanced lighting. Unless otherwise stated, when an environment map is required, the current global environment map (as specified by LiEnvironmentSet) is used. Master Doc Any change to an environment map, or an environment interface, should be indicated to the real-time module by using LiOpenGLInvalidate with the appropriate flags. Title Page
6.4.1. Material Reflectance Contents
Environment maps may be used when rendering materials, depending upon which mode and what shaders are referenced in the material. First Last
6.4.1.1. Non-programmable shading J I
Page 57 of 119 Environment maps are used when a material contains an "environment" reflectance shader. Spherical environments are supported on all graphics cards. Infinite cube environment maps are only supported if the graphics card supports the GL_ARB_texture_cube extension. Angular and Go Back latitude/longitude environment maps are treated as spherical environment maps.
LtInterface For environment maps created from an only cube maps will support the orientation Search This Doc parameters "twist" and "up".
All environment maps are treated as infinite distance maps for environment reflections. Search All Docs
Full Screen 6.4.1.2. Programmable Shading
Environment maps are not only used with the "environment" reflectance shader, but they are also used for simulating reflections and refractions for other reflectance shaders (for example, "mirror" and "glass").
Under this mode spherical, cube, angular and latitude/longitude maps are all supported. Additionally, Lightworks Author for environment maps created from an LtInterface the orientation parameters "twist" and "up" 9.0 are also supported. Lightworks Spherical and cube environment maps are always treated as infinite distance maps for environment Real-time reflections/refractions. Angular environment maps can be treated as infinite distance maps or fixed distance maps. Latitude/longitude environment maps can be treated as infinite distance maps, fixed distance maps or fixed distance hemisphere maps. For fixed distance hemisphere maps created from an LtInterface the parameter "horizon position" is also supported. Advanced usage
6.4.2. Backgrounds
Currently the "environment" background shader under Real-time supports infinite and fixed distance cubic environment maps as global or local environments. Master Doc
Infinite distance, fixed distance and fixed distance hemisphere latitude/longitude (or panorama) Title Page maps are supported if the graphics card supports the OpenGL Shading Language extension.
NEW Additionally, infinite distance and fixed distance angular maps are supported if the graphics Contents card supports the OpenGL Shading Language extension.
For environment maps created from an LtInterface the orientation parameters "twist" and First Last "up" are supported. For fixed distance hemisphere latitude/longitude maps created from an LtInterface the parameter "horizon position" is also supported. J I
6.4.3. Lighting Page 58 of 119
In programmable shading mode, an "environment" light shader can be added to a scene to provide Real-time Image Based Lighting (IBL) effects. Go Back
Under this mode spherical, cube, angular and latitude/longitude maps are all supported. For environment maps created from an LtInterface the orientation parameters "twist" and "up" Search This Doc are supported.
Spherical and cube environment maps are always treated as infinite distance maps for environment Search All Docs lighting. Angular environment maps can be treated as infinite distance maps or fixed distance maps. Latitude/longitude maps can be treated as infinite distance maps, fixed distance maps or fixed Full Screen distance hemisphere maps. For fixed distance hemisphere maps created from an LtInterface the parameter "horizon position" is supported. Using fixed distance and fixed distance hemisphere maps for Real-time IBL carries a significant computational cost compared to infinite distance maps. Therefore, if you wish to use a latitude/- longitude map or an angular map for environment lighting we recommend that you use an infinite distance map.
To use Lightworks Real-time IBL, the hardware must support programmable shading and must have already been enabled (i.e. LI_CONTROL_OPENGL_ENABLE_PROGRAMMABLE_SHADING set to TRUE or if using a render style, the "programmable shading" parameter set to TRUE). Additionally, the Lightworks Author graphics card must support the Unified Shader Model (DirectX Shader Model 4.0). Often such cards 9.0 will be classified by the card manufacturer as providing support for Direct3D 10 or DirectX 10. Lightworks There are additional arguments in the "real time shaded" or "real time shaded and vec- Real-time tor" render styles to support this feature.
Real-time IBL requires continuous sampling of the environment map and so places a considerable load on the graphics card. To assist with balancing quality versus performance use the render style parameters noted below. Advanced usage
• "environment light quality" - An LtNat32 that controls the different quality levels. Set lower values to give fast, coarse illumination. Set higher values to give smoother illumination, at the cost of slower render times. Master Doc Artefacts from using lower quality values are considerably reduced by using a heavily blurred environment lighting image. Speed is likely to be also increased by using a much smaller image than would be used for reflections. Title Page Two API functions are supplied to assist with resizing and blurring of HDR images:
LtStatus Contents LiHDRIImageResize(LtImage img, LtNat32 new_width, LtNat32 new_height, LtImage* image_out) First Last and
LtStatus J I LiHDRIImageBlur(LtImage img, LtNat32 h_blur, LtNat32 v_blur, LtBoolean h_repeat, LtBoolean v_repeat) Page 59 of 119
• "environment light max angle" - An LtFloat that controls how widely we sample the environment map when calculating the illumination from an "environment" light. Setting the Go Back maximum value of 90.0 degrees means we take samples across a full hemisphere above each shading point. This gives the most physically realistic result, however a high quality setting may be needed to give smooth illumination. Setting a lower value can give a better appearance Search This Doc with lower quality settings, at the expense of physical accuracy.
• "environment light intensity" - An LtFloat that adjusts the relative intensity of the Search All Docs "environment" light in programmable shading, versus the "intensity" of the light itself. If "environment" lights appear darker in Real-time rendering than in software rendering, set a value greater than 1.0 to brighten up the Real-time lighting. If they appear brighter in Real-time Full Screen rendering than in software rendering, set a value less than 1.0 to reduce the intensity of the Real-time lighting. For rendering not using the Real-time render styles, the render style parameters map directly onto equivalent control variables in the Lightworks Real-time module. These are:
Render Style Parameter Control Variable (prefix LI_CONTROL_OPENGL) environment light quality _ENVIRONMENT_LIGHT_QUALITY environment light max angle _ENVIRONMENT_LIGHT_MAX_ANGLE environment light intensity _ENVIRONMENT_LIGHT_INTENSITY Lightworks Author 9.0
Lightworks 6.5. User Defined Clipping Planes Real-time
In addition to the standard clipping planes provided by the view frustum, up to 6 user defined clipping planes can also be specified to clip the scene. User defined clipping can be enabled using the LI_CONTROL_OPENGL_USER_CLIPPING_PLANES control variable. When user defined clipping Advanced usage is enabled, then all defined clipping planes will be used.
A clipping plane can be defined with the following API function:
LtStatus Master Doc LiOpenGLClipPlaneSet(LtEnum clip_plane, LtDouble* plane_eqn) Title Page
Where clip_plane is one of: Contents • LI_OPENGL_CLIP_PLANE0 • LI_OPENGL_CLIP_PLANE1 First Last • LI_OPENGL_CLIP_PLANE2 J I • LI_OPENGL_CLIP_PLANE3
• LI_OPENGL_CLIP_PLANE4 Page 60 of 119 • LI_OPENGL_CLIP_PLANE5 Go Back and plane_eqn is the plane equation for the required clipping plane, specified as a 4 component vector (A, B, C, D) satisfying the equation Ax + By + Cz + D = 0. Passing a NULL pointer as the plane equation will disable the corresponding clipping plane. Search This Doc
To retrieve a previously set clipping plane equation, then the following API function can be used: Search All Docs
LtStatus LiOpenGLClipPlaneGet(LtEnum clip_plane, Full Screen LtDouble* plane_eqn) The relevant plane equation will be returned as plane_eqn, which must be a pointer to a 4 component LtDouble array. If no equation has been set, the the value (0.0, 0.0, 0.0, 0.0) will be returned.
Whilst the Real-time module allows a maximum of 6 clipping planes to be defined at any one time, the actual maximum number of clipping planes which can be used is dependent on the graphics card. The LI_OPENGL_QUERY_MAX_CLIP_PLANES query can be used to determine this value. Lightworks Author 9.0 6.6. User Defined Line Types Lightworks Real-time
The following functions allow access to OpenGL’s line stipple functionality. When the _LINE_STYLE control variable is enabled, then poly-lines and/or meshes rendered in _EDGE mode will be drawn with the corresponding line pattern. Advanced usage
LtStatus LiOpenGLLineStippleSet(LNat32 factor, LtNat16 pattern)
The factor and pattern parameters are exactly the same as for the OpenGL glLineStipple() Master Doc function. See the OpenGL Reference Manual for more information on line stipple patterns.
There are 4 predefined line styles: Title Page
• LI_OPENGL_LINE_STIPPLE_LONG_DASH Contents • LI_OPENGL_LINE_STIPPLE_MEDIUM_DASH • LI_OPENGL_LINE_STIPPLE_SHORT_DASH First Last
• LI_OPENGL_LINE_STIPPLE_DOT J I The following function can be used to retrieve the current values for line stippling: Page 61 of 119
LtStatus LiOpenGLLineStippleGet(LNat32* factor, LtNat16* pattern) Go Back
Search This Doc 6.7. Hidden Line Rendering Search All Docs Hidden Line rendering is exposed through the "hidden line" parameter of the "real time shaded and vector" render style. Full Screen Real-time hidden-line rendering can be achieved through the Core API by using the LiOpenGLRen- derHiddenLine API method, or using the LI_EXECUTE_REN_OPENGL_HIDDEN_LINE execute mode.
6.8. Anti-aliasing Lightworks Author 9.0 Multisampled anti-aliasing is supported by the Real-time module. Note that this requires the Graphics hardware to be support Multisampling (that is, the GL_ARB_multisample extension must Lightworks be supported). Real-time
Anti-aliasing in Real-time is enabled in two stages:
• Firstly, the number of samples per pixel must be set, via the LI_CONTROL_OGLDRV_- Advanced usage ANTIALIAS_SAMPLES control var. This control variable must be set before any rendering to the window is performed. If the real-time module is run in _CURRENT window mode, then it is up to the application to create a suitable render context which supports multisampling. • Secondly, Multisampled Anti-aliasing must be enabled by setting the control variable LI_- CONTROL_OPENGL_ANTIALIAS to TRUE. Master Doc
Title Page 6.9. Gamma Correction Contents A Gamma Correction factor can now be applied to real-time output, to help compensate for the non-linear response of display devices. In non-programmable real-time, this correction factor is an approximation, as colours and textures will be gamma corrected before shading. In programmable First Last shading mode, the gamma correction factor wil be properly applied after all shading calculations.
Gamma correction in real-time is enabled in the following way: J I
• Set the control variable LI_CONTROL_OPENGL_APPLY_GAMMA_CORRECTION to TRUE. Page 62 of 119 • Set the control variable LI_CONTROL_OPENGL_GAMMA_CORRECTION_FACTOR to the required gamma correction factor (this defaults to 1.0 which implies no gamma correction is to be Go Back performed)
Search This Doc 6.10. Accessing OpenGL extensions Search All Docs
Two new API functions are provided to facilitate access to OpenGL extension functionality. These functions are provided by the liogldrv module. Full Screen LtStatus LiOGLDrvExtensionQuery(LtString name)
This function checks if the given extension is available in the current rendering context. If no rendering context has been set (for example, if the function is called before LiOpenGLImageBegin, it will return LI_STATUS_NOT_INITIALISED. If a rendering context has been set, then the function Lightworks Author will return LI_STATUS_OK if the extension is supported, otherwise LI_STATUS_UNSUPPORTED. 9.0
LtStatus Lightworks LiOGLDrvExtensionGetFunction(LtString name, LtFunc *func) Real-time
This function will retrieve the function pointer for the requested extension function for the current context. Advanced usage
typedef LtVoid (APIENTRY * LtFuncGLActiveTextureARB)(GLenum target); { LtFuncGLActiveTextureARB glActiveTextureARB; LtStatus status;
status = LiOGLDrvExtensionQuery("GL_ARB_multitexture"); Master Doc
if (LiStatusOk(status)) { Title Page status |= LiOGLDrvExtensionGetFunction( "glActiveTextureARB", (LtFunc *)&glActiveTextureARB); Contents
if ( LiStatusOk(status) ) { First Last glActiveTextureARB(GL_TEXTURE0_ARB); } } } J I
Page 63 of 119 6.11. Mixing liopengl and OpenGL API calls Go Back
Direct calls to OpenGL can be mixed with liopengl calls if some care is taken. liopengl only binds a rendering context between LiOpenGLImageBegin and LiOpenGLImageEnd. This has two Search This Doc consequences: Search All Docs • An application can make OpenGL calls for its own rendering contexts at any time outside an LiOpenGLImageBegin / LiOpenGLImageEnd pair. The calls do not interfere. Full Screen • An application that wishes to make direct OpenGL calls to the same rendering context as liopengl must do so between an LiOpenGLImageBegin / LiOpenGLImageEnd pair. When making direct OpenGL calls to the same rendering context as liopengl, the application must make sure that it does not make any unexpected changes to OpenGL state. Conversely, the application must not assume that OpenGL state will be left unchanged after an liopengl API call. The safest approach is to use glPushAttrib and glPopAttrib around application OpenGL calls and to explicitly set any state required at the beginning of the calls.
Lightworks Author 6.12. Screen Space Ambient Occlusion 9.0 Lightworks Ambient Occlusion produces a more realistic look to ambient lighting in a scene. Real-time
The Ambient Occlusion technique, implemented in Lightworks Real-time is a Screen Space method that is an approximation calculated in image space from the scene’s depth buffer. It is implemented as a post-process, which is then blended into the final scene. Advanced usage
6.12.1. SSAO Requirements
To use Lightworks Real-time Ambient Occlusion, the hardware must support programmable shading Master Doc and must have already been enabled (i.e. LI_CONTROL_OPENGL_ENABLE_PROGRAMMABLE_- SHADING set to TRUE or if using a render style, the "programmable shading" parameter set to TRUE). Title Page
Additionally, the following OpenGL extensions are required: Contents • GL_ARB_framebuffer_object • GL_ARB_color_buffer_float First Last • GL_ARB_draw_buffers J I (If SSAO is enabled, but the Graphics Hardware cannot support it, then a diagnostic will be issued). Page 64 of 119
6.12.2. Using SSAO Go Back
To enable Ambient Occlusion, set the "ambient occlusion mode" render style parameter to LI_OPENGL_AO_MODE_SSAO. The default is for SSAO to be disabled: LI_OPENGL_AO_MODE_NONE. Search This Doc
Once enabled, the SSAO technique has a number of controls that can tailor the behaviour. Search All Docs
• "ambient occlusion quality" - An LtEnum that controls the different quality levels for SSAO. Note, this control also affects performance. The lower the quality, the higher the Full Screen performance. Additionally, some graphics cards may fail to render at high quality levels— unfortunately, this has been shown to be unpredictable. – LI_OPENGL_AO_QUALITY_LOW - Uses a half-size buffer with coarse sampling. – LI_OPENGL_AO_QUALITY_MEDIUM - Uses a half-size buffer with finer sampling. – LI_OPENGL_AO_QUALITY_HIGH - Uses a full-sized buffer with higher resolution sam- pling. – LI_OPENGL_AO_QUALITY_VERY_HIGH - Uses a full-sized buffer with extremely fine sampling. Lightworks Author – LI_OPENGL_AO_QUALITY_HIGHEST - Uses a double-size buffer with extremely fine 9.0 sampling. – LI_OPENGL_AO_QUALITY_TILED - Uses a quad-size buffer with extremely fine sampling. Lightworks To achieve this, the buffer is sub-divided into tiles before passing to the graphics card. Real-time Note that users should expect a performance reduction for this increase in quality compared to other modes. Navigation frame-rate may be compromised and so this mode could be used as a final pass, when no navigation is in progress, or when printing from the screen. Advanced usage • "ambient occlusion radius" - An LtFloat that controls the maximum distance from a point to be considered for occlusion. This defines the physical size of the effect, and so is model dependant.
• "ambient occlusion contrast" - An LtFloat that can lighten or darken the AO effect. Master Doc • "ambient occlusion display" - An LtEnum to define how the AO buffer is to be displayed: Title Page – LI_OPENGL_AO_DISPLAY_AO_ONLY - Display just the AO buffer. – LI_OPENGL_AO_QUALITY_POSTPROCESS_BLEND - Blend the ambient occlusion buffer over the rendered image. Contents
• "ambient occlusion blur radius" - An LtFloat that controls the radius, in pixels, of blurring of the ambient occlusion effect from the point of calculation. Set smaller values to pick First Last out detail more sharply, for example, spokes on a bicycle wheel may require values less than 2. Set larger values to allow the effect to blur softly, for example, a wall corner may require values nearer 5. J I • "ambient occlusion tile border" - An LtFloat that controls the size of the border region used in Tiled SSAO. This parameter has no effect unless "ambient occlusion quality" is Page 65 of 119 set to LI_OPENGL_AO_QUALITY_TILED. Set smaller values, for example 0.1, to reduce the amount of memory required to render a scene. Set larger values, for example 0.8, to remove any discontinuities between neighbouring tiles, at the cost of higher memory usage. Go Back
For rendering not using the Real-time render styles, the render style parameters map directly onto Search This Doc equivalent control variables in the Lightworks Real-time module. These are:
Search All Docs
Full Screen Render Style Parameter Control Variable (prefix LI_CONTROL_OPENGL) ambient occlusion mode _AMBIENT_OCCLUSION_MODE ambient occlusion quality _AMBIENT_OCCLUSION_QUALITY ambient occlusion radius _AMBIENT_OCCLUSION_RADIUS ambient occlusion contrast _AMBIENT_OCCLUSION_CONTRAST ambient occlusion display _AMBIENT_OCCLUSION_DISPLAY ambient occlusion blur radius _AMBIENT_OCCLUSION_BLUR_RADIUS Lightworks Author ambient occlusion tile border _AMBIENT_OCCLUSION_TILE_BORDER 9.0
Lightworks 6.12.3. Caveats Real-time
The SSAO implementation only uses a single layer of depth information, so artifacts are common at the viewport edges and where geometry is covered by other geometry. This is because of a lack of appropriate depth information. Advanced usage
6.13. Stereoscopic Rendering
Master Doc Stereoscopic Rendering allows a scene to be visualised in 3D, producing a more realistic and immersive experience. Title Page The Lightworks Real-time module uses quad buffered OpenGL rendering to create images of a scene suitable for 3D stereoscopic display. The scene must be rendered twice at each viewpoint, in order to generate separate images that can be displayed to the left and right eyes. Contents
6.13.1. Stereo Requirements First Last
To use Lightworks Real-time Stereoscopic Rendering, the graphics hardware must support quad J I buffered OpenGL render contexts. OpenGL Stereo may need to be enabled in the graphics driver control panel before a suitable context can be created. Consult your graphics hardware documentation for more details. If a quad buffered OpenGL context cannot be created, Lightworks Page 66 of 119 Real-time Stereoscopic Rendering will be disabled. Go Back Additionally, a 3D-compatible display device is required to view 3D stereoscopic images.
Search This Doc 6.13.2. Using Stereo
Search All Docs Before rendering can begin, an OpenGL render context that supports quad buffered stereo must be set, using the LI_CONTROL_OGLDRV_STEREO_BUFFERS control variable. This control variable must be set before any rendering to the window is performed. If the Real-time module is run in _CURRENT Full Screen window mode, then it is up to the application to create a suitable render context that supports quad buffered stereo. To generate a stereoscopic 3D image using quad buffered stereo, a scene must be rendered from two different viewpoints, into two different OpenGL buffers. When Stereoscopic Rendering is enabled, the Lightworks Real-time module will configure the stereo viewpoints and OpenGL buffers automatically. An application simply needs to perform two renders using its existing rendering method and non-stereo view, with the LI_CONTROL_OPENGL_STEREO_MODE control variable set to indicate which viewpoint should be used in each render. The first render of each pair must use the left-eye viewpoint, and the second render must use the right-eye viewpoint. Lightworks Author For example, an application that uses LiRenderStyleExecute with an appropriate real-time style, 9.0 could perform a stereo render using the following code: Lightworks LtData data; Real-time
LiViewSet( original_view );
LiDataSetEnum( &data, LI_OPENGL_STEREO_MODE_LEFT ); Advanced usage LiControlSet( LI_CONTROL_OPENGL_STEREO_MODE, &data ); LiRenderStyleExecute( real_time_style );
LiDataSetEnum( &data, LI_OPENGL_STEREO_MODE_RIGHT ); LiControlSet( LI_CONTROL_OPENGL_STEREO_MODE, &data ); LiRenderStyleExecute( real_time_style ); Master Doc
Applications that use the ’object level’ or ’primitive level’ API can take a similar approach by setting LI_CONTROL_OPENGL_STEREO_MODE before calling LiOpenGLImageBegin, as follows: Title Page
Contents
First Last
J I
Page 67 of 119
Go Back
Search This Doc
Search All Docs
Full Screen LtData data; LtNat32 pass, nr_passes;
LiViewSet( original_view );
LiDataSetEnum( &data, LI_OPENGL_STEREO_MODE_LEFT ); LiControlSet( LI_CONTROL_OPENGL_STEREO_MODE, &data ); Lightworks Author LiOpenGLImageBegin(); 9.0 LiOpenGLViewSet( LI_VIEW_CURRENT ); LiOpenGLBackgroundSet( NULL ); Lightworks LiOpenGLLightListSet( NULL ); LiOpenGLToneListSet( NULL ); Real-time nr_passes = LiOpenGLSceneGetNumPasses(); for ( pass = 0; pass < nr_passes; pass++ ) { LiOpenGLSceneBeginPass( pass ); Advanced usage LiOpenGLPrimitiveListRender( NULL ); LiOpenGLSceneEndPass( pass ); } LiOpenGLImageEnd();
LiDataSetEnum( &data, LI_OPENGL_STEREO_MODE_RIGHT ); LiControlSet( LI_CONTROL_OPENGL_STEREO_MODE, &data ); Master Doc
LiOpenGLImageBegin(); LiOpenGLViewSet( LI_VIEW_CURRENT ); Title Page LiOpenGLBackgroundSet( NULL ); LiOpenGLLightListSet( NULL ); LiOpenGLToneListSet( NULL ); Contents nr_passes = LiOpenGLSceneGetNumPasses(); for ( pass = 0; pass < nr_passes; pass++ ) { First Last LiOpenGLSceneBeginPass( pass ); LiOpenGLPrimitiveListRender( NULL ); LiOpenGLSceneEndPass( pass ); } J I LiOpenGLImageEnd(); Page 68 of 119
6.13.2.1. View manipulation in stereo rendering Go Back
During Stereoscopic Rendering, the Lightworks Real-time module will temporarily replace the current Search This Doc view object with a modified view suitable for generating a stereo 3D image. Applications that use LiRenderStyleExecute do not need to alter their view manipulation code - simply set the current LiViewSet (non-stereoscopic) view as usual by calling before performing the two stereo renders. Search All Docs Note that the application should not change the view between the left-eye and right-eye renders.
Applications that use the ’object level’ or ’primitive level’ API and pass a specific LtView object to Full Screen LiOpenGLViewSet, rather than using the current view, will need to alter their code for Stereoscopic Rendering. The application’s chosen view object should be set as the current Lightworks view, using LiViewSet, before performing the two stereo renders. The application should not change the view between the left-eye and right-eye renders.
During Stereoscopic Rendering, calling LiOpenGLImageBegin will retrieve the current Lightworks view object, extract its parameters and use them to construct a stereo view object. The stereo view object is then temporarily set as the current view for the duration of the render. It is assumed that LiOpenGLViewSet will be called with the parameter LI_VIEW_CURRENT, so that it will use this stereo view. If not, the stereoscopic image will not be rendered correctly. The original view object is Lightworks Author restored when LiOpenGLImageEnd is called. 9.0 Lightworks 6.13.2.2. Display of stereo images Real-time
During Stereoscopic Rendering, the front and back buffers will not be swapped after the first, left-eye render. The Lightworks Real-time module will hold back the first image until the second, right-eye Advanced usage render is complete. The front and back buffers will then be swapped (unless LI_CONTROL_- OPENGL_HOLD_IMAGE is set to TRUE), so that both parts of the stereo 3D image are displayed at the same time. This is necessary to prevent the screen from displaying conflicting images to the viewer’s left and right eyes.
Master Doc 6.13.3. Controlling the Stereo Effect Title Page Lightworks Real-time Stereoscopic Rendering will automatically calculate values for certain internal parameters that affect the appearance of stereoscopic 3D images. Using these default values should produce good-quality 3D images of most scenes. In case the default values do not produce the Contents desired result, the following two control variables (and associated render style arguments) can be used to adjust the 3D stereoscopic effect: First Last
• LI_CONTROL_OPENGL_STEREO_DISTANCE_FACTOR (LtDouble) Controls the apparent distance of the 3D model from the viewer. Smaller values (between 0.0 J I and 1.0) will make the model appear closer to the viewer. Larger values (greater than 1.0) will make the model appear to be farther from the viewer. Values less than or equal to 0.0 are not Page 69 of 119 valid. The default value is 1.0 This control variable maps to the "stereo distance factor" argument of the "real time shaded", "real time vector" and "real time shaded and vector" render Go Back styles.
• LI_CONTROL_OPENGL_STEREO_3D_FACTOR (LtDouble) Search This Doc Controls the strength of the 3D depth effect. Smaller values (between 0.0 and 1.0) will weaken the effect, making the scene appear more like a flat 2D image. Larger values (greater than 1.0) will strengthen the 3D effect. Values less than or equal to 0.0 are not valid. Reducing Search All Docs the strength of the 3D depth effect will reduce the likelihood of eyestrain or headaches when viewing scenes in 3D. The default value is 1.0 Full Screen This control variable maps to the "stereo 3D factor" argument of the "real time shaded", "real time vector" and "real time shaded and vector" render styles. 6.13.4. Caveats
Lightworks Real-time Stereoscopic Rendering requires a scene to be fully rendered twice before the stereo 3D image can be displayed. As such, it is not compatible with incremental rendering techniques such as Lightworks Real-time Plus . Lightworks Author 9.0
Lightworks Real-time
Advanced usage
Master Doc
Title Page
Contents
First Last
J I
Page 70 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 7 Lightworks Author 9.0
Lightworks Using Lightworks materials with your Real-time own interactive rendering (via the Using Lightworks materials with your Material API) own interactive rendering (via the Material API)
Master Doc
Title Page
Access to the liopengl module’s material processing functionality is provided through the following Contents set of API functions. These allow an application to use the OpenGL representation of a Lightworks material outside of the standard liopengl rendering framework. First Last If you do not have your own interactive rendering framework then you should perform interactive rendering via Lightworks, as discussed in Section 5.1, and skip this Section completely. J I Note: The use of the Material API is dependent upon several factors.
Page 71 of 119 • There must be a valid OpenGL rendering context set when calling any of the following functions. If the context changes at all, then the Real-time module needs to be informed by calling LiOpenGLInvalidateState with the LI_OPENGL_INVALIDATE_STATE_CONTEXT Go Back bit set. • A valid view needs to be set with the LiOpenGLViewSet API function. Once a view has been Search This Doc set, it need not be set again unless a new LtView is to be used. • A light list must be set using LiOpenGLLightListSet. This light list will be used for calculating lighting in standard OpenGL and will be used in the creation of a programmable Search All Docs material representation when in programmable shading mode. Once a light list has been set, then it will be used until a new light list is set. Full Screen
The above conditions need to be set before calling any of the Material API functions. 7.1. Creating an OpenGL material from a Lightworks material
The following function:
LtOpenGLMaterial LiOpenGLMaterialCreate(LtMaterial material) Lightworks Author 9.0 creates a new OpenGL material representation (of type LtOpenGLMaterial) from a Lightworks Lightworks material representation (LtMaterial). Real-time The function:
LtStatus LiOpenGLMaterialDestroy(LtOpenGLMaterial gl_material) Using Lightworks materials with your own interactive destroys an LtOpenGLMaterial object. Note: There must be a valid OpenGL context set, which rendering (via the shares state with the context used for the creation of the material object, to be able to delete texture Material API) objects, display list etc. Master Doc
7.2. Querying an OpenGL Material Title Page
The following API functions can be used to enquire certain information of the OpenGL Material. Contents
LtStatus First Last LiOpenGLMaterialGet(LtOpenGLMaterial gl_mat, LtEnum param, LtData* data) J I
LtStatus Page 72 of 119 LiOpenGLMaterialSet(LtOpenGLMaterial gl_mat, LtEnum param, LtData* data) Go Back
The following parameters can be used to enquire or set certain state of an OpenGL material. Those parameters marked as read-only (R) can only be used with LiOpenGLMaterialGet, and those Search This Doc marked write-only (W) can only be used with LiOpenGLMaterialSet.
Search All Docs
Full Screen Param (LI_OPENGL_MATERIAL..) Data Type R/W Notes _TYPE LtEnum R Returns the type of the given OpenGL Material: • LI_OPENGL_MATERIAL_TYPE_OPENGL— Standard nonprogrammable OpenGL material. • LI_OPENGL_MATERIAL_TYPE_CG— Programmable material using the Cg Lightworks Author language. 9.0 • LI_OPENGL_MATERIAL_TYPE_GLSL— Programmable material using the OpenGL Shading Language. Lightworks • LI_OPENGL_MATERIAL_TYPE_CGFX—A Real-time CgFX material .
_CGFX_EFFECT CGeffect R Returns the current effect object for the material. _CGFX_TECHNIQUE CGeffect R Returns the current technique object for the ma- Using Lightworks terial. materials with your _CGFX_TECHNIQUE_NAME CGeffect R Returns the current technique name for the ma- terial, or selects a specific technique when used own interactive with LiOpenGLMaterialSet. rendering (via the _CGFX_TECHNIQUE_NAMES CGeffect R/W Returns the names of all the available techniques Material API) for the material as a NULL terminated array of strings. Master Doc _CGFX_TEXTURE_PARAMETER CGeffect W Used to invalidate a texture parameter when the texture resource associated with it has been changed. Title Page
NB: All the LI_OPENGL_MATERIAL_CGFX_... parameters are only applicable to materials of type Contents _CGFX.
First Last 7.3. Using an OpenGL Material definition J I
The OpenGL material representation is used to setup the OpenGL state ready for rendering. The following functions do the state initialisation. Note that the LiOpenGLMaterialGetNumPasses Page 73 of 119 API function must always be called first. Go Back The function:
LtNat32 Search This Doc LiOpenGLMaterialGetNumPasses( LtOpenGLMaterial gl_material) Search All Docs returns the number of rendering passes required to render material. Full Screen The function: LtOpenGLProcRenContext LiOpenGLMaterialBeginPass(LtOpenGLMaterial gl_material, LtShader texture_space, LtNat32 pass, LtBitfield * render_props) Lightworks Author begins a specified rendering pass for this material. The corresponding OpenGL materials and 9.0 textures will be set up, and a LtOpenGLProcRenContext will be returned for the application to use (as for procedural rendering). The LtOpenGLProcRenContext returned is valid until Lightworks LiOpenGLMaterialEndPass is called. The render_props parameter must be initialised to inform the liopengl module what vertex properties are available (such as colour or texture Real-time coordinates). The bit-field values are the same as for procedural rendering:
• LI_OPENGL_VERTEX_PROP_NONE Using Lightworks • LI_OPENGL_VERTEX_PROP_NORMAL materials with your own interactive • LI_OPENGL_VERTEX_PROP_COLOUR rendering (via the Material API) • LI_OPENGL_VERTEX_PROP_TEXCOORD Master Doc Additionally, the following bit can be specified to indicate that the geometry is double sided: Title Page • LI_OPENGL_PRIM_PROP_TWO_SIDED Contents The function also returns render_props, which defines what properties need to be sent to OpenGL (vertex colours, tex coords, normals) in the same way as described for procedural rendering previously. Note that this means that the render_props value is overwritten, and so must be reset First Last for every render pass.
The function: J I
LtStatus Page 74 of 119 LiOpenGLMaterialEndPass(LtOpenGLMaterial gl_material)
Go Back ends the current rendering pass.
Search This Doc 7.4. Invalidating materials Search All Docs
Material state may also be invalidated using the following function: Full Screen LtStatus LiOpenGLMaterialRepInvalidate( LtOpenGLMaterial gl_material, LtBitfield inv_flags)
This function informs the liopengl module that the given material representation has changed in Lightworks Author some way. The inv_flags parameter comprises a combination of the following flags: 9.0
• LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_PARAMS Lightworks Real-time • LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_SHADER • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_PARAMS
• LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_SHADER Using Lightworks • LI_OPENGL_MATERIAL_INVALIDATE_REFLECTANCE_PARAMS materials with your own interactive • LI_OPENGL_MATERIAL_INVALIDATE_REFLECTANCE_SHADER rendering (via the Material API) • LI_OPENGL_MATERIAL_INVALIDATE_DISPLACEMENT_PARAMS Master Doc • LI_OPENGL_MATERIAL_INVALIDATE_DISPLACEMENT_SHADER • LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE_PARAMS Title Page • LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE_SHADER
• LI_OPENGL_MATERIAL_INVALIDATE_VERTEX_PARAMS Contents • LI_OPENGL_MATERIAL_INVALIDATE_VERTEX_SHADER • LI_OPENGL_MATERIAL_INVALIDATE_PIPELINE_PARAMS First Last • LI_OPENGL_MATERIAL_INVALIDATE_PIPELINE_SHADER
• LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_SCALE J I • LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY_SCALE Page 75 of 119 • LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_SPACE
Go Back _PARAMS indicates that a parameter on the appropriate shader has been changed, and any cached data will need to be updated. _SHADER indeicates that the given shader has changed, and the material should be updated to reflect this change. COLOUR_SCALE invalidates any cached Search This Doc data derived from the scale parameter of a material’s colour shader. TRANSPARENCY_SCALE invalidates any cached data derived from the scale parameter of a material’s transparency shader. TEXTURE_SPACE invalidates any cached data derived from the material’s Texture Space shader. Search All Docs
Full Screen 7.5. Blended materials
The following function:
LtBoolean LiOpenGLMaterialIsBlend(LtOpenGLMaterial gl_material) Lightworks Author 9.0
Returns TRUE if the material requires a blending operation and so should be rendered last. For exam- Lightworks ple, A material with a transparent shader defined, and LI_CONTROL_OPENGL_TRANSPARENCY_MODE set to LI_OPENGL_TRANSPARENCY_BLEND. Real-time
7.6. Invalidating the OpenGL state Using Lightworks materials with your own interactive The following function: rendering (via the Material API)
LtStatus Master Doc LiOpenGLInvalidateState(LtBitmask invalidate_bits)
Title Page informs liopengl that the application has independently changed some part of the OpenGL state. liopengl should re-send the affected parts of the state if necessary. Allows efficient mixing of (for liopengl example) and application materials. Contents Allowable bits for invalidate_bits are: First Last • LI_OPENGL_INVALIDATE_STATE_MATERIAL • LI_OPENGL_INVALIDATE_STATE_TEXTURE_OBJ J I • LI_OPENGL_INVALIDATE_STATE_TRANSPARENCY • LI_OPENGL_INVALIDATE_STATE_LIGHTING Page 76 of 119 • LI_OPENGL_INVALIDATE_STATE_CONTEXT Go Back Notes: Search This Doc 1. The ..._MATERIAL bit should be used whenever some material property has been altered (such as diffuse, specular, shininess etc) Search All Docs 2. The ..._TEXTURE_OBJ bit should be used if the texturing environment has changed (such as a new texture object has been bound). Full Screen 3. The ..._TRANSPARENCY bit should be used if any the GL_BLEND, GL_ALPHA_TEST or GL_- POLYGON_STIPPLE states have been altered. 4. The ..._LIGHTING bit should be used, if any lighting properties have been changed 5. The ..._CONTEXT bit should be used, if the underlying window rendering context has been changed (should only be needed in _CURRENT window mode or when using the Material API.
Listing 7.1: Using liopengl Material API /* Lightworks Author * myPrim is a structure of vertices, normals, OpenGL Material 9.0 * and texture space */ typedef struct { Lightworks LtPoint *verts; Real-time LtVector *norms; LtOpenGLMaterial glMat; LtShader texspace; } myPrim; Using Lightworks myPrim PrimList[10]; materials with your own interactive rendering (via the LtVoid Material API) myCreatePrimList( LtVoid ) { /* Master Doc * ladsMaterial1 and ladsMaterial2 are previously created * Lightworks Materials / * Title Page glMat1 = LiOpenGLMaterialCreate( ladsMaterial1 ); glMat2 = LiOpenGLMaterialCreate( ladsMaterial2 );
mat1Texspace = LiShaderCreate( Contents LI_SHADER_CLASS_TEXTURE_SPACE, "y plane" ); mat2Texspace = LiShaderCreate( LI_SHADER_CLASS_TEXTURE_SPACE, "y plane" ); First Last
primList[0].verts = poly1_vert; primList[0].norms = poly1_norm; J I primList[0].glMat = glMat1; primList[0].texspace = mat1Texspace; primList[1].verts = poly2_vert; Page 77 of 119 primList[1].norms = poly2_norm; primList[1].glMat = glMat2; primList[1].texspace = mat2Texspace; primList[2].verts = poly3_vert; Go Back primList[2].norms = poly3_norm; primList[2].glMat = glMat1; primList[2].texspace = mat1Texspace; Search This Doc }
LtVoid Search All Docs myRenderOpenGL( LtVoid ) { myPrim *toRender[10]; /* max of 10 prims to render last */ Full Screen LtNat32 toBlend, nr_passes, pass, idx; LtBitfield render_props; LtOpenGLProcRenContext context = NULL; toBlend = 0;
/* liopengl function calls are used here, but are not necessary. * Standard OpenGL calls can be substituted to set up a * rendering context, view, clear the buffers and enable lights Lightworks Author */ 9.0 LiOpenGLImageBegin(); LiOpenGLViewSet( NULL ); LiOpenGLBackgroundSet( NULL ); Lightworks LiOpenGLLightListSet( NULL ); Real-time for (idx = 0; idx < NR_PRIMS; idx++) { if ( LiOpenGLMaterialIsBlend( primList[idx].glMat ) ) { Using Lightworks toRender[toBlend++] = &primList[idx]; materials with your continue; own interactive } rendering (via the nr_passes = LiOpenGLMaterialGetNumPasses( Material API) primList[idx].glMat ); for ( pass = 0; pass < nr_passes; pass++ ) Master Doc { render_props = LI_OPENGL_VERTEX_PROP_NORMAL; context = LiOpenGLMaterialBeginPass( primList[idx].glMat, Title Page primList[idx].texspace, pass, &render_props); /* Contents * myRenderPolygon() simply sends the geometry to OpenGL */ myRenderPolygon( primList[idx].verts, First Last primList[idx].norms, render_props, context ); LiOpenGLMaterialEndPass( primList[idx].glMat ); } J I } for (idx = 0; idx < toBlend; idx++) Page 78 of 119 { nr_passes = LiOpenGLMaterialGetNumPasses( toRender[idx]->glMat ); for ( pass = 0; pass < nr_passes; pass++ ) Go Back { render_props = LI_OPENGL_VERTEX_PROP_NORMAL; context = LiOpenGLMaterialBeginPass( Search This Doc toRender[idx]->glMat, toRender[idx]->texspace, pass, &render_props ); Search All Docs myRenderPolygon( toRender[idx]->verts, toRender[idx]->norms, render_props, context ); Full Screen LiOpenGLMaterialEndPass( toRender[idx]->glMat ); } } LiOpenGLImageEnd(); }
Lightworks Author 9.0
Lightworks Real-time
Using Lightworks materials with your own interactive rendering (via the Material API)
Master Doc
Title Page
Contents
First Last
J I
Page 79 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 8 Lightworks Author 9.0
Lightworks Programmable shading Real-time
Programmable shading
Master Doc The Lightworks Real-time module supports programmable shading using the nVidia Cg language and the OpenGL Shading Language. Title Page Enabling programmable shading allows the Real-time module to generate a far more realistic representation of the Lightworks material. Procedural shaders can be evaluated on a per pixel basis, and far greater lighting realism is possible, by moving the lighting calculation from a per vertex Contents operation to be done per pixel.
To enable programmable shading three conditions must be met: First Last
• The Graphics Card must support the proper OpenGL extensions (currently only nVidia J I GeForceFX and QuadroFX based graphics boards are supported for Cg, and 3DLabs’ WildCat Realizm series and ATI’s FireGL Series for OpenGL Shading Language Support). Windows only. Page 80 of 119 • If using the Cg Language the the Cg runtime DLLs must be installed, and the directory containing the DLLs must be included in the PATH environment variable. (N.B., Appropriate Go Back Cg runtime DLLs, cg.dll and cgGL.dll can be found on the resource CD). Windows only. • LI_CONTROL_OPENGL_ENABLE_PROGRAMMABLE_SHADING Either the control variable must Search This Doc be set to TRUE, or the "programmable shading" parameter of the "real time shaded" or "real time shaded and vector" render style must be set to TRUE. Search All Docs If the above conditions are met, then the Real-time module will automatically convert all materials into a programmable equivalent. Full Screen A programmable shading representation of a material is made up from a Lightworks material descrip- tion (that is an LtMaterial), and the currently enabled light list (set through LiOpenGLLightList- Set or from the current Lightworks defined light list if using render styles or LiOpenGLRender.
To benefit fully from using programmable shading, any changes to a material should be reflected by invalidating the appropriate material using the LiOpenGLMaterialInvalidate API function. Changes to parameters of shaders should use the _PARAMS bits for the affected shaders, whilst changes to the material itself (e.g. changing a colour shader to a different type) should use the _SHADER bits. Lightworks Author 9.0 Note: Care should be taken when changing light lists. As the generated Real-time program contains the lighting calculations, any changes to the light list will necessarily mean that all materials will have Lightworks to be rebuilt and recompiled. Any changes to the light list, either adding a light, deleting a light, or Real-time changing a light’s type needs to be followed by calling LiOpenGLLightListSet with the new light list. Changes to light parameters should be reflected by calling LiOpenGLShaderInvalidate with the _INVALIDATE_PARAMS bit set. Programmable shading 8.1. Current restrictions
The following restrictions currently exist when using programmable shading. Master Doc
• The number of lights supported in programmable shading depends on the user’s graphics card Title Page and choice of shading language. See Section 8.4 for more details. • At most one environment light is currently supported. Contents • No support for radiosity or tone-mapping.
• Not all shaders are currently supported. Unsupported shaders are ignored currently. First Last
8.2. Environment reflections in Real-time J I
Page 81 of 119 Note that, although Real-time will, where programmable hardware shading is available, attempt to produce reflections where appropriate, it does this in a different way to standard rendering. This is because it will use the currently set environment to produce reflections, even if the material uses Go Back mirror reflectance rather than environment reflectance (and without the environment background being used). Search This Doc This behaviour allows Real-time to produce sensible looking reflections where possible whilst maintaining efficiency. However it does open up a possible inconsistency, in that software renders of the same scene might not show an environment reflection. Search All Docs
In order to prevent your users encountering this inconsistent behaviour, we recommend that, whenever you set a current environment for the scene, you also set the environment background Full Screen shader as the current background. See Section 6.4 for more details about environment mapping in Real-time.
8.3. Decals in programmable shading
Colour and Reflectance decals are supported in the programmable shading mode of Lightworks Real- Lightworks Author time, under both Cg and the OpenGL Shading Language. 9.0
Reflectance decals cannot be mixed with colour decals. Layering of decals is only supported on Lightworks the "base ..." argument of the decal. That is, only the "base colour" argument of a colour Real-time decal may be another decal, and the "base reflectance" argument of a reflectance decal may be another reflectance decal.
Decals created via the session manager interface are also supported. Programmable A material containing a decal can be invalidated as normal, via the LiOpenGLMaterialInvalidate shading and LiOpenGLMaterialRepInvalidate API functions. This will affect all decal layers. However, If an individual decal layer is to be invalidated, then the following functions can be used.
LtStatus Master Doc LiOpenGLDecalInvalidate(LtMaterial lw_mat, LtShader decal, LtBitfield flags) Title Page or Contents LtStatus LiOpenGLDecalRepInvalidate(LtOpenGLMaterial gl_mat, First Last LtShader decal, LtBitfield flags) J I These functions take exactly the same flags as the ...MaterialInvalidate counterparts, but allow an individual layer of a decal material to be modified. Page 82 of 119 For users of the Material API, it should be noted that decals need to be rendered in multiple LiOpenGLMaterialBeginPass LiOpenGLMaterialEndPass passes. Thus and need to be Go Back called multiple times; once per decal layer.
Also note the following caveats: Search This Doc
• A material with a reflectance decal doesn’t support the material’s transparency shader (trans- Search All Docs parent shaders assigned to a decal layer or as a "selector" are supported though). • Only the displacement caused by the "decal displacement" shader will be visible in a decal layer. The material displacement shader or the "base displacement" shader will not Full Screen be visible in a decal layer. 8.4. Lights in programmable shading
The Lightworks Real-time module places limits on the number of lights that can be used in programmable shading. This is to avoid problems in situations where the currently enabled light list contains more lights than a user’s graphics card can render.
Two important limits are imposed by the Real-time module. The first is a limit on the total number of Lightworks Author lights in a scene. The second is a limit on the number of shadow-casting lights. This refers to any 9.0 light that has the ability to cast shadows in programmable shading, even if shadows are disabled for that light. Currently, sun, spot, distant and projector lights support shadows in programmable Lightworks shading, and are counted as shadow-casting lights. All other light types do not currently support Real-time shadows in programmable shading.
If the Cg shading language is used, a maximum of 6 lights are allowed in total. Within that overall limit, a maximum of 3 shadow-casting lights are allowed. Programmable If the OpenGL Shading Language is used, the limits for total lights and shadow-casting lights are shading calculated at runtime based on the capabilities of the user’s graphics card. Typical limits for a modern graphics card would be upto 8 shadow-casting lights and upto 16 lights in total.
To find out the limits that will apply to programmable shading with the current choice of shading Master Doc language, call LiOpenGLQuery with one of the following query types:
• LI_OPENGL_QUERY_MAX_PROG_LIGHTS Title Page • LI_OPENGL_QUERY_MAX_PROG_SHADOW_LIGHTS Contents
See Section 5.3 for more information on how to use this API function. First Last The values returned by LiOpenGLQuery represent an upper limit on the number of lights that the Real-time module will allow. That is, it is never possible to use more than that number of lights. However, in certain circumstances the limits imposed by the Real-time module may be lower J I than the values returned by LiOpenGLQuery. This will only occur if the currently enabled light list contains projector, goniometric or environment lights, and is most likely to occur on AMD/ATI graphics cards. nVidia graphics cards are unlikely to be affected. Page 83 of 119
The Real-time module also places a limit on the number of environment lights. Only one environment light can be used in programmable shading, regardless of the chosen shading Go Back language. Search This Doc
8.5. Shaders supported by programmable shading real-time hard- Search All Docs ware
Full Screen The following is a complete list of shaders supported by Cg and the OpenGL Shading Language. Colour Reflectance Transparency Lights Displacement Texture Space plain plastic plain coverage ambient wrapped bump map all wrapped image phong wrapped mask spot wrapped tread plate chrome matte wrapped image point wrapped height map wrapped diagonal metal wrapped grid distant rough wrapped t stripe environment plain eye wrapped dimple wrapped s stripe glass eroded sun wrapped knurl wrapped grid mirror wrapped square goniometric wrapped rough Lightworks Author wrapped checker dielectric glow projector paving cubes conductor wrapped checker † environment wrapped roof 9.0 solid polka constant x ray shingles wrapped polka radiosity simple wood Lightworks base stepped false solid clouds blue marble chrome 2D solid polka Real-time draft angle eye light plastic wrapped brick evaluation decal wrapped brick marble ‡ blurred mirror bonds simple wood ‡ blurred glass wrapped checker solid clouds ‡ glossy metal wrapped diagonal surface evaluation ‡ glossy dielectric wrapped grid Programmable wood ‡ blurred conductor wrapped polka shading wrapped brick ‡ blurred dielectric wrapped s stripe wrapped brick ‡ glossy mirror wrapped t stripe bonds ‡ glossy glass wrapped textured wrapped filtered wrapped specular brick image map cubes wrapped textured shadow catcher casting Master Doc brick † multilayer paint † leather wrapped roof tiles car paint † local leather wrapped birch floor † wrapped leather wrapped cherry floor Title Page wrapped maple floor wrapped oak floor wrapped pine floor Contents wrapped wood floor birch cherry maple First Last oak pine turbulent paving J I decal † Requires graphics cards able to support the Unified Shader Model (equivalent to DirectX Shader Model 4.0) ‡ Supported, but approximated by their non-glossy/blurred versions. Page 84 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Chapter 9 Lightworks Author 9.0
Lightworks CgFX Support Real-time
CgFX Support
Master Doc The support for the nVidia CgFX effect description is provided through a new reflectance shader: cgfx . If a cgfx reflectance shader is used on an LtMaterial, then real-time will use the CgFX effect data and will ignore the rest of the materials’ shaders. Title Page
This section assumes some familiarity with nVidia’s Cg language and the CgFX framework. For more information, see nVidia’s developer website: Contents
http://developer.nvidia.com/page/home.html First Last
Support is based on the Cg2.0 runtime, FXComposer 2.0 and the nVidia whitepaper: Using SAS with CgFX and FX file formats (available from the nVidia website). Additionally, only CgFX effects J I which describe object effects are supported. There is no support for pre or post processing (in SAS version 0.8, this is equivalent to a ScriptClass = "object" in the STANDARDSGLOBAL Page 85 of 119 parameter block.).
Note: CgFX support is based on the May 2008 version of the Cg 2.0 runtime. (DLL version 2.0.0.15). Go Back Cg Programmable shading is also now dependent on this version, and is compatible with Cg versions prior to 2.0. Search This Doc
9.1. Semantics and Annotations Search All Docs
The following semantics are supported by the real-time module. These are parameters that will be Full Screen set automatically at runtime by the real-time module, commonly known as ‘un-tweakables’–they are not supposed to be edited. Note, the semantic name is treated as case-insensitive. Semantic Name Data Type WORLD float4x4 WORLDINVERSE float4x4 WORLDTRANSPOSE float4x4 WORLDINVERSETRANSPOSE float4x4 VIEW float4x4 VIEWINVERSE float4x4 Lightworks Author VIEWTRANSPOSE float4x4 VIEWINVERSETRANSPOSE float4x4 9.0 WORLDVIEW float4x4 WORLDVIEWINVERSE float4x4 Lightworks WORLDVIEWTRANSPOSE float4x4 Real-time WORLDVIEWINVERSETRANSPOSE float4x4 PROJECTION float4x4 PROJECTIONINVERSE float4x4 PROJECTIONTRANSPOSE float4x4 CgFX Support PROJECTIONINVERSETRANSPOSE float4x4 WORLDVIEWPROJECTION float4x4 WORLDVIEWPROJECTIONINVERSE float4x4 WORLDVIEWPROJECTIONTRANSPOSE float4x4 WORLDVIEWPROJECTIONINVERSETRANSPOSE float4x4 CAMERAPOSITION float3 Master Doc VIEWPORTPIXELSIZE float2 SHADOWMAP sampler2D Title Page SHADOWMAPPROJECTION float4x4 SHADOWMAPRESOLUTION float SHADOWMAPFILTERSIZE float Contents SHADOWMAPPENUMBRAWIDTH float SHADOWMAPDEPTHBIAS float SHADOWMAPGRADIENTCLAMP float First Last
Any parameters defined using the above semantics are expected to be marked with the annotation: J I < string UIWidget = "none"; >;
float4x4 WVPMatrix : WORLDVIEWPROJECTION < string UIWidget = "none"; >; Page 86 of 119
The semantics WORLD, WORLDTRANSPOSE, WORLDINVERSE and WORLDINVERSETRANSPOSE require Go Back the model matrix to be set. In the normal real-time rendering mode this is already tracked using the primitive’s transform. However, when using the Material API this information isn’t readily available, so a call back is provided for the application to supply the current model transform: Search This Doc (LI_CALL_OPENGL_GET_MODEL_TRANSFORM) Search All Docs LtStatus (*LtFuncOpenGLGetModelTransform)(LtMatrix modelTrans, LtMatrix invModelTrans) Full Screen If the callback isn’t defined, then the real-time model will derive the current transform from the current GL_MODELVIEW_MATRIX and current view. Note that this will require a calculation of a matrix inverse, so it is preferable for perfomance reasons to supply the callback.
9.2. Texture Annotations Lightworks Author 9.0 Texture parameters must use the annotation ResourceName to indicate to the real-time module the name of the texture resource to load. They must also define the annotation ResourceType to Lightworks indicate what type of texture it is (1D, 2D, 3D, Cube or Rect). Real-time
texture ColourImage < string ResourceName = "taj.jpg"; string ResourceType = "2D"; CgFX Support >;
9.3. ShadowMap Semantics Master Doc
To reference a Lightworks Real-time shadow map from within a CgFX file, the application must use the following API function: Title Page
LtStatus Contents LiOpenGLBindCgFXLight(LtShader light, LtString object_name)
First Last The application needs to perform the following steps:
• Create one or more Lightworks Author lights which match the lights defined in the CgFX J I file, create a LightList from these and use it as the Real-time light list (set via LiOpenGL- LightListSet()). Page 87 of 119 • Bind each light to a unique name string using LiOpenGLBindCgFXLight(). • Add the appropriate parameters to the CgFX file with the correct semantics. Go Back • For each light, add three parameters corresponding to the semantics ShadowMap, Shad- owMapProjection and ShadowMapResolution. Give each of these an Object annotation that Search This Doc matches the name string bound to the light. • Modify the CgFX code to apply the shadow maps. Search All Docs
The following semantics are available to allow shadow map support: Full Screen
• ShadowMap - The parameter to bind the shadow map texture to. • ShadowMapProjection - The parameter to bind the lights’ projection matrix for calculating the shadow map texture coordinates. • ShadowMapResolution - The size of the shadow map (the shadow map texture is square, hence the single float value).
• ShadowMapFilterSize - The filter size to use for calculating soft edged shadows. Lightworks Author • ShadowMapPenumbraWidth - The width of the soft shadow edges, measured in texels on the shadow map texture. 9.0 • ShadowMapDepthBias - The bias to add to the depth test to compensate for self shadowing Lightworks artifacts. Real-time • ShadowMapGradientClamp - Soft shadow control to help alleviate shadowing artifacts due to polygons nearly parallel to the light direction.
CgFX Support Typically, support for a Lightworks Real-time shadowmap can be introduced into a CgFX shader using the following parameters:
Master Doc
Title Page
Contents
First Last
J I
Page 88 of 119
Go Back
Search This Doc
Search All Docs
Full Screen sampler2D sMap : ShadowMap < string Object = "DirectionalLight0"; string UIWidget = "None"; > = sampler_state { MinFilter = Linear; MagFilter = Linear; WrapS = CLAMP; WrapT = CLAMP; Lightworks Author }; 9.0
float4x4 smProj : ShadowMapProjection < Lightworks string Object = "DirectionLight0"; string UIWidget = "None"; Real-time >;
float smRes : ShadowMapResolution < string Object = "DirectionalLight0"; CgFX Support string UIWidget = "None"; >;
float smFilter : ShadowMapFilterSize < string Object = "DirectionalLight0"; string UIWidget = "None"; >; Master Doc
float smWidth : ShadowMapPenumbraWidth < string Object = "DirectionalLight0"; Title Page string UIWidget = "None"; >; Contents float smBias : ShadowMapDepthBias < string Object = "DirectionalLight0"; string UIWidget = "None"; First Last >;
float smClamp : ShadowMapGradientClamp < string Object = "DirectionalLight0"; J I string UIWidget = "None"; >; Page 89 of 119
NB: The Object annotation is not currently used for the semantics ShadowMapFilterSize, Shad- owMapPenumbraWidth, ShadowMapDepthBias and ShadowMapGradientClamp, as these seman- Go Back tics are set using a single value for all lights. Search This Doc
9.4. Editing CgFX Parameters Search All Docs
Whilst CgFX effect files will work in standard real-time, the ability to edit parameters and change Full Screen techniques is only currently available via the Material API. Editing of parameters must be done using the standard Cg runtime functions on a CGeffect object. The CGeffect object (and other CgFX LtData data; LtStatus status = LI_STATUS_OK;
/* * Assumes a valid LtOpenGLMaterial: GLMat * Query the CGeffect object from the material */ status |= LiOpenGLMaterialGet( GLMat, Lightworks Author LI_OPENGL_MATERAIL_CGFX_EFFECT, 9.0 &data ); Lightworks if (LiStatusOk(status)) { Real-time CGeffect cg_effect = (CGeffect)LiDataGetGenericPtr( &data );
/* Assume the CgFX file has a texture parameter called "ColourTexture" * CgFX Support */ CGparameter cg_param = cgGetNamedEffectParameter( cg_effect, "ColourTexture" ); CGannotation cg_anno = cgGetNamedParameterAnnotation( cg_param, "ResourceName" );
if (cg_anno) Master Doc { const char *sVal = "NewFileName.jpg"; Title Page /* * Set the ResourceName annotation to the new value */ Contents cgSetStringAnnotation( cg_anno, sVal );
/* First Last * Now flag the parameter on the GL Material as invalid. Until * this call is made, the texture on the material will not change */ LiDataSetGenericPtr( &data, (LtGenericPtr)cg_param ); J I LiOpenGLMaterialSet( GLMat, LI_OPENGL_MATERIAL_CGFX_TEXTURE_PARAMETER, Page 90 of 119 &data ); } } Go Back specific data) for an LtOpenGLMaterial can be obtained using the LiOpenGLMaterialGet and Search This Doc LiOpenGLMaterialSet functions described in the Material API section.
Note: Changing parameter values or techniques will be automatically updated, so no invalidation Search All Docs needs to be done, except when changing a texture resource associated with a texture parameter. This is because the change affects the parameters’ annotation value and not the parameter itself. In this case, simply call the LiOpenGLMaterialSet function: Full Screen 9.5. Resource Loading/Unloading
To allow embedded resources to be loaded into the real-time module, the following callbacks can be used. Currently, if the callbacks are set, then they will be called before attempting to read in any texture data referenced by a CgFX effect, using the value defined by the annotation ResourceName. Lightworks Author CallBack Name Prototype 9.0 LtStatus (*LtFuncOpenGLResourceLoad) ( Lightworks LtString resource_name, Real-time LI_CALL_OPENGL_RESOURCE_LOAD LtGenericPtr *resource_data, LtEnum *resource_type, LtBitfield *flags ); LtStatus (*LtFuncOpenGLResourceUnLoad) ( CgFX Support LtString resource_name, LI_CALL_OPENGL_RESOURCE_UNLOAD LtGenericPtr resource_data, LtEnum resource_type, LtBitfield flags );
The value of the ResourceName annotation will be used as the resource_name parameter to the Master Doc _RESOURCE_LOAD callback, if one is set.
The _RESOURCE_LOAD callback is expected to return a pointer to the appropriate object as Title Page resource_data, an enumeration indicating what the resource type is (in resource_type). The flags parameter is currently unused. Contents The possible resource types available, and the data expected to be return are: First Last Resource Type Expected Data Description LI_OPENGL_RESOURCE_IMAGE_2D LtImage Simgle 2D Image pointer LI_OPENGL_RESOURCE_CUBEMAP_IMAGES LtImage[6] Array of 6 2D images representing J I +X -X +Y -Y +Z -Z faces of the cube map Page 91 of 119
When the real-time module has finished with the resource, then the _RESOURCE_UNLOAD callback will be called to allow the data to be freed by the application. Go Back
Search This Doc
Search All Docs
Full Screen Chapter 10 Lightworks Author 9.0
Lightworks Control Variables for Real-time Real-time
Control Variables for Real-time
Master Doc The control variables available within the liopengl module divide into groups based on when it is valid to change them. Title Page Note: If you are using render styles to control Real-time rendering then only those control variables marked with an asterisk (*) should be modified or queried; render style arguments should be used instead of the others. Contents
First Last 10.1. Context variables
J I May not be changed inside an LiOpenGLInitialise / LiOpenGLTerminate pair.
Page 92 of 119 Context Control Variables (prefix LI_CONTROL_OPENGL_) Variable Type Description DOUBLE_BUFFERED (*) LtBoolean Specifies whether the OpenGL module should use a single or Go Back double buffered display when configuring a window itself. Default is TRUE. SHARE_CONTEXTS (*) LtBoolean Specifies whether the OpenGL module should share OpenGL Search This Doc state between compatible rendering contexts. Can be set to FALSE if primitives are not rendered to multiple rendering con- texts (windows/images), or if they are invalidated before switch- ing to a different context. Default is TRUE. Search All Docs SOFTWARE_RENDER (*) LtBoolean Specifies whether the OpenGL module should use the software OpenGL implementation in preference to a hardware implemen- tation. Default is FALSE. Full Screen Context Control Variables (prefix LI_CONTROL_OPENGL_) Variable Type Description WINDOW_MODE (*) LtEnum Defines how the application will specify the current window to liopengl. The following values may be specified: • LI_OPENGL_WINDOW_MODE_LW • LI_OPENGL_WINDOW_MODE_APP • LI_OPENGL_WINDOW_MODE_CURRENT In LW mode the current driver is used. In APP mode the ap- Lightworks Author plication can specify a window or image directly. In CURRENT 9.0 mode the application is responsible for creating and binding an OpenGL rendering context—liopengl will send calls to the current context. The default is WINDOW_MODE_LW. Lightworks ANTIALIAS_SAMPLES (*) LtNat32 Specifies the number of samples to use for anti-aliasing render- Real-time ing. The value must be a power of 2. If the graphics card doesn’t support a mode with the requested number of samples, then the number of samples will be set to the highest power of 2 that the graphics card supports. Default is 1. STEREO_BUFFERS (*) LtBoolean Specifies whether the OpenGL module should use a display containing left and right buffers when configuring a window Control Variables for itself. When combined with a double-buffered display, this is Real-time often referred to as ’quad-buffer’ stereo. Default is FALSE.
10.2. Geometry variables Master Doc
May not be changed inside an LiOpenGLImageBegin / LiOpenGLImageEnd pair. Changes in Title Page these variables may not affect any previously rendered primitives until they are invalidated with the flag LI_OPENGL_INVALIDATE_GEOMETRY. Contents
Geometry Control Variables (prefix LI_CONTROL_OPENGL_) First Last Variable Type Description CONV_MODE LtEnum Specifies how Lightworks data is to be converted to OpenGL rendering calls. The modes cover a range from short setup times and slow rendering times to longer J I setup times and fast rendering times. The following values may be specified: • LI_OPENGL_CONV_MODE_TRIANGLE Page 93 of 119 • LI_OPENGL_CONV_MODE_DIRECT • LI_OPENGL_CONV_MODE_LIST • LI_OPENGL_CONV_MODE_VERTEX_ARRAY Go Back TRIANGLE mode facets or triangulates the Lightworks geometry and passes it to OpenGL as triangles. DIRECT mode additionally forms the triangles into tri-strips Search This Doc before passing to OpenGL. LIST mode additionally stores the tri-strips in OpenGL display lists. VERTEX_- ARRAY mode stores the tri-strips as OpenGL ver- tex arrays, and supersedes the control variable LI_- Search All Docs CONTROL_OPENGL_VERTEX_ARRAYS The default is _- CONV_MODE_DIRECT. Full Screen Geometry Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description FACETING LtEnum Specifies how surfaces should be faceted. Because liopengl is aimed at interactive manipulation, view- independent faceting is used. The following values may be specified: • LI_OPENGL_FACETING_FASTEST mode pro- vides a coarse level of faceting. Lightworks Author • LI_OPENGL_FACETING_NICEST mode provides 9.0 a finer level. • LI_OPENGL_FACETING_LW mode uses the cur- Lightworks rent Lightworks faceting state. Real-time The default is _FACETING_FASTEST. USE_PRIMITIVE_FACET_REF LtBoolean Specifies whether facet refinements attached to primi- tives will be used during geometry expansion (TRUE), or whether all primitives will use the same level of faceting (FALSE). When this control is set to FALSE, all prim- itives are expanded using the same level of faceting, Control Variables for as specified by LI_CONTROL_OPENGL_FACETING. If Real-time this control is set to TRUE, any primitives that have facet refinements attached will use those refinements when they are expanded. Primitives without facet refine- ments will continue to use the faceting state specified by LI_CONTROL_OPENGL_FACETING. The default setting is FALSE. Master Doc LOWPOLY_THRESHOLD LtNat32 Only relevant in CONV_MODE_LIST mode. Specifies the number of triangles in a primitive below which the module avoids building a display list. If the complexity of a primitive is below this threshold no display list will Title Page be built and the primitive will be converted as if CONV_- MODE_DIRECT had been specified. The default value is 20. PRESERVE_GEOMETRY LtBoolean Specifies whether the original geometry for poly/mesh Contents primitives will be over-written by the module (FALSE) or preserved (TRUE). You should set this to TRUE if you want to keep the original pre-triangulation geometry, for First Last example, for refaceting. Normally however it is more efficient to use the default setting (FALSE). Note: If you do set this control to TRUE, be sure to do so before any geometry is processed, or the original geometry will be J I lost. CONTRACT_GEOMETRY LtBoolean Specifies whether to contract temporary geometry when using OpenGL display list or vertex arrays (i.e., CONV_- Page 94 of 119 MODE set to LIST or VERTEX_ARRAY) to improve mem- ory efficiency. (the value is TRUE by default). POLYLINE_MODE LtEnum Specifies if PolyLine primitives should either be ex- panded into meshes before rendering, or rendered as Go Back OpenGL Lines. POLYLINE_MODE_DEFAULT will ren- der the primitives as GL_LINES, whereas POLYLINE_- MODE_EXPAND will expand the PolyLine primitives into meshes, and render the resulting meshes. (the value is Search This Doc POLYLINE_MODE_DEFAULT by default).
Search All Docs
Full Screen Geometry Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description TEX_FIX_ORIENTATION (*) LtBoolean This control can be used to fix a bug that may occur when rendering textured materials in real-time programmable shading. In some situations, textures applied to large primitives might appear to reverse spontaneously during navigation through a scene. To prevent this, set the control to TRUE. This will force the textures to maintain Lightworks Author the same orientation during navigation. The default setting is FALSE. 9.0 Lightworks Real-time 10.3. Material variables
LiOpenGLImageBegin LiOpenGLImageEnd May not be changed inside an / pair. Changes in Control Variables for these variables may not effect any previously rendered materials until they are invalidated with flag Real-time LI_OPENGL_INVALIDATE_MATERIAL.
Material Control Variables (prefix LI_CONTROL_OPENGL_) Variable Type Description Master Doc DECALS_ENABLED LtBoolean Specifies if the processing of decals is enabled or not. When disabled, only the base layer of the decal is processed and displayed. The default value is TRUE. Title Page MAX_TEXTURE_SIZE LtNat32 Specifies the maximum size of texture for materials to be used which are generated procedurally (such as "wrapped checker"). The default value is 128. This value is used to clamp texture map size of Contents wrapped shader (set by shader writer through predefined shader parameters texture_map_resolution_low and texture_map_resolution_high) only if LI_- OPENGL_TEXTURE_QUALITY is not equal to LI_- First Last OPENGL_TEXTURE_QUALITY_NICEST. For details see Section 6.7 of the Lightworks Plug-in SDK (Writing Cus- tom Shaders) documentation. Note that materials which use images (such as "wrapped image") take their J I maximum size from the image dimensions, not from this variable. MAX_BG_TEXTURE_SIZE LtNat32 Specifies the maximum size of texture for background Page 95 of 119 textures to be used. The default value is 256. CLAMP_IMAGE_TEXTURES LtBoolean Specifies if the textures generated from materials which use images (such as "wrapped image") should be clmaped to a maximum size (TRUE), or to use the actual Go Back image dimensions as the texture size (FALSE) The default value is FALSE. MAX_IMAGE_TEXTURE_SIZE LtNat32 Specifies the maximum size of textures derived from Search This Doc images (such as "wrapped image") if the clamping of image textures is enabled. The default value is 64. MIPMAPPING LtBoolean Specifies whether to create textures as mipmaps (TRUE) for increased visual quality, or standard textures (FALSE). Search All Docs Note that setting this control variable to TRUE will gener- ally increase the memory usage, as mipmapped textures require more storage space. The default value is FALSE. Full Screen Material Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description TEXTURE_QUALITY LtEnum Specifies the quality settings to be used when generating textures. • LI_OPENGL_TEXTURE_QUALITY_GL • LI_OPENGL_TEXTURE_QUALITY_FASTEST • LI_OPENGL_TEXTURE_QUALITY_NICEST Lightworks Author The default is ..._FASTEST, ..._NICEST uses bi-linear filtering to give a better appearance to textures although 9.0 should only be set when hardware available. In GL mode the application is responsible for setting OpenGL filtering modes and texture quality hints—liopengl will use the Lightworks current OpenGL state. Real-time There are also 3 settings which can be used with mipmapped textures: • LI_OPENGL_TEXTURE_QUALITY_POINT • LI_OPENGL_TEXTURE_QUALITY_BILINEAR • LI_OPENGL_TEXTURE_QUALITY_TRILINEAR Control Variables for Real-time In mipmapping mode, ..._FASTEST maps to ..._POINT and ..._NICEST maps to ..._TRILINEAR. This control variable (with cooperation of predefined shader parameters texture_map_resolution_low and texture_map_resolution_high) specifies also texture maps size of wrapped shader (for more details see Section 6.7 of the Lightworks Plug-in SDK (Writing Master Doc Custom Shaders) documentation).
EMULATE_PROG_SHADERS LtBitfield Allows wrapped procedural shaders in a material to be Title Page emulated with a texture map in programmable shading. Emulating procedural shaders will increase performance, but at a cost of lower visual quality. Valid bit-fields are: Contents • LI_OPENGL_EMULATE_WRAPPED_COLOUR Forces emulation of procedural wrapped colour shaders with a texture mapped representation • LI_OPENGL_EMULATE_WRAPPED_- First Last TRANSPARENCY Forces emulation of procedural wrapped transparency shaders with a texture mapped representation J I The default value is zero (no bits set).
Page 96 of 119 10.4. Render variables Go Back
May not be changed inside an LiOpenGLImageBegin / LiOpenGLImageEnd pair. Search This Doc
Search All Docs
Full Screen Render Control Variables (prefix LI_CONTROL_OPENGL_) Variable Type Description AMBIENT_- LtEnum Controls how the Ambient Occlusion blur radius is used OCCLUSION_BLUR_- to define the size of the blurring effect. The options are: MODE (*) • LI_OPENGL_AO_BLUR_MODE_BUFFER The blur radius specifies the size of the blurring effect in pixels in the Ambient Occlusion buffer. • LI_OPENGL_AO_BLUR_MODE_SCREEN The blur Lightworks Author radius specifies the size of the blurring effect in pixels in the final rendered image. 9.0 The default value is LI_OPENGL_AO_BLUR_MODE_- BUFFER Lightworks AMBIENT_- LtFloat Controls the amount of blurring of the occlusion effect. OCCLUSION_BLUR_- Smaller values pick out detail more sharply, larger values Real-time RADIUS create a smoothly blurred occlusion effect. The default value is 7.0 AMBIENT_- LtFloat Controls the contrast of the occlusion effect. Higher OCCLUSION_- values darken the occlusion, lower values lighten the CONTRAST occlusion value. The default value is 1.25 Control Variables for AMBIENT_- LtEnum Controls how the Ambient Occlusion data is displayed. OCCLUSION_DISPLAY The options are: Real-time • LI_OPENGL_AO_DISPLAY_AO_ONLY Displays only the Ambient Occlusion buffer • LI_OPENGL_AO_DISPLAY_POSTPROCESS_- BLEND Modulates the rendered image with the Ambient Occlusion buffer (i.e. each pixel Master Doc in the rendered image is multiplied by the corresponding value in the Ambient Occlusion buffer) Title Page The default is LI_OPENGL_AO_DISPLAY_- POSTPROCESS_BLEND AMBIENT_- LtEnum Controls the Ambient Occlusion method. Options: Contents OCCLUSION_MODE • LI_OPENGL_AO_MODE_NONE Disables Ambient Occlusion processing. • LI_OPENGL_AO_MODE_SSAO Enables Screen Space Ambient Occlusion. (Programmable shad- First Last ing must also be enabled.) The default value is LI_OPENGL_AO_MODE_NONE J I
Page 97 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description AMBIENT_- LtEnum Controls the quality of the Ambient Occlusion effect. OCCLUSION_QUALITY Note, this control also affects performance. The lower the quality, the higher the performance • LI_OPENGL_AO_QUALITY_LOW Renders to a low resolution buffer, with coarse sampling • LI_OPENGL_AO_QUALITY_MEDIUM Renders to Lightworks Author a low resolution buffer with a finer sampling strat- 9.0 egy • LI_OPENGL_AO_QUALITY_HIGH Renders to a Lightworks full size resolution buffer with a fine sampling strategy Real-time • LI_OPENGL_AO_QUALITY_VERY_HIGH Ren- ders to a full size resolution buffer with extremely fine sampling • LI_OPENGL_AO_QUALITY_HIGHEST Renders to a high resolution buffer with extremely fine Control Variables for sampling Real-time • LI_OPENGL_AO_QUALITY_TILED Renders to a very high resolution buffer with extremely fine sampling The default is LI_OPENGL_AO_QUALITY_MEDIUM AMBIENT_- LtFloat Sets the radius for considering occlusion. Only data Master Doc OCCLUSION_RADIUS within this radius around a point will be considered during occlusion processing. The default value is 0.2 AMBIENT_- LtFloat Controls the size of the border region used in Tiled OCCLUSION_TILE_- SSAO. This affects both image quality and memory Title Page BORDER usage. Smaller values reduce memory usage, with a possible decrease in image quality. Larger values in- crease image quality at the cost of higher memory us- age. This control requires the LI_CONTROL_OPENGL_- Contents AMBIENT_OCCLUSION_QUALITY control variable to be set to LI_OPENGL_AO_QUALITY_TILED. The default value is 0.25 First Last ANTIALIAS (*) LtBoolean Specifies whether or not to perform anti-aliasing render- ing, if available. This control requires the LI_CONTROL_- OPENGL_ANTIALIAS_SAMPLES control variable to be set. The default is FALSE. J I APPLY_GAMMA_- LtBoolean Specifies whether or not to apply gamma correction to CORRECTION colours and textures. The default is FALSE. GAMMA_- LtFloat Specifies the gamma correction factor to apply to output Page 98 of 119 CORRECTION_FACTOR colours and textures. The default is 1.0.
Go Back
Search This Doc
Search All Docs
Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description BACKGROUND_- LtEnum Background mode to be used. Possible values are: QUALITY • LI_OPENGL_BACKGROUND_QUALITY_NO_- TEXTURE sets background to a plain colour. • LI_OPENGL_BACKGROUND_QUALITY_TEX_- NEAREST tries to build an OpenGL texture of the background and display using GL_NEAREST. Lightworks Author • LI_OPENGL_BACKGROUND_QUALITY_TEX_- 9.0 LINEAR is similar to ..._TEX_NEAREST except for using GL_LINEAR. Lightworks • LI_OPENGL_BACKGROUND_QUALITY_TEX_- FASTEST is a synonym for ..._NO_TEXTURE. Real-time • LI_OPENGL_BACKGROUND_QUALITY_TEX_- NICEST is a synonym for ..._TEX_LINEAR. The default is ...NICEST. CLEAR_BUFFER (*) LtBitfield Specifies which buffers are cleared when Control Variables for LiOpenGLBackgroundSet is called. The follow- ing bit-fields are defined: Real-time • LI_OPENGL_CLEAR_COLOUR • LI_OPENGL_CLEAR_DEPTH Can be used in conjunction with HOLD_IMAGE to com- bine multiple renderings. The default is COLOUR | DEPTH. Master Doc CLEAR_COLOUR LtColour Default background colour used by LiOpenGLBack- groundSet if background is of unknown type or doesn’t exist. The default is (0, 0, 0). Title Page DECAL_MODE LtEnum Decal mode to be used. Possible values are: • LI_OPENGL_DECAL_MODE_NICEST blends the decal layers together.. Contents • LI_OPENGL_DECAL_MODE_FASTEST uses a threshold test for pixel visibility. The default is ..._NICEST. First Last DISABLE_- LtBoolean Controls the way transmitted light is simulated by glass- REFRACTION (*) type and dielectric-type reflectance shaders in real- time programmable shading. When FALSE, the default method is used. Refraction is simulated by taking a sample from the global environment. A limited amount J I of alpha transparency is used, upto a maximum of 50% transparent. When TRUE, a simpler method is used. Refraction is not simulated, and materials can be upto Page 99 of 119 90% transparent, if the "transmission factor" is greater than 0.9. The default is FALSE. This control affects the following reflectance shaders: Go Back "glass", "blurred glass", "glossy glass", "dielectric", "blurred dielectric", "glossy dielectric" and "lit appearance". ENABLE_- LtBoolean Controls whether to allow programmable shading or not, Search This Doc PROGRAMMABLE_- if it is available. (See Section8 for details). The default is SHADING FALSE. ENABLE_SOFT_- LtBoolean Controls whether to allow soft shadows in real-time SHADOWS renders (programmable shading must also be enabled). Search All Docs The default is FALSE.
Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description ENVIRONMENT_- LtFloat Modifies the intensity of "environment" lights in pro- LIGHT_INTENSITY grammable shading, relative to the "intensity" of the light itself. If "environment" lights appear darker in Real-time rendering than in software rendering, set a value greater than 1.0 to brighten up the Real-time light- ing. If they appear brighter in Real-time rendering than Lightworks Author in software rendering, set a value less than 1.0 to reduce the intensity of the Real-time lighting. The default is 1.0. 9.0 ENVIRONMENT_- LtFloat Controls how widely we sample the environment map LIGHT_MAX_ANGLE when calculating the illumination from an "environ- ment" light. Setting the maximum value of 90.0 degrees Lightworks means we take samples across a full hemisphere above Real-time each shading point. This gives the most physically realis- tic result, however a high quality setting may be needed to give smooth illumination. Setting a lower value can give a better appearance with lower quality settings, at the expense of physical accuracy. The default is 35.0 degrees. Control Variables for ENVIRONMENT_- LtNat32 Controls the quality of lighting from "environment" lights. Real-time LIGHT_QUALITY Set lower values to give fast, coarse illumination. Set higher values to give smoother illumination, at the cost of slower render times. Artefacts from using lower qual- ity values are considerably reduced by using a heavily blurred environment lighting image. Speed is also likely to be increased by using a much smaller image than Master Doc would be used for reflections. The functions LiHDRI- ImageResize and LiHDRIImageBlur are supplied to assist with resizing and blurring HDR images. The mini- mum value is 1, the maximum value is 7. The default is Title Page 2. HOLD_IMAGE (*) LtBoolean Specifies whether the image being rendered should be held for further processing at ImageEnd. If TRUE the Contents rendered image will not be displayed immediately. Mul- tiple renders can be combined together to implement multiple drawing styles in the same image or to imple- ment multiple pass rendering algorithms. The default is First Last FALSE. IGNORE_TRANSPAR- LtBoolean Specifies whether transparent primitives should be sent ENT_PRIMS to OpenGL. Used within multi-pass rendering to make sure primitives get blended together correctly. See J I Section 5.1.3.1. The default is FALSE. LIGHTING LtEnum Specifies the type of lighting model to be used. The following values are available: Page 100 of 119 • LI_OPENGL_LIGHTING_LW uses the Lightworks lights. • LI_OPENGL_LIGHTING_GL provides one eye Go Back light. • LI_OPENGL_LIGHTING_UNLIT turns off all lighting. Search This Doc The default is LIGHTING_LW.
Search All Docs
Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description LIGHTING_CALC LtEnum Specifies the lighting calculation method to use. The following values are available: • LI_OPENGL_LIGHTING_CALC_NONE forces all lights to be calculated by OpenGL. That is, all light intensities will be clamped to 1.0. • LI_OPENGL_LIGHTING_CALC_MIXED forces all Lightworks Author lights with intensities <= 1.0 to be calculated by 9.0 OpenGL, and all lights with intensities > 1.0 to be calculated by the liopengl module. Lightworks • LI_OPENGL_LIGHTING_CALC_ALL forces the liopengl module to do all the lighting calcu- Real-time lations. The default is LIGHTING_CALC_NONE. LINE_STIPPLE LtBoolean Specifies whether to apply the current line type when rendering PolyLines or polygon edges in _EDGE render- ing mode. The default is FALSE. Control Variables for MATERIAL LtEnum Specifies how the module should setup the OpenGL Real-time material model. Possible values are: • LI_OPENGL_MATERIAL_NONE sends no materi- als. If the application does not send materials itself, then everything will appear in the default OpenGL material (grey). • LI_OPENGL_MATERIAL_MATTE sends only the Master Doc average colour of each material with a matte reflectance model. • LI_OPENGL_MATERIAL_PER_PRIM sends the Title Page average colour of each material and approxi- mates the Lightworks reflectance model. • LI_OPENGL_MATERIAL_PER_VERTEX sets up Contents the materials as for ..._PER_PRIM and also ap- proximates solid shaders by evaluating the colour at each vertex and allowing OpenGL to interpo- late. First Last • LI_OPENGL_MATERIAL_FASTEST is a synonym for ..._MATTE. • LI_OPENGL_MATERIAL_NICEST is a synonym J I for ..._PER_VERTEX. The default is MATERIAL_NICEST. REN_METHOD LtEnum Specifies the rendering method to use. Possible values Page 101 of 119 are: • LI_OPENGL_REN_METHOD_WIRE renders the geometry in wireframe mode Go Back • LI_OPENGL_REN_METHOD_FLAT renders the geometry with flat shading • LI_OPENGL_REN_METHOD_SMOOTH renders the Search This Doc geometry with smooth (Gouraud) shading • LI_OPENGL_REN_METHOD_EDGE renders the original geometry (before it was triangulated) in Search All Docs wireframe. Note that this will only work properly if LI_CONTROL_PRESERVE_GEOMETRY is set to TRUE. The default is METHOD_SMOOTH. Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description SHADING_LANGUAGE LtEnum Selects the shading language to use when pro- grammable shading is enabled. Possible values are: • LI_OPENGL_SHADING_LANGUAGE_ANY Uses ei- ther Cg or GLSLANG. On NVIDIA hardware, the Cg language will be used by default, on other hardware, GLSLANG will be used. Lightworks Author • LI_OPENGL_SHADING_LANGUAGE_CG Only use 9.0 the Cg language, if available. If not available, then programmable shading will be disabled. Lightworks • LI_OPENGL_SHADING_LANGUAGE_GLSLANG Only use the OpenGL Shading language, if Real-time available. If not available, then programmable shading will be disabled. The default is LANGUAGE_ANY. SHADOW_AVAIL- LtBitfield Queries the shadow mapping algorithms available for ABLE_DEPTHS rendering shadows. NOTE: This control variable can Control Variables for only be queried between a call to LiOpenGLImageBe- gin and LiOpenGLImageEnd. It is a read only control Real-time variable. The returned LtBitfield can have the fol- lowing bits set: • LI_OPENGL_SHADOW_DEPTH_BIT_8 A shadow mapping algorithm using 8 bit precision depth maps can be used with the current rendering Master Doc context • LI_OPENGL_SHADOW_DEPTH_BIT_16 A shadow mapping algorithm using 16 bit Title Page precision depth maps can be used with the current rendering context • LI_OPENGL_SHADOW_DEPTH_BIT_24 A shadow mapping algorithm using 24 bit Contents precision depth maps can be used with the current rendering context A returned value of 0 indicates that the shadow mapping First Last algorithms are not compatible with the current rendering context. SHADOW_DEPTH LtEnum Selects the shadow mapping algorithm to use • LI_OPENGL_SHADOW_DEPTH_FASTEST Render J I shadows using the fastest algorithm available • LI_OPENGL_SHADOW_DEPTH_NICEST Render shadows using the most accurate (i.e. highest Page 102 of 119 precision) algorithm available • LI_OPENGL_SHADOW_DEPTH_8 Render shad- ows using 8 bit depth precision Go Back • LI_OPENGL_SHADOW_DEPTH_16 Render shad- ows using 16 bit depth precision. Note: if 16 bit precision is not available, then 8 bit precision will Search This Doc be used instead • LI_OPENGL_SHADOW_DEPTH_24 Render shad- ows using 24 bit depth precision. Note: if 24 bit Search All Docs precision is not available, then 16 bit precision will be used if possible, otherwise 8 bit shadows will be used. The default is _SHADOW_DEPTH_NICEST. Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description SHADOW_FILTER_- LtNat32 Controls the quality of soft shadows when using pro- SIZE grammable shading. Increasing the filter size will lead to a smoother transition between lit and shadowed areas, at the cost of slower rendering speeds. Setting the fil- ter size to 1 will have the same effect as disabling soft shadows. Note that some older or less capable graphics Lightworks Author cards may struggle to run correctly with high values for this setting. The default is 5. 9.0 SHADOW_PENUMBRA_- LtNat32 Controls the width of the transition between lit and WIDTH shadowed areas when soft shadows are enabled in programmable shading. Lightworks SHADOW_DEPTH_BIAS LtFloat Controls the depth bias of the shadow map look-up when Real-time soft shadows are enabled. The bias should probably be restricted to positive values between 0.0 and 1.0. SHADOW_GRADIENT_- LtFloat Surfaces that are almost face-on to a light have a small CLAMP shadow gradient (the angle between the surface normal and the light is close to zero), while surfaces that are almost edge-on to the light have a large gradient (the Control Variables for angle between the normal and the light is close to 90 Real-time degrees). When soft shadows are enabled, the shadow gradient value is used to adjust the soft shadow effect at each point, to prevent self-shadowing artifacts. This control allows the user to clamp the gradient value before it is used in the soft shadow calculation. This may help to reduce other types of shadow artifacts. The Master Doc control is an angle between 0 and 90 degrees. If the gradient at a point is calculated as being larger than this value, it is clamped down to the specified value. SHADOW_MODE LtEnum Enables Shadows. Title Page • LI_OPENGL_SHADOW_MODE_NONE Disables shadows Contents • LI_OPENGL_SHADOW_MODE_SHADOW_MAPS En- ables shadow rendering using a shadow mapping algorithm • LI_OPENGL_SHADOW_MODE_AUTO_SHADOW_- First Last MAPS Enables shadow rendering and automatic shadow map calculation when using the LiOpenGLRender function (or the LI_EXE- CUTE_REN_OPENGL execute method. J I The default is _SHADOW_MODE_NONE. SHADOW_OPTIONS LtBitfield Controls aspects of shadow map generation/usage. The following bit-fields are defined. Page 103 of 119 • LI_OPENGL_SHADOW_OPTION_PBUFFER Use PBuffers to generate shadow maps, if available. The default is _SHADOW_OPTION_PBUFFER. Go Back
Search This Doc
Search All Docs
Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description STEREO_MODE (*) LtEnum Controls real-time stereoscopic rendering. The options are: • LI_OPENGL_STEREO_MODE_NONE Disables stereoscopic rendering. • LI_OPENGL_STEREO_MODE_LEFT Enables stereoscopic rendering and sets up the current Lightworks Author view for a left-eye render. The image being 9.0 rendered will appear in the back left OpenGL buffer. SwapBuffers will not be called when the render is complete. Lightworks • LI_OPENGL_STEREO_MODE_RIGHT Enables Real-time stereoscopic rendering and sets up the current view for a right-eye render. The image being rendered will appear in the back right OpenGL buffer. The default value is LI_OPENGL_STEREO_MODE_NONE Control Variables for STEREO_3D_FACTOR LtDouble Controls the strength of the 3D depth effect. Smaller values (between 0.0 and 1.0) will weaken the effect, Real-time making the scene appear more like a flat 2D image. Larger values (greater than 1.0) will strengthen the 3D effect. Values less than or equal to 0.0 are not valid. Reducing the strength of the 3D depth effect will reduce the likelihood of eyestrain or headaches when viewing scenes in 3D. The default value is 1.0 Master Doc STEREO_DISTANCE_- LtDouble Controls the apparent distance of the 3D model from FACTOR the viewer. Smaller values (between 0.0 and 1.0) will make the model appear closer to the viewer. Larger Title Page values (greater than 1.0) will make the model appear to be farther from the viewer. Values less than or equal to 0.0 are not valid. The default value is 1.0 TONE_AUTOSETUP LtBoolean Specifies whether or not to automatically initialise tone Contents shaders, when specified with the LiOpenGLToneList- Set function. The default is TRUE. TEXTURES_ENABLED LtBoolean Specifies whether textures should be sent to OpenGL. First Last Can speed up rendering if disabled, at the cost of image quality. The default is TRUE. TRANSPARENCY_MODE LtEnum Transparency mode to be used. Possible values are: • LI_OPENGL_TRANSPARENCY_NONE turns off J I support for transparent primitives. • LI_OPENGL_TRANSPARENCY_STIPPLE uses a quick stipple pattern ‘screen door’ effect to rep- Page 104 of 119 resent a primitive’s transparency. • LI_OPENGL_TRANSPARENCY_BLEND blends un- sorted transparent primitives with pre-drawn Go Back opaque objects. • LI_OPENGL_TRANSPARENCY_SORTED_BLEND sorts transparent primitives from back to front Search This Doc and then blends them with pre-drawn opaque objects. • LI_OPENGL_TRANSPARENCY_NICEST is a syn- onym for ..._SORTED_BLEND. Search All Docs • LI_OPENGL_TRANSPARENCY_FASTEST is a syn- onym for ..._STIPPLE. The default is ..._FASTEST. Full Screen Render Control Variables (continued) (prefix LI_CONTROL_OPENGL_) Variable Type Description USER_CLIPPING_- LtBoolean Specifies whether to apply any user defined clipping PLANES planes. The default is FALSE. WIRE_COLOUR LtEnum Specifies how to colour the lines in wireframe render modes (_WIRE and _EDGE). • LI_OPENGL_WIRE_COLOUR_MATERIAL Uses the average colour of the primitives material Lightworks Author • LI_OPENGL_WIRE_COLOUR_DEFAULT Uses the 9.0 default colour defined by LI_CONTROL_- OPENGL_DEFAULT_WIRE_COLOUR Lightworks The default is _COLOUR_DEFAULT. DEFAULT_WIRE_- LtColour Specifies the default colour to render lines in _EDGE and Real-time COLOUR _WIRE modes. The default is white (1.0, 1.0, 1.0)
Control Variables for Real-time
Master Doc
Title Page
Contents
First Last
J I
Page 105 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Lightworks Author 9.0
Lightworks Real-time
Part VI
Appendix Master Doc
Title Page
Contents
First Last
J I
Page 106 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Appendix A Lightworks Author 9.0
Lightworks Notes Real-time
Notes
Master Doc This section outlines the features of Lightworks which are supported, and limitations of OpenGL and this release of Lightworks Real-time and Real-time Plus. We also list the platforms on which the software has been tested, and the minimum system requirements you will need. Title Page
Contents A.1. Features
First Last liopengl aims to match the results of Lightworks rendering modes as closely as possible while maintaining interactive performance. Some Lightworks features cannot be supported, or can only be supported with reduced quality. The Lightworks features supported by this release are J I detailed below. Further features may be supported in future releases. Note: Apart from the Geometry and background shaders, the supported features refer only to standard Real-time and not to programmable Real-time. For a list of shaders supported by programmable shading, see Page 107 of 119 Section 8.5.
Go Back Geometry All surface primitive types are supported. Poly-lines, poly-line sets, curves and trees are not Search This Doc supported.
Background Shaders Search All Docs Fully supported shaders are "none", "plain" "graduated", "image", "scaled image" and "clouds. For "ray cube" the "primary shader" is used. For "two planes" the "front shader" is used. For all other shaders, liopengl will try to produce a texture Full Screen map for the background, otherwise the background colour as specified by the default LI_- CONTROL_OPENGL_CLEAR_COLOUR will be used. Colour Shaders All constant colour shaders are supported. Wrapped shaders are supported as texture maps. Solid shaders are approximated by evaluating the shader at each vertex and allowing OpenGL to interpolate between vertices. All other shaders are approximated by their average colour, except for decals for which there is explicit support. Note: liopengl only supports decals which are layered on the base colour argument (i.e. only the base colour argument for a decal may be another decal ). Lightworks Author Displacement Shaders 9.0 Not supported. Lightworks Foreground Shaders Real-time Not supported. Light Shaders Supported shaders are "ambient", "distant", "eye", "point", "spot" and "sun". Notes Post Shaders Not supported. Reflectance Shaders Shaders that match or can be approximated by the OpenGL material model are handled Master Doc explicitly. A matte reflectance is used for all other shaders. Fully supported shaders are "plastic", "matte", "constant" and "phong". Approximated shaders are "metal", "glass", "chrome 2D", "conductor". "reflectance decal" shaders are handled Title Page as a special case, and are converted into colour decals. "environment" shaders are supported for spherical environment maps. Cubic environment maps are only supported if the GL_ARB_texture_cube_map is supported Contents
Tone Mapping Shaders All tone mapping shaders are supported. First Last Texture Space Shaders Shaders that match the OpenGL texgen model are handled explicitly. These are "arbitrary plane", "x plane", "y plane" and "z plane". All other shaders are evaluated to J I generate texture coordinates at each vertex. The texture coordinates are then passed to OpenGL to interpolate across polygons. Page 108 of 119 Transparency Shaders All plain and wrapped shaders are fully supported. Solid transparency shaders are approxi- Go Back mated by evaluating the shader at each vertex and allowing OpenGL to interpolate between vertices. Search This Doc
A.2. OpenGL Limitations Search All Docs liopengl aims to match the results of Lightworks rendering modes as closely as possible while Full Screen maintaining interactive performance. Situations in which OpenGL limitations can lead to significant differences between Lightworks and liopengl rendering are indicated below. • Real-time transparency with Intel 830M integrated graphics chipsets. Problems have been encountered with transparency in real-time and the Intel 830M integrated graphics chipsets causing artifacts (especially with RPC primitives) . Workaround: Currently the only workaround is to turn off hardware acceleration. • Transparent double-sided geometry can sometimes cause problems for OpenGL rendering. Workaround: Ensure all transparent geometry is single-sided. Lightworks Author • OpenGL does not support lights with an intensity greater than 1.0. The liopengl module does 9.0 support lights with intensities greater than 1.0, however these lights will be calculated by the module and thus, will not be able to take advantage of any available hardware acceleration. See Lightworks the "lighting accuracy" argument in the reference page for the "real time shaded" Real-time render style (or the LI_CONTROL_OPENGL_LIGHTING_CALC_), for more details. If lights with intensities greater than 1.0 are used and the liopengl module lighting calculations are switched off, then the OpenGL rendered image will appear darker than the Lightworks rendered image. Notes Workaround: Ensure all light intensities are less than 1.0. Add an ambient light if the model appears too dark. • Non-linear texture spaces ("auto axis", "cylindrical", "spherical") don’t match Lightworks rendering exactly. The OpenGL module evaluates the texture space shaders for each vertex to generate texture coordinates for use by OpenGL. Lightworks evaluates the texture space shaders for each pixel. OpenGL linearly interpolates texture coordinates from Master Doc the vertices across pixels. Workaround: Only use these texture spaces on compatible geometry (auto axis on facetted Title Page geometry without smooth shading, cylindrical on cylinders, spherical on spheres), reduce the size of polygons. • Texture spaces with seams (cylindrical, spherical) cause rendering artifacts where the seam Contents runs through the middle of a polygon. OpenGL interpolates texture coordinates between vertices. This has the effect of stretching out the seam across the width of the polygon. First Last Workaround: Avoid using these texture spaces, position the geometry to try and hide the seam, try reducing the size of polygons to minimise the size of the artifact. • OpenGL doesn’t support the full Lightworks transparency model. liopengl uses an approx- J I imation which fails to match Lightworks rendering in some cases where filtered transparency (e.g., plain shader) is used. Coloured filters are approximated as grey scale. Bright primitive Page 109 of 119 colours with dark blend colours look too dark. Workaround: Use alpha based transparency shaders (such as the "plain coverage" shader), use dark primitive colours with bright blend colours rather than bright primitive colours Go Back with dark blend colours. • OpenGL does not support gamma correction. If the gamma correction feature of the Lightworks Search This Doc driver is used, the overall brightness of Lightworks rendered images and OpenGL rendered images will differ. Workaround: Set the Lightworks driver gamma (LI_CONTROL_DRIVER_GAMMA) to 1.0 and use Search All Docs the gamma correction features of the window system or graphics card.
• Lightworks Real-time does not support LiPrimitiveSetShadowReceive. Because of the Full Screen way shadows are calculated in real-time rendering, it is not currently possible to turn shadow receiving on and off on a per-primitive basis as you can with software rendering. A.3. Usage of Geometry Data
It is worth noting the following points about the use of geometry data;
A.3.1. Data caching Lightworks Author 9.0 During rendering, liopengl uses the currently set primitive list and attaches its own data to each primitive as additional primitive properties. This additional data is retained until the primitive is Lightworks invalidated using LiOpenGLPrimitiveInvalidate. Real-time
The geometry conversion mode dictates the way in which liopengl handles geometry the preferred mode will depend upon the performance and memory footprint requirements and the geometry source. Notes
• LI_OPENGL_CONV_MODE_TRIANGLE (the default) The primitive’s geometry is triangulated, the resultant polygon meshes being retained with the primitive. This is the fastest set -up, but is slower to render. • LI_OPENGL_CONV_MODE_DIRECT Additionally forms the triangular meshes into triangle strips. Master Doc This involves more set-up time, and adds to the size of the Lightworks data repository, but improves render times. Title Page • LI_OPENGL_CONV_MODE_LIST This additionally stores the tri-strips in OpenGL display lists cache (independently of the Lightworks data repository). Again there is a setup time but a further improvement in performance. Contents • LI_CONTROL_OPENGL_VERTEX_ARRAY This is similar to the ’display list’ option above except that OpenGL vertex arrays are used. Unlike display lists, vertex array data is accessible First Last between renders. Any updates to materials or texture spaces would force a rebuild of the display list, but not the vertex array. The use of vertex arrays is more appropriate where materials, texture spaces, or Lightworks lights are updated between renders. J I
Also consider the effect of the following... Page 110 of 119
• LI_CONTROL_OPENGL_PRESERVE_GEOMETRY Go Back
If this is set to TRUE, a copy of the Lightworks geometry is made before triangulation, subsequent Search This Doc rendering using Lightworks is thus unaffected. This would be appropriate if you want to execute a subsequent Lightworks render with different faceting settings without invalidating the primitive list (a full render might require view dependent faceting, and a wireframe render might want to display Search All Docs polygons without triangulation).
Full Screen A.3.2. Geometry expansion
Lightworks procedural and surface primitives are expanded as required by liopengl during rendering, and the expanded geometry is retained until the primitive is destroyed. There is currently no view frustum culling so primitives are expanded even if they are not in view.
Instance primitives are currently copied during expansion in Lightworks scanline and ray-trace Lightworks Author rendering, but liopengl send the original geometry and any transformation to OpenGL. Use of 9.0 Lightworks instance primitives is strongly recommended for liopengl implementations. Lightworks Real-time A.3.3. Incremental update of geometry
If a primitive is removed from the primitive list it will not be rendered by liopengl. Notes Any changes to a primitive are not registered in liopengl until the primitive is invalidated. Moving or scaling an existing primitive can be achieved by combining
LiPrimitiveSetTransform( prim,transform ); and Master Doc LiOpenGLPrimitiveInvalidate( prim, LI_OPENGL_INVALIDATE_TRANSFORM ); Title Page
Any cached geometry will be retained along with its material and texture space properties, but any subsequent liopengl render will use the new transformation. Contents
A.3.4. Presentation of geometry for Real-time Plus First Last
Real-time Plus rendering is best suited to certain types of scenes. Those with a relatively flat scene J I hierarchy will work best (i.e., many individual primitives with minimal grouping). Scenes with a deep hierarchy (for example many levels of groups nested within other groups) will not work as well. To get the best performance for such scenes it is currently recommended that some flattening of the Page 111 of 119 scene hierarchy is performed before the primitive list is presented for Real-time Plus rendering. Go Back
A.4. Known Problems Search This Doc
Known problems are listed below. These problems will be fixed in a future release. Search All Docs
• When using LI_OPENGL_WINDOW_MODE_LW and rendering to an archive driver, the size of the Full Screen image created is based on the current Lightworks view when LiOpenGLImageBegin is called, not the view passed to LiOpenGLViewSet. Workaround: Call LiViewSet with the required view before rendering. • Primitives facetted in LI_OPENGL_FACETING_LW mode may disappear when view dependent faceting is used. Workaround: Always use view independent faceting. • Materials containing wrapped colour and transparency shaders with different scales may not be sampled correctly Lightworks Author Workaround: None at present 9.0
• Multi-pass OpenGL rendering is currently not active during Real-time Plus rendering. Lightworks Workaround: If multi-pass rendering effects are required then it is necessary to perform Real-time a standard Lightworks Real-time (OpenGL) render once all Real-time Plus rendering has completed. • Real-time Plus does not support alpha-blended transparency. The only currently supported LI_CONTROL_OPENGL_TRANSPARENCY_- transparency modes (set via the control variable Notes MODE) are LI_OPENGL_TRANSPARENCY_MODE_NONE and LI_OPENGL_TRANSPARENCY_- MODE_STIPPLE. Setting the transparency mode to one of the blended modes will result in Real-time Plus rendering falling back to using STIPPLE mode. Workaround: As above: once the user/application has completed Real-time Plus rendering then it needs to perform a standard OpenGL render to see the higher quality transparency modes. Master Doc
Title Page A.5. OpenGL Compatibility Contents liopengl has been written to be compatible with the OpenGL 1.1 standard. Some implementations of OpenGL may diverge from the standard in subtle ways or may just have bugs. liopengl has been tested using software OpenGL and a selection of boards that we believe reflects the hardware in First Last current use. Problems have been found which required workarounds in liopengl, or the installation of an up to date driver obtained from the board manufacturer. J I Users are recommended to thoroughly test target configurations in order to identify problems as early as possible. End users should be advised to ensure they have the latest drivers available for Page 112 of 119 their boards. We will investigate any problems and aim to provide workarounds but cannot guarantee to work around every possible bug in a hardware driver (particularly if fixed in the latest drivers). Go Back liopengl is extensively tested with software OpenGL. Setting LI_CONTROL_OPENGL_- SOFTWARE_RENDER to TRUE forces the use of software OpenGL. This provides a fall back position that should work on all configurations. This control variable can also be used to confirm a suspected Search This Doc driver bug.
Search All Docs A.6. Tested Configurations Full Screen
The following configurations have been tested: Microsoft Software OpenGL Windows NT 4, Service Pack 3
• Lighting errors when local viewer lighting is disabled. Workaround: liopengl always enables local viewer lighting. • Memory leaks and stability problems with MCD based pixel formats. Workaround: liopengl never chooses an MCD based pixel format. Lightworks Author Microsoft Software OpenGL Windows 95 9.0 • No known problems. Lightworks Microsoft Software OpenGL Windows 98 Real-time
• No known problems.
ATI RADEON based boards Notes • Shadow maps fail to render properly, no known workaround at present.
3DLabs Permedia2 based boards
• Offsets for linear texture spaces calculated by glTexGen are ignored, resulting in incorrect positioning of textures in some cases. Master Doc Workaround: liopengl does not use glTexGen with Permedia2 boards.
3DLabs Oxygen VX1 Title Page
• Offsets for linear texture spaces calculated by glTexGen are ignored, resulting in incorrect positioning of textures in some cases. Contents Workaround: liopengl does not use glTexGen.
Intergraph Realizm First Last
• No known problems. J I 3DLabs Oxygen GVX1
• No known problems. Page 113 of 119
3DLabs Oxygen GMX Go Back • Some textures appear smeared.
Diamond FireGL 1000 Search This Doc • Alpha channel not interpolated between vertices Search All Docs Diamond Viper 550 (OS: NT SP4, BIOS: 1.93, Driver: 1.37)
• Minor lighting artifacts. Full Screen STB Velocity 128 (OS: 98, BIOS: 1.82, Driver: 4.10.01.0182) • Application crashes in driver when LiOpenGLTerminate is called if state is shared between contexts. Workaround: Set LI_CONTROL_OPENGL_SHARE_CONTEXTS to FALSE. • Alpha channel not interpolated between vertices
Other RIVA TNT and RIVA 128 based boards Lightworks Author LiOpenGLTerminate • Application may crash in driver when is called if state is shared 9.0 between contexts. Workaround: Install latest drivers, set LI_CONTROL_OPENGL_SHARE_CONTEXTS to Lightworks FALSE. Real-time • Minor texturing artifacts. • RIVA128 only - Artifacts using shadow maps
Matrox G400 and G450 Notes Application may crash in driver when LiOpenGLTerminate is called if state is shared between contexts. Workaround: Install latest drivers, set LI_CONTROL_OPENGL_SHARE_CONTEXTS to FALSE. Intel 830M integrated graphics chipsets Artifacts with transparent materials—see the note in Section A.2. Master Doc
Title Page A.7. System Requirements Contents Minimum system requirements for this release are as follows: First Last • OpenGL 1.1 • Lightworks 6.5 Lite J I • Windows NT 4.0 / Windows 95, or greater Page 114 of 119
Go Back
Search This Doc
Search All Docs
Full Screen Index Lightworks Author 9.0 (*LtFuncOpenGLGetModelTransform), 86 LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- TILE_BORDER, 98 Lightworks advanced multi-pass rendering, 29 LI_CONTROL_OPENGL_ANTIALIAS, 98 Real-time with Real-time, 29 LI_CONTROL_OPENGL_ANTIALIAS_SAMPLES, 93 Ambient Occlusion, 64 LI_CONTROL_OPENGL_APPLY_GAMMA_CORREC- annotations, 46 TION, 98 LI_CONTROL_OPENGL_BACKGROUND_QUALITY, call back functions 99 LI_CALL_OPENGL_MULTIPASS_RENDER, 30 LI_CONTROL_OPENGL_CLAMP_IMAGE_TEX- Index LI_OPENGL_PROC_CLASS_CALL_DESTROY, 51 TURES, 95 LI_OPENGL_PROC_CLASS_CALL_FLAGS, 51 LI_CONTROL_OPENGL_CLEAR_BUFFER, 99 LI_OPENGL_PROC_CLASS_CALL_INVALIDATE, LI_CONTROL_OPENGL_CLEAR_COLOUR, 99 49 LI_CONTROL_OPENGL_CONTRACT_GEOMETRY, 94 LI_OPENGL_PROC_CLASS_CALL_RENDER, 48 LI_CONTROL_OPENGL_CONV_MODE, 93 CgFX, 85 LI_CONTROL_OPENGL_DECAL_MODE, 99 Cocoa, 14 LI_CONTROL_OPENGL_DECALS_ENABLED, 95 Master Doc compatibility, 112 LI_CONTROL_OPENGL_DEFAULT_WIRE_COLOUR, which OpenGL standard?, 112 105 with hardware OpenGL boards, 112 LI_CONTROL_OPENGL_DISABLE_REFRACTION, control variable 99 Title Page LI_CONTROL_OPENGL_TRANSPARENCY_MODE, LI_CONTROL_OPENGL_DOUBLE_BUFFERED, 92 112 LI_CONTROL_OPENGL_EMULATE_PROG_- LI_CONTROL_OPENGL_CLEAR_COLOUR, 26 SHADERS, 96 LI_CONTROL_OPENGL_ENABLE_- LI_CONTROL_OPENGL_ENABLE_PRO- Contents PROGRAMMABLE_SHADING, 80 GRAMMABLE_SHADING, 44 LI_CONTROL_OPENGL_LIGHTING_CALC_, 109 LI_CONTROL_OPENGL_ENABLE_PRO- LI_CONTROL_OPENGL_PRESERVE_GEOMETRY, GRAMMABLE_SHADING, 99 First Last 110 LI_CONTROL_OPENGL_ENABLE_SOFT_SHADOWS, LI_CONTROL_OPENGL_SHADOW_DEPTH, 44 44 LI_CONTROL_OPENGL_SOFTWARE_RENDER, 112 LI_CONTROL_OPENGL_ENABLE_SOFT_SHADOWS, LI_CONTROL_OPENGL_TRANSPARENCY_MODE, 76 99 J I LI_CONTROL_OPENGL_VERTEX_ARRAY, 110 LI_CONTROL_OPENGL_ENVIRONMENT_LIGHT_- LI_CONTROL_OPENGL_WINDOW_MODE, 21 INTENSITY, 100 LI_CONTROL_PRESERVE_GEOMETRY, 101 LI_CONTROL_OPENGL_ENVIRONMENT_LIGHT_- LI_SESSION_VIEW_VAR_ACTIVE_STYLE, 18 MAX_ANGLE, 100 Page 115 of 119 LI_CONTROL_OGLDRV_STEREO_BUFFERS, 66 LI_CONTROL_OPENGL_ENVIRONMENT_LIGHT_- LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- QUALITY, 100 BLUR_MODE, 97 LI_CONTROL_OPENGL_FACETING, 94 Go Back LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- LI_CONTROL_OPENGL_GAMMA_CORRECTION_- BLUR_RADIUS, 97 FACTOR, 98 LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- LI_CONTROL_OPENGL_HOLD_IMAGE, 69 CONTRAST, 97 LI_CONTROL_OPENGL_HOLD_IMAGE, 100 Search This Doc LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- LI_CONTROL_OPENGL_IGNORE_TRANSPARENT_- DISPLAY, 97 PRIMS, 31 LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- LI_CONTROL_OPENGL_IGNORE_TRANSPARENT_- MODE, 97 PRIMS, 100 Search All Docs LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- LI_CONTROL_OPENGL_LIGHTING, 100 QUALITY, 98 LI_CONTROL_OPENGL_LIGHTING_CALC, 101 LI_CONTROL_OPENGL_AMBIENT_OCCLUSION_- LI_CONTROL_OPENGL_LINE_STIPPLE, 101 Full Screen RADIUS, 98 LI_CONTROL_OPENGL_LOWPOLY_THRESHOLD, 94 LI_CONTROL_OPENGL_MATERIAL, 101 LI_CONTROL_OPENGL_MAX_BG_TEXTURE_SIZE, LI_CONTROL_OPENGL_USER_CLIPPING_- 95 PLANES, 60 LI_CONTROL_OPENGL_MAX_IMAGE_TEXTURE_- SIZE, 95 data types LI_CONTROL_OPENGL_MAX_TEXTURE_SIZE, 95 CGeffect, 89 LI_CONTROL_OPENGL_MIPMAPPING, 95 LtBitfield, 52, 102 LI_CONTROL_OPENGL_POLYLINE_MODE, 94 LtEnum, 21 LI_CONTROL_OPENGL_PRESERVE_GEOMETRY, 94 LtMaterial, 72, 85 LI_CONTROL_OPENGL_REN_METHOD, 101 LtOpenGLMaterial, 72, 90 Lightworks Author LI_CONTROL_OPENGL_SHADING_LANGUAGE, 102 LtOpenGLProcRenContext, 52, 74 LI_CONTROL_OPENGL_SHADOW_AVAILABLE_- LtOpenGLTexCoord, 55 9.0 DEPTHS, 102 LtOpenGLTexCoords, 53, 56 LI_CONTROL_OPENGL_SHADOW_DEPTH, 102 depth of shadows, 44 Lightworks LI_CONTROL_OPENGL_SHADOW_DEPTH_BIAS, 45 LI_CONTROL_OPENGL_SHADOW_DEPTH_BIAS, geometry Real-time 103 best results with Real-time Plus, 111 LI_CONTROL_OPENGL_SHADOW_FILTER_SIZE, expansion of, 111 44 incremental update of, 111 LI_CONTROL_OPENGL_SHADOW_FILTER_SIZE, usage of geometry data, 110 103 LI_CONTROL_OPENGL_SHADOW_GRADIENT_- hardware OpenGL boards, 112 Index CLAMP, 45 list of tested configurations, 112 LI_CONTROL_OPENGL_SHADOW_GRADIENT_- CLAMP, 103 ImageEnd, 100 LI_CONTROL_OPENGL_SHADOW_MODE, 103 installation, 13 LI_CONTROL_OPENGL_SHADOW_OPTIONS, 103 invalidation, 37 LI_CONTROL_OPENGL_SHADOW_PENUMBRA_- WIDTH, 45 known problems, 111 Master Doc LI_CONTROL_OPENGL_SHADOW_PENUMBRA_- WIDTH, 103 LI_CALL_OPENGL_MULTIPASS_RENDER, 30 LI_CONTROL_OPENGL_SHARE_CONTEXTS, 92 LI_CONTROL _OPENGL_IGNORE_TRANSPARENT_- LI_CONTROL_OPENGL_SOFTWARE_RENDER, 92 PRIMS, 31 Title Page LI_CONTROL_OPENGL_STEREO_3D_FACTOR, 69 LI_OPENGL_INVALIDATE_ALL, 34 LI_CONTROL_OPENGL_STEREO_3D_FACTOR, 104 LI_OPENGL_INVALIDATE_CONTEXT, 34 LI_CONTROL_OPENGL_STEREO_BUFFERS, 93 LI_OPENGL_INVALIDATE_GEOMETRY, 34 Contents LI_CONTROL_OPENGL_STEREO_DISTANCE_FAC- LI_OPENGL_INVALIDATE_LIGHTING, 34 TOR, 69 LI_OPENGL_INVALIDATE_MATERIAL, 34 LI_CONTROL_OPENGL_STEREO_DISTANCE_FAC- LI_OPENGL_INVALIDATE_MATERIAL_REF, 34 TOR, 104 LI_OPENGL_INVALIDATE_TEXTURE_SPACE, 34 First Last LI_CONTROL_OPENGL_STEREO_MODE, 67 LI_OPENGL_INVALIDATE_TONE, 34 LI_CONTROL_OPENGL_STEREO_MODE, 104 LI_OPENGL_INVALIDATE_TRANSFORM, 34 LI_CONTROL_OPENGL_TEX_FIX_ORIENTATION, LI_OPENGL_MATERIAL_INVALIDATE_ALL, 36 95 LI_OPENGL_MATERIAL_INVALIDATE_COLOUR, 36 J I LI_CONTROL_OPENGL_TEXTURE_QUALITY, 96 LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_- LI_CONTROL_OPENGL_TEXTURES_ENABLED, 104 PARAMS, 36, 75 LI_CONTROL_OPENGL_TONE_AUTOSETUP, 104 LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_SCALE, Page 116 of 119 LI_CONTROL_OPENGL_TRANSPARENCY_MODE, 36, 75 104 LI_OPENGL_MATERIAL_INVALIDATE_COLOUR_- LI_CONTROL_OPENGL_USE_PRIMITIVE_- SHADER, 36, 75 FACET_REF, 94 LI_OPENGL_MATERIAL_INVALIDATE_DISPLACE- Go Back LI_CONTROL_OPENGL_USER_CLIPPING_- MENT_PARAMS, 36, 75 PLANES, 105 LI_OPENGL_MATERIAL_INVALIDATE_DISPLACE- MENT_SHADER, 36, 75 LI_CONTROL_OPENGL_WINDOW_MODE, 23 Search This Doc LI_CONTROL_OPENGL_WINDOW_MODE, 93 LI_OPENGL_MATERIAL_INVALIDATE_PIPELINE_- LI_CONTROL_OPENGL_WIRE_COLOUR, 105 PARAMS, 36, 75 LI_CONTROL_OGLDRV_ANTIALIAS_SAMPLES, 62 LI_OPENGL_MATERIAL_INVALIDATE_PIPELINE_- LI_CONTROL_OGLDRV_MAC_DRIVER_MODE, 22 SHADER, 36, 75 Search All Docs LI_CONTROL_OPENGL_ANTIALIAS, 62 LI_OPENGL_MATERIAL_INVALIDATE_RE- LI_CONTROL_OPENGL_APPLY_GAMMA_CORREC- FLECTANCE_PARAMS, 36, 75 TION, 62 LI_OPENGL_MATERIAL_INVALIDATE_RE- LI_CONTROL_OPENGL_GAMMA_CORRECTION_- FLECTANCE_SHADER, 36, 75 Full Screen FACTOR, 62 LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_- SPACE, 36, 75 LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_- LiOpenGLEvaluateTexCoordsInfo, 49, 53, 55, 56 SPACE_PARAMS, 36, 75 LiOpenGLEvaluateTexDerivs, 49, 56 LI_OPENGL_MATERIAL_INVALIDATE_TEXTURE_- LiOpenGLGeneralInvalidate, 37 SPACE_SHADER, 36, 75 LiOpenGLImageBegin, 23, 26, 31, 32, 40, 43, 63, 67, LI_OPENGL_MATERIAL_INVALIDATE_TRANSPARENCY, 69, 93, 95, 96, 102, 111 36 LiOpenGLImageEnd, 23, 27, 31, 32, 40, 43, 63, 69, 93, LI_OPENGL_MATERIAL_INVALIDATE_TRANS- 95, 96, 102 PARENCY_PARAMS, 36, 75 LiOpenGLInitialise, 21, 22, 26, 92 LI_OPENGL_MATERIAL_INVALIDATE_TRANS- LiOpenGLInvalidate, 38, 57 Lightworks Author PARENCY_SCALE, 36, 75 LiOpenGLInvalidateState, 38, 71, 76 LI_OPENGL_MATERIAL_INVALIDATE_TRANS- LiOpenGLLightGroupInvalidate, 37, 38 9.0 PARENCY_SHADER, 36, 75 LiOpenGLLightGroupReferenceInvalidate, 37, 38 LI_OPENGL_MATERIAL_INVALIDATE_VERTEX_- LiOpenGLLightListSet, 26, 71, 81 Lightworks PARAMS, 36, 75 LiOpenGLLightListSet(), 87 LI_OPENGL_MATERIAL_INVALIDATE_VERTEX_- LiOpenGLLightListShadowMapCreate, 43 Real-time SHADER, 36, 75 LiOpenGLLightSet, 32 LI_OPENGL_QUERY_LIGHT_SUPPORT_SHADOWS, 39 LiOpenGLLineStippleGet, 61 LI_OPENGL_QUERY_MAX_CLIP_PLANES, 39 LiOpenGLLineStippleSet, 61 LI_OPENGL_QUERY_MAX_PROG_LIGHTS, 39 LiOpenGLMaterialBeginPass, 74, 82 LI_OPENGL_QUERY_MAX_PROG_SHADOW_LIGHTS, 39 LiOpenGLMaterialCreate, 72 LI_OPENGL_QUERY_PROGRAMMABLE_LANGUAGES, 39 LiOpenGLMaterialDestroy, 72 Index LI_OPENGL_QUERY_RENDERER, 39 LiOpenGLMaterialEndPass, 74, 82 LI_OPENGL_QUERY_SHADOW_DEPTHS, 39 LiOpenGLMaterialGet, 72, 90 LI_OPENGL_QUERY_SSAO_SUPPORT, 39 LiOpenGLMaterialGetNumPasses, 73 LI_OPENGL_QUERY_VENDOR, 39 LiOpenGLMaterialInvalidate, 35–38, 81, 82 LI_OPENGL_QUERY_VERSION, 39 LiOpenGLMaterialIsBlend, 76 LI_OPENGL_SHADER_INVALIDATE_ALL, 36 LiOpenGLMaterialRepInvalidate, 38, 75, 82 LI_OPENGL_SHADER_INVALIDATE_DESTROY, 36 LiOpenGLMaterialSet, 72, 73, 90 Master Doc LI_OPENGL_SHADER_INVALIDATE_PARAMS, 36 LiOpenGLPolygonOffsetDisable, 27, 28 LI_OPENGL_SHADER_INVALIDATE_SHADER, 36 LiOpenGLPolygonOffsetEnable, 27, 28 LI_OPENGL_SHADER_INVALIDATE_SHADOW_MAP, 36 LiOpenGLPrimitiveInvalidate, 19, 33–35, 37, 38, LI_CONTROL_OGLDRV_MAC_DRIVER_MODE, 22 110 Title Page LI_OGLDRV_MAC_DRIVER_MODE_CARBON, 22 LiOpenGLPrimitiveListInvalidate, 19, 33, 34, 38 LI_OGLDRV_MAC_DRIVER_MODE_COCOA, 22 LiOpenGLPrimitiveListRender, 27, 29 lidrvcca, 14 LiOpenGLPrimitiveRender, 23, 29, 32 Contents LiEntityCreateRenderStyle, 19 LiOpenGLPrimitiveSetProceduralClass, 52 LiEnvironmentSet, 57 LiOpenGLProceduralClassCreate, 47 light groups, 37 LiOpenGLProceduralClassDestroy, 52 LiHDRIImageBlur, 59, 100 LiOpenGLProceduralClassSetCallback, 48 First Last LiHDRIImageResize, 59, 100 LiOpenGLProcRenContextQuery, 52 LiInitialise, 13 LiOpenGLProcRenEvalColour, 49, 53 LiInstallModule, 13 LiOpenGLProcRenEvalLighting, 49, 57 LiInterfaceCreate, 24 LiOpenGLQuery, 30, 38, 83 J I LiInterfaceDestroy, 24 LiOpenGLRender, 30 limitations LiOpenGLRender, 22, 23, 25, 26, 29, 30, 81, 103 of OpenGL, 108 LiOpenGLRenderHiddenLine, 62 Page 117 of 119 linking, 14 LiOpenGLSceneBeginPass, 29 LiOGLDrvContextGetData, 41 LiOpenGLSceneEndPass, 29 LiOGLDrvExtensionGetFunction, 63 LiOpenGLSceneGetNumPasses, 28 LiOGLDrvExtensionQuery, 63 LiOpenGLSetAnnotationFunction, 47 Go Back LiOGLDrvWindowInitialise, 23 LiOpenGLSetTexCoords, 56 LiOGLDrvWindowInitialise(), 23 LiOpenGLSetTexCoordsInfo, 56 LiOGLDrvWindowSetCurrent, 23 LiOpenGLShaderInvalidate, 19, 36–38, 81 Search This Doc LiOGLDrvWindowTerminate, 23 LiOpenGLShadowMapCreate, 42, 43 LiOpenGLBackgroundSet, 26, 99 LiOpenGLShadowMapIsAvailable, 43 LiOpenGLBindCgFXLight, 87 LiOpenGLShadowMapIsValid, 43 LiOpenGLBindCgFXLight(), 87 LiOpenGLTerminate, 22, 26, 40, 92 Search All Docs LiOpenGLClipPlaneGet, 60 LiOpenGLTexCoordsCreate, 54 LiOpenGLClipPlaneSet, 60 LiOpenGLTexCoordsDestroy, 56 LiOpenGLDecalInvalidate, 82 LiOpenGLTexCoordsGet, 54 LiOpenGLDecalRepInvalidate, 82 LiOpenGLToneListInvalidate, 27, 38 Full Screen LiOpenGLEvaluateTexCoords, 53 LiOpenGLToneListSet, 27, 104 LiOpenGLViewSet, 26, 68, 69, 71, 111 soft shadows, 44 LiOpenGLWindowInitialise, 40 SSAO, 64 LiOpenGLWindowSetCurrent, 41 Stereoscopic Rendering, 66 LiOpenGLWindowTerminate, 40, 41 system requirements LiPrimitiveSetShadowReceive, 46, 109 minimum requirements, 114 LiRenderStyleExecute, 23, 24, 67, 68 LiSessionViewUpdate, 19 Windows API, 40 LiViewSet, 68, 69, 112 Lightworks Author materials API, 71 multi-pass rendering, 28 9.0 with Real-time, 28 with Real-time Plus, 112 Lightworks object level API, 26 Real-time OpenGL anti-aliasing, 62 clipping planes, 60 environment maps, 57 extensions, 62 Index gamma correction, 62 hidden line, 61 limitations, 108 line types, 61 making direct calls to, 63 OpenGL compatibility, 112 primitive level API, 32 Master Doc problems known problems, 111 programmable shading, 80 Title Page Quad Buffer Stereo, 66 Querying Lightworks Real-time information, 38 Contents Real-time advanced multi-pass rendering, 29 known problems, 111 multi-pass rendering, 28 First Last rendering multiple lights, 29 using Lightworks material API with external render- ers, 71 using the core API, 21 J I using the GUI Framework, 16 using the Session Manager, 18 Real-time Plus, 13 Page 118 of 119 known problems, 112 multi-pass rendering, 112 presenting geometry for, 111 render styles, 24 Go Back resolution of shadows, 43 scene level API, 25 Search This Doc shading programmable, 80 CgFX, 85 shadow map, 42 Search All Docs shadows, 42 depth of, 44 resolution, 43 Full Screen shadow map creation, 42 soft, 44 Lightworks Documentation Feedback
Please help us to improve our documentation by taking the time to complete and return this form, once you are familiar with the product. You may photocopy this page.
Your name: Date:
Your job title: Company: Lightworks Author 9.0 How many years programming experience do you have? C: C++: Other (please specify): Lightworks Real-time How would you rate your level of knowledge and experience of 3D computer graphics? 2 Relative novice 2 Competent 2 Expert
Name of manual: Part No. (given on first page of each manual) :
How would you rate the clarity of the manual? 2 Good 2 Satisfactory 2 Poor Do you feel that the manual is pitched at the right level technically? 2 Yes 2 No, it’s too simple 2 No, it’s too technical Master Doc How would you rate the use of examples in the manual? 2 Good 2 Satisfactory 2 Poor Title Page Were there any sections or concepts which could be made clearer by the use of more examples? 2 No 2 Yes If ‘Yes’, give details: Contents Were there any sections or concepts where the explanation given in the text was confusing or 2 No 2 Yes If ‘Yes’, give details: lacking? First Last How would you rate the overall standard of the manual? 2 Excellent 2 Good 2 Satisfactory 2 Below average 2 Poor J I
Additional comments (attach additional sheets if required): Page 119 of 119
Go Back
Search This Doc
Search All Docs
Full Screen