[1092] | 1 | /*
|
---|
| 2 | -----------------------------------------------------------------------------
|
---|
| 3 | This source file is part of OGRE
|
---|
| 4 | (Object-oriented Graphics Rendering Engine)
|
---|
| 5 | For the latest info, see http://ogre.sourceforge.net/
|
---|
| 6 |
|
---|
| 7 | Copyright (c) 2000-2005 The OGRE Team
|
---|
| 8 | Also see acknowledgements in Readme.html
|
---|
| 9 |
|
---|
| 10 | This program is free software; you can redistribute it and/or modify it under
|
---|
| 11 | the terms of the GNU Lesser General Public License as published by the Free Software
|
---|
| 12 | Foundation; either version 2 of the License, or (at your option) any later
|
---|
| 13 | version.
|
---|
| 14 |
|
---|
| 15 | This program is distributed in the hope that it will be useful, but WITHOUT
|
---|
| 16 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
|
---|
| 17 | FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
|
---|
| 18 |
|
---|
| 19 | You should have received a copy of the GNU Lesser General Public License along with
|
---|
| 20 | this program; if not, write to the Free Software Foundation, Inc., 59 Temple
|
---|
| 21 | Place - Suite 330, Boston, MA 02111-1307, USA, or go to
|
---|
| 22 | http://www.gnu.org/copyleft/lesser.txt.
|
---|
| 23 | -----------------------------------------------------------------------------
|
---|
| 24 | */
|
---|
| 25 | #ifndef __RenderSystem_H_
|
---|
| 26 | #define __RenderSystem_H_
|
---|
| 27 |
|
---|
| 28 | // Precompiler options
|
---|
| 29 | #include "OgrePrerequisites.h"
|
---|
| 30 |
|
---|
| 31 | #include "OgreString.h"
|
---|
| 32 |
|
---|
| 33 | #include "OgreTextureUnitState.h"
|
---|
| 34 | #include "OgreCommon.h"
|
---|
| 35 |
|
---|
| 36 | #include "OgreRenderOperation.h"
|
---|
| 37 | #include "OgreRenderSystemCapabilities.h"
|
---|
| 38 | #include "OgreRenderTarget.h"
|
---|
| 39 | #include "OgreRenderTexture.h"
|
---|
| 40 | #include "OgreFrameListener.h"
|
---|
| 41 | #include "OgreConfigOptionMap.h"
|
---|
| 42 | #include "OgreGpuProgram.h"
|
---|
| 43 | #include "OgrePlane.h"
|
---|
| 44 | #include "OgreIteratorWrappers.h"
|
---|
| 45 |
|
---|
| 46 | namespace Ogre
|
---|
| 47 | {
|
---|
| 48 | typedef std::map< String, RenderTarget * > RenderTargetMap;
|
---|
| 49 | typedef std::multimap<uchar, RenderTarget * > RenderTargetPriorityMap;
|
---|
| 50 |
|
---|
| 51 | class TextureManager;
|
---|
| 52 | /// Enum describing the ways to generate texture coordinates
|
---|
| 53 | enum TexCoordCalcMethod
|
---|
| 54 | {
|
---|
| 55 | /// No calculated texture coordinates
|
---|
| 56 | TEXCALC_NONE,
|
---|
| 57 | /// Environment map based on vertex normals
|
---|
| 58 | TEXCALC_ENVIRONMENT_MAP,
|
---|
| 59 | /// Environment map based on vertex positions
|
---|
| 60 | TEXCALC_ENVIRONMENT_MAP_PLANAR,
|
---|
| 61 | TEXCALC_ENVIRONMENT_MAP_REFLECTION,
|
---|
| 62 | TEXCALC_ENVIRONMENT_MAP_NORMAL,
|
---|
| 63 | /// Projective texture
|
---|
| 64 | TEXCALC_PROJECTIVE_TEXTURE
|
---|
| 65 | };
|
---|
| 66 | /// Enum describing the various actions which can be taken onthe stencil buffer
|
---|
| 67 | enum StencilOperation
|
---|
| 68 | {
|
---|
| 69 | /// Leave the stencil buffer unchanged
|
---|
| 70 | SOP_KEEP,
|
---|
| 71 | /// Set the stencil value to zero
|
---|
| 72 | SOP_ZERO,
|
---|
| 73 | /// Set the stencil value to the reference value
|
---|
| 74 | SOP_REPLACE,
|
---|
| 75 | /// Increase the stencil value by 1, clamping at the maximum value
|
---|
| 76 | SOP_INCREMENT,
|
---|
| 77 | /// Decrease the stencil value by 1, clamping at 0
|
---|
| 78 | SOP_DECREMENT,
|
---|
| 79 | /// Increase the stencil value by 1, wrapping back to 0 when incrementing the maximum value
|
---|
| 80 | SOP_INCREMENT_WRAP,
|
---|
| 81 | /// Decrease the stencil value by 1, wrapping when decrementing 0
|
---|
| 82 | SOP_DECREMENT_WRAP,
|
---|
| 83 | /// Invert the bits of the stencil buffer
|
---|
| 84 | SOP_INVERT
|
---|
| 85 | };
|
---|
| 86 |
|
---|
| 87 | /** Defines the frame buffers which can be cleared. */
|
---|
| 88 | enum FrameBufferType {
|
---|
| 89 | FBT_COLOUR = 0x1,
|
---|
| 90 | FBT_DEPTH = 0x2,
|
---|
| 91 | FBT_STENCIL = 0x4
|
---|
| 92 | };
|
---|
| 93 |
|
---|
| 94 | /** Defines the functionality of a 3D API
|
---|
| 95 | @remarks
|
---|
| 96 | The RenderSystem class provides a base interface
|
---|
| 97 | which abstracts the general functionality of the 3D API
|
---|
| 98 | e.g. Direct3D or OpenGL. Whilst a few of the general
|
---|
| 99 | methods have implementations, most of this class is
|
---|
| 100 | abstract, requiring a subclass based on a specific API
|
---|
| 101 | to be constructed to provide the full functionality.
|
---|
| 102 | Note there are 2 levels to the interface - one which
|
---|
| 103 | will be used often by the caller of the Ogre library,
|
---|
| 104 | and one which is at a lower level and will be used by the
|
---|
| 105 | other classes provided by Ogre. These lower level
|
---|
| 106 | methods are prefixed with '_' to differentiate them.
|
---|
| 107 | The advanced user of the library may use these lower
|
---|
| 108 | level methods to access the 3D API at a more fundamental
|
---|
| 109 | level (dealing direct with render states and rendering
|
---|
| 110 | primitives), but still benefitting from Ogre's abstraction
|
---|
| 111 | of exactly which 3D API is in use.
|
---|
| 112 | @author
|
---|
| 113 | Steven Streeting
|
---|
| 114 | @version
|
---|
| 115 | 1.0
|
---|
| 116 | */
|
---|
| 117 | class _OgreExport RenderSystem
|
---|
| 118 | {
|
---|
| 119 | public:
|
---|
| 120 | /** Default Constructor.
|
---|
| 121 | */
|
---|
| 122 | RenderSystem();
|
---|
| 123 |
|
---|
| 124 | /** Destructor.
|
---|
| 125 | */
|
---|
| 126 | virtual ~RenderSystem();
|
---|
| 127 |
|
---|
| 128 | /** Returns the name of the rendering system.
|
---|
| 129 | */
|
---|
| 130 | virtual const String& getName(void) const = 0;
|
---|
| 131 |
|
---|
| 132 | /** Returns the details of this API's configuration options
|
---|
| 133 | @remarks
|
---|
| 134 | Each render system must be able to inform the world
|
---|
| 135 | of what options must/can be specified for it's
|
---|
| 136 | operation.
|
---|
| 137 | @par
|
---|
| 138 | These are passed as strings for portability, but
|
---|
| 139 | grouped into a structure (_ConfigOption) which includes
|
---|
| 140 | both options and current value.
|
---|
| 141 | @par
|
---|
| 142 | Note that the settings returned from this call are
|
---|
| 143 | affected by the options that have been set so far,
|
---|
| 144 | since some options are interdependent.
|
---|
| 145 | @par
|
---|
| 146 | This routine is called automatically by the default
|
---|
| 147 | configuration dialogue produced by Root::showConfigDialog
|
---|
| 148 | or may be used by the caller for custom settings dialogs
|
---|
| 149 | @returns
|
---|
| 150 | A 'map' of options, i.e. a list of options which is also
|
---|
| 151 | indexed by option name.
|
---|
| 152 | */
|
---|
| 153 | virtual ConfigOptionMap& getConfigOptions(void) = 0;
|
---|
| 154 |
|
---|
| 155 | /** Sets an option for this API
|
---|
| 156 | @remarks
|
---|
| 157 | Used to confirm the settings (normally chosen by the user) in
|
---|
| 158 | order to make the renderer able to initialise with the settings as required.
|
---|
| 159 | This may be video mode, D3D driver, full screen / windowed etc.
|
---|
| 160 | Called automatically by the default configuration
|
---|
| 161 | dialog, and by the restoration of saved settings.
|
---|
| 162 | These settings are stored and only activated when
|
---|
| 163 | RenderSystem::initialise or RenderSystem::reinitialise
|
---|
| 164 | are called.
|
---|
| 165 | @par
|
---|
| 166 | If using a custom configuration dialog, it is advised that the
|
---|
| 167 | caller calls RenderSystem::getConfigOptions
|
---|
| 168 | again, since some options can alter resulting from a selection.
|
---|
| 169 | @param
|
---|
| 170 | name The name of the option to alter.
|
---|
| 171 | @param
|
---|
| 172 | value The value to set the option to.
|
---|
| 173 | */
|
---|
| 174 | virtual void setConfigOption(const String &name, const String &value) = 0;
|
---|
| 175 |
|
---|
| 176 | virtual HardwareOcclusionQuery* createHardwareOcclusionQuery() = 0;
|
---|
| 177 |
|
---|
| 178 | /** Validates the options set for the rendering system, returning a message if there are problems.
|
---|
| 179 | @note
|
---|
| 180 | If the returned string is empty, there are no problems.
|
---|
| 181 | */
|
---|
| 182 | virtual String validateConfigOptions(void) = 0;
|
---|
| 183 |
|
---|
| 184 | /** Start up the renderer using the settings selected (Or the defaults if none have been selected).
|
---|
| 185 | @remarks
|
---|
| 186 | Called by Root::setRenderSystem. Shouldn't really be called
|
---|
| 187 | directly, although this can be done if the app wants to.
|
---|
| 188 | @param
|
---|
| 189 | autoCreateWindow If true, creates a render window
|
---|
| 190 | automatically, based on settings chosen so far. This saves
|
---|
| 191 | an extra call to RenderSystem::createRenderWindow
|
---|
| 192 | for the main render window.
|
---|
| 193 | @par
|
---|
| 194 | If an application has more specific window requirements,
|
---|
| 195 | however (e.g. a level design app), it should specify false
|
---|
| 196 | for this parameter and do it manually.
|
---|
| 197 | @returns
|
---|
| 198 | A pointer to the automatically created window, if requested, otherwise null.
|
---|
| 199 | */
|
---|
| 200 | virtual RenderWindow* initialise(bool autoCreateWindow, const String& windowTitle = "OGRE Render Window");
|
---|
| 201 |
|
---|
| 202 | /** Restart the renderer (normally following a change in settings).
|
---|
| 203 | */
|
---|
| 204 | virtual void reinitialise(void) = 0;
|
---|
| 205 |
|
---|
| 206 | /** Shutdown the renderer and cleanup resources.
|
---|
| 207 | */
|
---|
| 208 | virtual void shutdown(void);
|
---|
| 209 |
|
---|
| 210 |
|
---|
| 211 | /** Sets the colour & strength of the ambient (global directionless) light in the world.
|
---|
| 212 | */
|
---|
| 213 | virtual void setAmbientLight(float r, float g, float b) = 0;
|
---|
| 214 |
|
---|
| 215 | /** Sets the type of light shading required (default = Gouraud).
|
---|
| 216 | */
|
---|
| 217 | virtual void setShadingType(ShadeOptions so) = 0;
|
---|
| 218 |
|
---|
| 219 | /** Sets whether or not dynamic lighting is enabled.
|
---|
| 220 | @param
|
---|
| 221 | enabled If true, dynamic lighting is performed on geometry with normals supplied, geometry without
|
---|
| 222 | normals will not be displayed. If false, no lighting is applied and all geometry will be full brightness.
|
---|
| 223 | */
|
---|
| 224 | virtual void setLightingEnabled(bool enabled) = 0;
|
---|
| 225 |
|
---|
| 226 | /** Sets whether or not W-buffers are enabled if they are avalible for this renderer.
|
---|
| 227 | @param
|
---|
| 228 | enabled If true and the renderer supports them W-buffers will be used. If false
|
---|
| 229 | W-buffers will not be used even if avalible. W-buffers are enabled by default
|
---|
| 230 | for 16bit depth buffers and disabled for all other depths.
|
---|
| 231 | */
|
---|
| 232 | void setWBufferEnabled(bool enabled);
|
---|
| 233 |
|
---|
| 234 | /** Returns true if the renderer will try to use W-buffers when avalible.
|
---|
| 235 | */
|
---|
| 236 | bool getWBufferEnabled(void) const;
|
---|
| 237 |
|
---|
| 238 | /** Creates a new rendering window.
|
---|
| 239 | @remarks
|
---|
| 240 | This method creates a new rendering window as specified
|
---|
| 241 | by the paramteters. The rendering system could be
|
---|
| 242 | responible for only a single window (e.g. in the case
|
---|
| 243 | of a game), or could be in charge of multiple ones (in the
|
---|
| 244 | case of a level editor). The option to create the window
|
---|
| 245 | as a child of another is therefore given.
|
---|
| 246 | This method will create an appropriate subclass of
|
---|
| 247 | RenderWindow depending on the API and platform implementation.
|
---|
| 248 | @par
|
---|
| 249 | After creation, this window can be retrieved using getRenderTarget().
|
---|
| 250 | @param
|
---|
| 251 | name The name of the window. Used in other methods
|
---|
| 252 | later like setRenderTarget and getRenderWindow.
|
---|
| 253 | @param
|
---|
| 254 | width The width of the new window.
|
---|
| 255 | @param
|
---|
| 256 | height The height of the new window.
|
---|
| 257 | @param
|
---|
| 258 | fullScreen Specify true to make the window full screen
|
---|
| 259 | without borders, title bar or menu bar.
|
---|
| 260 | @param
|
---|
| 261 | miscParams A NameValuePairList describing the other parameters for the new rendering window.
|
---|
| 262 | Options are case sensitive. Unrecognised parameters will be ignored silently.
|
---|
| 263 | These values might be platform dependent, but these are present for all platorms unless
|
---|
| 264 | indicated otherwise:
|
---|
| 265 | **
|
---|
| 266 | Key: "title"
|
---|
| 267 | Description: The title of the window that will appear in the title bar
|
---|
| 268 | Values: string
|
---|
| 269 | Default: RenderTarget name
|
---|
| 270 | **
|
---|
| 271 | Key: "colourDepth"
|
---|
| 272 | Description: Colour depth of the resulting rendering window; only applies if fullScreen
|
---|
| 273 | is set.
|
---|
| 274 | Values: 16 or 32
|
---|
| 275 | Default: desktop depth
|
---|
| 276 | Notes: [W32 specific]
|
---|
| 277 | **
|
---|
| 278 | Key: "left"
|
---|
| 279 | Description: screen x coordinate from left
|
---|
| 280 | Values: positive integers
|
---|
| 281 | Default: 'center window on screen'
|
---|
| 282 | Notes: Ignored in case of full screen
|
---|
| 283 | **
|
---|
| 284 | Key: "top"
|
---|
| 285 | Description: screen y coordinate from top
|
---|
| 286 | Values: positive integers
|
---|
| 287 | Default: 'center window on screen'
|
---|
| 288 | Notes: Ignored in case of full screen
|
---|
| 289 | **
|
---|
| 290 | Key: "depthBuffer" [DX9 specific]
|
---|
| 291 | Description: Use depth buffer
|
---|
| 292 | Values: false or true
|
---|
| 293 | Default: true
|
---|
| 294 | **
|
---|
| 295 | Key: "externalWindowHandle" [API specific]
|
---|
| 296 | Description: External window handle, for embedding the OGRE context
|
---|
| 297 | Values: positive integer for W32 (HWND handle)
|
---|
| 298 | poslong:posint:poslong (display*:screen:windowHandle) or
|
---|
| 299 | poslong:posint:poslong:poslong (display*:screen:windowHandle:XVisualInfo*) for GLX
|
---|
| 300 | Default: 0 (None)
|
---|
| 301 | **
|
---|
| 302 | Key: "parentWindowHandle" [API specific]
|
---|
| 303 | Description: Parent window handle, for embedding the OGRE context
|
---|
| 304 | Values: positive integer for W32 (HWND handle)
|
---|
| 305 | poslong:posint:poslong for GLX (display*:screen:windowHandle)
|
---|
| 306 | Default: 0 (None)
|
---|
| 307 | **
|
---|
| 308 | Key: "FSAA"
|
---|
| 309 | Description: Full screen antialiasing factor
|
---|
| 310 | Values: 0,2,4,6,...
|
---|
| 311 | Default: 0
|
---|
| 312 | **
|
---|
| 313 | Key: "displayFrequency"
|
---|
| 314 | Description: Display frequency rate, for fullscreen mode
|
---|
| 315 | Values: 60...?
|
---|
| 316 | Default: Desktop vsync rate
|
---|
| 317 | **
|
---|
| 318 | Key: "vsync"
|
---|
| 319 | Description: Synchronize buffer swaps to vsync
|
---|
| 320 | Values: true, false
|
---|
| 321 | Default: 0
|
---|
| 322 | **
|
---|
| 323 | Key: "border"
|
---|
| 324 | Description: The type of window border (in windowed mode)
|
---|
| 325 | Values: none, fixed, resize
|
---|
| 326 | Default: resize
|
---|
| 327 | **
|
---|
| 328 | Key: "outerDimensions"
|
---|
| 329 | Description: Whether the width/height is expressed as the size of the
|
---|
| 330 | outer window, rather than the content area
|
---|
| 331 | Values: true, false
|
---|
| 332 | Default: false
|
---|
| 333 | */
|
---|
| 334 | virtual RenderWindow* createRenderWindow(const String &name, unsigned int width, unsigned int height,
|
---|
| 335 | bool fullScreen, const NameValuePairList *miscParams = 0) = 0;
|
---|
| 336 |
|
---|
| 337 | /** Creates and registers a render texture object.
|
---|
| 338 | @param name
|
---|
| 339 | The name for the new render texture. Note that names must be unique.
|
---|
| 340 | @param width
|
---|
| 341 | The requested width for the render texture. See Remarks for more info.
|
---|
| 342 | @param height
|
---|
| 343 | The requested width for the render texture. See Remarks for more info.
|
---|
| 344 | @param texType
|
---|
| 345 | The type of texture; defaults to TEX_TYPE_2D
|
---|
| 346 | @param internalFormat
|
---|
| 347 | The internal format of the texture; defaults to PF_X8R8G8B8
|
---|
| 348 | @param miscParams A NameValuePairList describing the other parameters for the new rendering window.
|
---|
| 349 | Unrecognised parameters will be ignored silently.
|
---|
| 350 | These values might be platform dependent, but these are present for all platorms unless
|
---|
| 351 | indicated otherwise:
|
---|
| 352 | **
|
---|
| 353 | Key: "FSAA"
|
---|
| 354 | Description: Full screen antialiasing factor
|
---|
| 355 | Values: 0,2,4,6,...
|
---|
| 356 | Default: 0
|
---|
| 357 | **
|
---|
| 358 | Key: "depth"
|
---|
| 359 | Description: Depth in case of render-to-texture TEX_3D
|
---|
| 360 | Values: positive integers
|
---|
| 361 | @returns
|
---|
| 362 | On succes, a pointer to a new platform-dependernt, RenderTexture-derived
|
---|
| 363 | class is returned. On failiure, NULL is returned.
|
---|
| 364 | @remarks
|
---|
| 365 | Because a render texture is basically a wrapper around a texture object,
|
---|
| 366 | the width and height parameters of this method just hint the preferred
|
---|
| 367 | size for the texture. Depending on the hardware driver or the underlying
|
---|
| 368 | API, these values might change when the texture is created. The same applies
|
---|
| 369 | to the internalFormat parameter.
|
---|
| 370 | */
|
---|
| 371 | virtual RenderTexture * createRenderTexture( const String & name, unsigned int width, unsigned int height,
|
---|
| 372 | TextureType texType = TEX_TYPE_2D, PixelFormat internalFormat = PF_X8R8G8B8,
|
---|
| 373 | const NameValuePairList *miscParams = 0 ) = 0;
|
---|
| 374 |
|
---|
| 375 | /** Destroys a render window */
|
---|
| 376 | virtual void destroyRenderWindow(const String& name);
|
---|
| 377 | /** Destroys a render texture */
|
---|
| 378 | virtual void destroyRenderTexture(const String& name);
|
---|
| 379 | /** Destroys a render target of any sort */
|
---|
| 380 | virtual void destroyRenderTarget(const String& name);
|
---|
| 381 |
|
---|
| 382 | /** Attaches the passed render target to the render system.
|
---|
| 383 | */
|
---|
| 384 | virtual void attachRenderTarget( RenderTarget &target );
|
---|
| 385 | /** Returns a pointer to the render target with the passed name, or NULL if that
|
---|
| 386 | render target cannot be found.
|
---|
| 387 | */
|
---|
| 388 | virtual RenderTarget * getRenderTarget( const String &name );
|
---|
| 389 | /** Detaches the render target with the passed name from the render system and
|
---|
| 390 | returns a pointer to it.
|
---|
| 391 | @note
|
---|
| 392 | If the render target cannot be found, NULL is returned.
|
---|
| 393 | */
|
---|
| 394 | virtual RenderTarget * detachRenderTarget( const String &name );
|
---|
| 395 |
|
---|
| 396 | /// Iterator over RenderTargets
|
---|
| 397 | typedef MapIterator<Ogre::RenderTargetMap> RenderTargetIterator;
|
---|
| 398 |
|
---|
| 399 | /** Returns a specialised MapIterator over all render targets attached to the RenderSystem. */
|
---|
| 400 | virtual RenderTargetIterator getRenderTargetIterator(void) {
|
---|
| 401 | return RenderTargetIterator( mRenderTargets.begin(), mRenderTargets.end() );
|
---|
| 402 | }
|
---|
| 403 | /** Returns a description of an error code.
|
---|
| 404 | */
|
---|
| 405 | virtual String getErrorDescription(long errorNumber) const = 0;
|
---|
| 406 |
|
---|
| 407 | /** Defines whether or now fullscreen render windows wait for the vertical blank before flipping buffers.
|
---|
| 408 | @remarks
|
---|
| 409 | By default, all rendering windows wait for a vertical blank (when the CRT beam turns off briefly to move
|
---|
| 410 | from the bottom right of the screen back to the top left) before flipping the screen buffers. This ensures
|
---|
| 411 | that the image you see on the screen is steady. However it restricts the frame rate to the refresh rate of
|
---|
| 412 | the monitor, and can slow the frame rate down. You can speed this up by not waiting for the blank, but
|
---|
| 413 | this has the downside of introducing 'tearing' artefacts where part of the previous frame is still displayed
|
---|
| 414 | as the buffers are switched. Speed vs quality, you choose.
|
---|
| 415 | @note
|
---|
| 416 | Has NO effect on windowed mode render targets. Only affects fullscreen mode.
|
---|
| 417 | @param
|
---|
| 418 | enabled If true, the system waits for vertical blanks - quality over speed. If false it doesn't - speed over quality.
|
---|
| 419 | */
|
---|
| 420 | void setWaitForVerticalBlank(bool enabled);
|
---|
| 421 |
|
---|
| 422 | /** Returns true if the system is synchronising frames with the monitor vertical blank.
|
---|
| 423 | */
|
---|
| 424 | bool getWaitForVerticalBlank(void) const;
|
---|
| 425 |
|
---|
| 426 | // ------------------------------------------------------------------------
|
---|
| 427 | // Internal Rendering Access
|
---|
| 428 | // All methods below here are normally only called by other OGRE classes
|
---|
| 429 | // They can be called by library user if required
|
---|
| 430 | // ------------------------------------------------------------------------
|
---|
| 431 |
|
---|
| 432 |
|
---|
| 433 | /** Tells the rendersystem to use the attached set of lights (and no others)
|
---|
| 434 | up to the number specified (this allows the same list to be used with different
|
---|
| 435 | count limits) */
|
---|
| 436 | virtual void _useLights(const LightList& lights, unsigned short limit) = 0;
|
---|
| 437 | /** Sets the world transform matrix. */
|
---|
| 438 | virtual void _setWorldMatrix(const Matrix4 &m) = 0;
|
---|
| 439 | /** Sets multiple world matrices (vertex blending). */
|
---|
| 440 | virtual void _setWorldMatrices(const Matrix4* m, unsigned short count);
|
---|
| 441 | /** Sets the view transform matrix */
|
---|
| 442 | virtual void _setViewMatrix(const Matrix4 &m) = 0;
|
---|
| 443 | /** Sets the projection transform matrix */
|
---|
| 444 | virtual void _setProjectionMatrix(const Matrix4 &m) = 0;
|
---|
| 445 | /** Utility function for setting all the properties of a texture unit at once.
|
---|
| 446 | This method is also worth using over the individual texture unit settings because it
|
---|
| 447 | only sets those settings which are different from the current settings for this
|
---|
| 448 | unit, thus minimising render state changes.
|
---|
| 449 | */
|
---|
| 450 | virtual void _setTextureUnitSettings(size_t texUnit, TextureUnitState& tl);
|
---|
| 451 | /** Turns off a texture unit. */
|
---|
| 452 | virtual void _disableTextureUnit(size_t texUnit);
|
---|
| 453 | /** Disables all texture units from the given unit upwards */
|
---|
| 454 | virtual void _disableTextureUnitsFrom(size_t texUnit);
|
---|
| 455 | /** Sets the surface properties to be used for future rendering.
|
---|
| 456 |
|
---|
| 457 | This method sets the the properties of the surfaces of objects
|
---|
| 458 | to be rendered after it. In this context these surface properties
|
---|
| 459 | are the amount of each type of light the object reflects (determining
|
---|
| 460 | it's colour under different types of light), whether it emits light
|
---|
| 461 | itself, and how shiny it is. Textures are not dealt with here,
|
---|
| 462 | see the _setTetxure method for details.
|
---|
| 463 | This method is used by _setMaterial so does not need to be called
|
---|
| 464 | direct if that method is being used.
|
---|
| 465 |
|
---|
| 466 | @param ambient The amount of ambient (sourceless and directionless)
|
---|
| 467 | light an object reflects. Affected by the colour/amount of ambient light in the scene.
|
---|
| 468 | @param diffuse The amount of light from directed sources that is
|
---|
| 469 | reflected (affected by colour/amount of point, directed and spot light sources)
|
---|
| 470 | @param specular The amount of specular light reflected. This is also
|
---|
| 471 | affected by directed light sources but represents the colour at the
|
---|
| 472 | highlights of the object.
|
---|
| 473 | @param emissive The colour of light emitted from the object. Note that
|
---|
| 474 | this will make an object seem brighter and not dependent on lights in
|
---|
| 475 | the scene, but it will not act as a light, so will not illuminate other
|
---|
| 476 | objects. Use a light attached to the same SceneNode as the object for this purpose.
|
---|
| 477 | @param shininess A value which only has an effect on specular highlights (so
|
---|
| 478 | specular must be non-black). The higher this value, the smaller and crisper the
|
---|
| 479 | specular highlights will be, imitating a more highly polished surface.
|
---|
| 480 | This value is not constrained to 0.0-1.0, in fact it is likely to
|
---|
| 481 | be more (10.0 gives a modest sheen to an object).
|
---|
| 482 | @param tracking A bit field that describes which of the ambient, diffuse, specular
|
---|
| 483 | and emissive colours follow the vertex colour of the primitive. When a bit in this field is set
|
---|
| 484 | its ColourValue is ignored. This is a combination of TVC_AMBIENT, TVC_DIFFUSE, TVC_SPECULAR(note that the shininess value is still
|
---|
| 485 | taken from shininess) and TVC_EMISSIVE. TVC_NONE means that there will be no material property
|
---|
| 486 | tracking the vertex colours.
|
---|
| 487 | */
|
---|
| 488 | virtual void _setSurfaceParams(const ColourValue &ambient,
|
---|
| 489 | const ColourValue &diffuse, const ColourValue &specular,
|
---|
| 490 | const ColourValue &emissive, Real shininess,
|
---|
| 491 | TrackVertexColourType tracking = TVC_NONE) = 0;
|
---|
| 492 | /**
|
---|
| 493 | Sets the status of a single texture stage.
|
---|
| 494 |
|
---|
| 495 | Sets the details of a texture stage, to be used for all primitives
|
---|
| 496 | rendered afterwards. User processes would
|
---|
| 497 | not normally call this direct unless rendering
|
---|
| 498 | primitives themselves - the SubEntity class
|
---|
| 499 | is designed to manage materials for objects.
|
---|
| 500 | Note that this method is called by _setMaterial.
|
---|
| 501 |
|
---|
| 502 | @param unit The index of the texture unit to modify. Multitexturing hardware
|
---|
| 503 | can support multiple units (see RenderSystemCapabilites::numTextureUnits)
|
---|
| 504 | @param enabled Boolean to turn the unit on/off
|
---|
| 505 | @param texname The name of the texture to use - this should have
|
---|
| 506 | already been loaded with TextureManager::load.
|
---|
| 507 | */
|
---|
| 508 | virtual void _setTexture(size_t unit, bool enabled, const String &texname) = 0;
|
---|
| 509 |
|
---|
| 510 | /**
|
---|
| 511 | Sets the texture coordinate set to use for a texture unit.
|
---|
| 512 |
|
---|
| 513 | Meant for use internally - not generally used directly by apps - the Material and TextureUnitState
|
---|
| 514 | classes let you manage textures far more easily.
|
---|
| 515 |
|
---|
| 516 | @param unit Texture unit as above
|
---|
| 517 | @param index The index of the texture coordinate set to use.
|
---|
| 518 | */
|
---|
| 519 | virtual void _setTextureCoordSet(size_t unit, size_t index) = 0;
|
---|
| 520 |
|
---|
| 521 | /**
|
---|
| 522 | Sets a method for automatically calculating texture coordinates for a stage.
|
---|
| 523 | Should not be used by apps - for use by Ogre only.
|
---|
| 524 | @param unit Texture unit as above
|
---|
| 525 | @param m Calculation method to use
|
---|
| 526 | @param frustum Optional Frustum param, only used for projective effects
|
---|
| 527 | */
|
---|
| 528 | virtual void _setTextureCoordCalculation(size_t unit, TexCoordCalcMethod m,
|
---|
| 529 | const Frustum* frustum = 0) = 0;
|
---|
| 530 |
|
---|
| 531 | /** Sets the texture blend modes from a TextureUnitState record.
|
---|
| 532 | Meant for use internally only - apps should use the Material
|
---|
| 533 | and TextureUnitState classes.
|
---|
| 534 | @param unit Texture unit as above
|
---|
| 535 | @param bm Details of the blending mode
|
---|
| 536 | */
|
---|
| 537 | virtual void _setTextureBlendMode(size_t unit, const LayerBlendModeEx& bm) = 0;
|
---|
| 538 |
|
---|
| 539 | /** Sets the filtering options for a given texture unit.
|
---|
| 540 | @param unit The texture unit to set the filtering options for
|
---|
| 541 | @param minFilter The filter used when a texture is reduced in size
|
---|
| 542 | @param magFilter The filter used when a texture is magnified
|
---|
| 543 | @param mipFilter The filter used between mipmap levels, FO_NONE disables mipmapping
|
---|
| 544 | */
|
---|
| 545 | virtual void _setTextureUnitFiltering(size_t unit, FilterOptions minFilter,
|
---|
| 546 | FilterOptions magFilter, FilterOptions mipFilter);
|
---|
| 547 |
|
---|
| 548 | /** Sets a single filter for a given texture unit.
|
---|
| 549 | @param unit The texture unit to set the filtering options for
|
---|
| 550 | @param ftype The filter type
|
---|
| 551 | @param filter The filter to be used
|
---|
| 552 | */
|
---|
| 553 | virtual void _setTextureUnitFiltering(size_t unit, FilterType ftype, FilterOptions filter) = 0;
|
---|
| 554 |
|
---|
| 555 | /** Sets the maximal anisotropy for the specified texture unit.*/
|
---|
| 556 | virtual void _setTextureLayerAnisotropy(size_t unit, unsigned int maxAnisotropy) = 0;
|
---|
| 557 |
|
---|
| 558 | /** Sets the texture addressing mode for a texture unit.*/
|
---|
| 559 | virtual void _setTextureAddressingMode(size_t unit, TextureUnitState::TextureAddressingMode tam) = 0;
|
---|
| 560 |
|
---|
| 561 | /** Sets the texture coordinate transformation matrix for a texture unit.
|
---|
| 562 | @param unit Texture unit to affect
|
---|
| 563 | @param xform The 4x4 matrix
|
---|
| 564 | */
|
---|
| 565 | virtual void _setTextureMatrix(size_t unit, const Matrix4& xform) = 0;
|
---|
| 566 |
|
---|
| 567 | /** Sets the global blending factors for combining subsequent renders with the existing frame contents.
|
---|
| 568 | The result of the blending operation is:</p>
|
---|
| 569 | <p align="center">final = (texture * sourceFactor) + (pixel * destFactor)</p>
|
---|
| 570 | Each of the factors is specified as one of a number of options, as specified in the SceneBlendFactor
|
---|
| 571 | enumerated type.
|
---|
| 572 | @param sourceFactor The source factor in the above calculation, i.e. multiplied by the texture colour components.
|
---|
| 573 | @param destFactor The destination factor in the above calculation, i.e. multiplied by the pixel colour components.
|
---|
| 574 | */
|
---|
| 575 | virtual void _setSceneBlending(SceneBlendFactor sourceFactor, SceneBlendFactor destFactor) = 0;
|
---|
| 576 |
|
---|
| 577 | /** Sets the global alpha rejection approach for future renders.
|
---|
| 578 | By default images are rendered regardless of texture alpha. This method lets you change that.
|
---|
| 579 | @param func The comparison function which must pass for a pixel to be written.
|
---|
| 580 | @param val The value to compare each pixels alpha value to (0-255)
|
---|
| 581 | */
|
---|
| 582 | virtual void _setAlphaRejectSettings(CompareFunction func, unsigned char value) = 0;
|
---|
| 583 | /**
|
---|
| 584 | * Signifies the beginning of a frame, ie the start of rendering on a single viewport. Will occur
|
---|
| 585 | * several times per complete frame if multiple viewports exist.
|
---|
| 586 | */
|
---|
| 587 | virtual void _beginFrame(void) = 0;
|
---|
| 588 |
|
---|
| 589 |
|
---|
| 590 | /**
|
---|
| 591 | * Ends rendering of a frame to the current viewport.
|
---|
| 592 | */
|
---|
| 593 | virtual void _endFrame(void) = 0;
|
---|
| 594 | /**
|
---|
| 595 | Sets the provided viewport as the active one for future
|
---|
| 596 | rendering operations. This viewport is aware of it's own
|
---|
| 597 | camera and render target. Must be implemented by subclass.
|
---|
| 598 |
|
---|
| 599 | @param target Pointer to the appropriate viewport.
|
---|
| 600 | */
|
---|
| 601 | virtual void _setViewport(Viewport *vp) = 0;
|
---|
| 602 | /** Get the current active viewport for rendering. */
|
---|
| 603 | virtual Viewport* _getViewport(void);
|
---|
| 604 |
|
---|
| 605 | /** Sets the culling mode for the render system based on the 'vertex winding'.
|
---|
| 606 | A typical way for the rendering engine to cull triangles is based on the
|
---|
| 607 | 'vertex winding' of triangles. Vertex winding refers to the direction in
|
---|
| 608 | which the vertices are passed or indexed to in the rendering operation as viewed
|
---|
| 609 | from the camera, and will wither be clockwise or anticlockwise (that's 'counterclockwise' for
|
---|
| 610 | you Americans out there ;) The default is CULL_CLOCKWISE i.e. that only triangles whose vertices
|
---|
| 611 | are passed/indexed in anticlockwise order are rendered - this is a common approach and is used in 3D studio models
|
---|
| 612 | for example. You can alter this culling mode if you wish but it is not advised unless you know what you are doing.
|
---|
| 613 | You may wish to use the CULL_NONE option for mesh data that you cull yourself where the vertex
|
---|
| 614 | winding is uncertain.
|
---|
| 615 | */
|
---|
| 616 | virtual void _setCullingMode(CullingMode mode) = 0;
|
---|
| 617 |
|
---|
| 618 | virtual CullingMode _getCullingMode(void) const;
|
---|
| 619 |
|
---|
| 620 | /** Sets the mode of operation for depth buffer tests from this point onwards.
|
---|
| 621 | Sometimes you may wish to alter the behaviour of the depth buffer to achieve
|
---|
| 622 | special effects. Because it's unlikely that you'll set these options for an entire frame,
|
---|
| 623 | but rather use them to tweak settings between rendering objects, this is an internal
|
---|
| 624 | method (indicated by the '_' prefix) which will be used by a SceneManager implementation
|
---|
| 625 | rather than directly from the client application.
|
---|
| 626 | If this method is never called the settings are automatically the same as the default parameters.
|
---|
| 627 | @param depthTest If true, the depth buffer is tested for each pixel and the frame buffer is only updated
|
---|
| 628 | if the depth function test succeeds. If false, no test is performed and pixels are always written.
|
---|
| 629 | @param depthWrite If true, the depth buffer is updated with the depth of the new pixel if the depth test succeeds.
|
---|
| 630 | If false, the depth buffer is left unchanged even if a new pixel is written.
|
---|
| 631 | @param depthFunction Sets the function required for the depth test.
|
---|
| 632 | */
|
---|
| 633 | virtual void _setDepthBufferParams(bool depthTest = true, bool depthWrite = true, CompareFunction depthFunction = CMPF_LESS_EQUAL) = 0;
|
---|
| 634 |
|
---|
| 635 | /** Sets whether or not the depth buffer check is performed before a pixel write.
|
---|
| 636 | @param enabled If true, the depth buffer is tested for each pixel and the frame buffer is only updated
|
---|
| 637 | if the depth function test succeeds. If false, no test is performed and pixels are always written.
|
---|
| 638 | */
|
---|
| 639 | virtual void _setDepthBufferCheckEnabled(bool enabled = true) = 0;
|
---|
| 640 | /** Sets whether or not the depth buffer is updated after a pixel write.
|
---|
| 641 | @param enabled If true, the depth buffer is updated with the depth of the new pixel if the depth test succeeds.
|
---|
| 642 | If false, the depth buffer is left unchanged even if a new pixel is written.
|
---|
| 643 | */
|
---|
| 644 | virtual void _setDepthBufferWriteEnabled(bool enabled = true) = 0;
|
---|
| 645 | /** Sets the comparison function for the depth buffer check.
|
---|
| 646 | Advanced use only - allows you to choose the function applied to compare the depth values of
|
---|
| 647 | new and existing pixels in the depth buffer. Only an issue if the deoth buffer check is enabled
|
---|
| 648 | (see _setDepthBufferCheckEnabled)
|
---|
| 649 | @param func The comparison between the new depth and the existing depth which must return true
|
---|
| 650 | for the new pixel to be written.
|
---|
| 651 | */
|
---|
| 652 | virtual void _setDepthBufferFunction(CompareFunction func = CMPF_LESS_EQUAL) = 0;
|
---|
| 653 | /** Sets whether or not colour buffer writing is enabled, and for which channels.
|
---|
| 654 | @remarks
|
---|
| 655 | For some advanced effects, you may wish to turn off the writing of certain colour
|
---|
| 656 | channels, or even all of the colour channels so that only the depth buffer is updated
|
---|
| 657 | in a rendering pass. However, the chances are that you really want to use this option
|
---|
| 658 | through the Material class.
|
---|
| 659 | @param red, green, blue, alpha Whether writing is enabled for each of the 4 colour channels. */
|
---|
| 660 | virtual void _setColourBufferWriteEnabled(bool red, bool green, bool blue, bool alpha) = 0;
|
---|
| 661 | /** Sets the depth bias, NB you should use the Material version of this.
|
---|
| 662 | @remarks
|
---|
| 663 | When polygons are coplanar, you can get problems with 'depth fighting' where
|
---|
| 664 | the pixels from the two polys compete for the same screen pixel. This is particularly
|
---|
| 665 | a problem for decals (polys attached to another surface to represent details such as
|
---|
| 666 | bulletholes etc.).
|
---|
| 667 | @par
|
---|
| 668 | A way to combat this problem is to use a depth bias to adjust the depth buffer value
|
---|
| 669 | used for the decal such that it is slightly higher than the true value, ensuring that
|
---|
| 670 | the decal appears on top.
|
---|
| 671 | @param bias The bias value, should be between 0 and 16.
|
---|
| 672 | */
|
---|
| 673 | virtual void _setDepthBias(ushort bias) = 0;
|
---|
| 674 | /** Sets the fogging mode for future geometry.
|
---|
| 675 | @param mode Set up the mode of fog as described in the FogMode enum, or set to FOG_NONE to turn off.
|
---|
| 676 | @param colour The colour of the fog. Either set this to the same as your viewport background colour,
|
---|
| 677 | or to blend in with a skydome or skybox.
|
---|
| 678 | @param expDensity The density of the fog in FOG_EXP or FOG_EXP2 mode, as a value between 0 and 1. The default is 1. i.e. completely opaque, lower values can mean
|
---|
| 679 | that fog never completely obscures the scene.
|
---|
| 680 | @param linearStart Distance at which linear fog starts to encroach. The distance must be passed
|
---|
| 681 | as a parametric value between 0 and 1, with 0 being the near clipping plane, and 1 being the far clipping plane. Only applicable if mode is FOG_LINEAR.
|
---|
| 682 | @param linearEnd Distance at which linear fog becomes completely opaque.The distance must be passed
|
---|
| 683 | as a parametric value between 0 and 1, with 0 being the near clipping plane, and 1 being the far clipping plane. Only applicable if mode is FOG_LINEAR.
|
---|
| 684 | */
|
---|
| 685 | virtual void _setFog(FogMode mode = FOG_NONE, const ColourValue& colour = ColourValue::White, Real expDensity = 1.0, Real linearStart = 0.0, Real linearEnd = 1.0) = 0;
|
---|
| 686 |
|
---|
| 687 |
|
---|
| 688 | /** The RenderSystem will keep a count of tris rendered, this resets the count. */
|
---|
| 689 | virtual void _beginGeometryCount(void);
|
---|
| 690 | /** Reports the number of tris rendered since the last _beginGeometryCount call. */
|
---|
| 691 | virtual unsigned int _getFaceCount(void) const;
|
---|
| 692 | /** Reports the number of vertices passed to the renderer since the last _beginGeometryCount call. */
|
---|
| 693 | virtual unsigned int _getVertexCount(void) const;
|
---|
| 694 |
|
---|
| 695 | /** Generates a packed data version of the passed in ColourValue suitable for
|
---|
| 696 | use as with this RenderSystem.
|
---|
| 697 | @remarks
|
---|
| 698 | Since different render systems have different colour data formats (eg
|
---|
| 699 | RGBA for GL, ARGB for D3D) this method allows you to use 1 method for all.
|
---|
| 700 | @param colour The colour to convert
|
---|
| 701 | @param pDest Pointer to location to put the result.
|
---|
| 702 | */
|
---|
| 703 | virtual void convertColourValue(const ColourValue& colour, uint32* pDest) = 0;
|
---|
| 704 |
|
---|
| 705 | /** Builds a perspective projection matrix suitable for this render system.
|
---|
| 706 | @remarks
|
---|
| 707 | Because different APIs have different requirements (some incompatible) for the
|
---|
| 708 | projection matrix, this method allows each to implement their own correctly and pass
|
---|
| 709 | back a generic OGRE matrix for storage in the engine.
|
---|
| 710 | */
|
---|
| 711 | virtual void _makeProjectionMatrix(const Radian& fovy, Real aspect, Real nearPlane, Real farPlane,
|
---|
| 712 | Matrix4& dest, bool forGpuProgram = false) = 0;
|
---|
| 713 |
|
---|
| 714 | /** Builds a perspective projection matrix for the case when frustum is
|
---|
| 715 | not centered around camera.
|
---|
| 716 | @remarks
|
---|
| 717 | Viewport coordinates are in camera coordinate frame, i.e. camera is
|
---|
| 718 | at the origin.
|
---|
| 719 | */
|
---|
| 720 | virtual void _makeProjectionMatrix(Real left, Real right, Real bottom, Real top,
|
---|
| 721 | Real nearPlane, Real farPlane, Matrix4& dest, bool forGpuProgram = false) = 0;
|
---|
| 722 | /** Builds an orthographic projection matrix suitable for this render system.
|
---|
| 723 | @remarks
|
---|
| 724 | Because different APIs have different requirements (some incompatible) for the
|
---|
| 725 | projection matrix, this method allows each to implement their own correctly and pass
|
---|
| 726 | back a generic OGRE matrix for storage in the engine.
|
---|
| 727 | */
|
---|
| 728 | virtual void _makeOrthoMatrix(const Radian& fovy, Real aspect, Real nearPlane, Real farPlane,
|
---|
| 729 | Matrix4& dest, bool forGpuProgram = false) = 0;
|
---|
| 730 |
|
---|
| 731 | /** Update a perspective projection matrix to use 'oblique depth projection'.
|
---|
| 732 | @remarks
|
---|
| 733 | This method can be used to change the nature of a perspective
|
---|
| 734 | transform in order to make the near plane not perpendicular to the
|
---|
| 735 | camera view direction, but to be at some different orientation.
|
---|
| 736 | This can be useful for performing arbitrary clipping (e.g. to a
|
---|
| 737 | reflection plane) which could otherwise only be done using user
|
---|
| 738 | clip planes, which are more expensive, and not necessarily supported
|
---|
| 739 | on all cards.
|
---|
| 740 | @param matrix The existing projection matrix. Note that this must be a
|
---|
| 741 | perspective transform (not orthographic), and must not have already
|
---|
| 742 | been altered by this method. The matrix will be altered in-place.
|
---|
| 743 | @param plane The plane which is to be used as the clipping plane. This
|
---|
| 744 | plane must be in CAMERA (view) space.
|
---|
| 745 | @param forGpuProgram Is this for use with a Gpu program or fixed-function
|
---|
| 746 | */
|
---|
| 747 | virtual void _applyObliqueDepthProjection(Matrix4& matrix, const Plane& plane,
|
---|
| 748 | bool forGpuProgram) = 0;
|
---|
| 749 |
|
---|
| 750 | /** Sets how to rasterise triangles, as points, wireframe or solid polys. */
|
---|
| 751 | virtual void _setRasterisationMode(SceneDetailLevel level) = 0;
|
---|
| 752 |
|
---|
| 753 | /** Turns stencil buffer checking on or off.
|
---|
| 754 | @remarks
|
---|
| 755 | Stencilling (masking off areas of the rendering target based on the stencil
|
---|
| 756 | buffer) canbe turned on or off using this method. By default, stencilling is
|
---|
| 757 | disabled.
|
---|
| 758 | */
|
---|
| 759 | virtual void setStencilCheckEnabled(bool enabled) = 0;
|
---|
| 760 | /** Determines if this system supports hardware accelerated stencil buffer.
|
---|
| 761 | @remarks
|
---|
| 762 | Note that the lack of this function doesn't mean you can't do stencilling, but
|
---|
| 763 | the stencilling operations will be provided in software, which will NOT be
|
---|
| 764 | fast.
|
---|
| 765 | @par
|
---|
| 766 | Generally hardware stencils are only supported in 32-bit colour modes, because
|
---|
| 767 | the stencil buffer shares the memory of the z-buffer, and in most cards the
|
---|
| 768 | z-buffer has to be the same depth as the colour buffer. This means that in 32-bit
|
---|
| 769 | mode, 24 bits of the z-buffer are depth and 8 bits are stencil. In 16-bit mode there
|
---|
| 770 | is no room for a stencil (although some cards support a 15:1 depth:stencil option,
|
---|
| 771 | this isn't useful for very much) so 8 bits of stencil are provided in software.
|
---|
| 772 | This can mean that if you use stencilling, your applications may be faster in
|
---|
| 773 | 32-but colour than in 16-bit, which may seem odd to some people.
|
---|
| 774 | */
|
---|
| 775 | /*virtual bool hasHardwareStencil(void) = 0;*/
|
---|
| 776 |
|
---|
| 777 | /** This method allows you to set all the stencil buffer parameters in one call.
|
---|
| 778 | @remarks
|
---|
| 779 | The stencil buffer is used to mask out pixels in the render target, allowing
|
---|
| 780 | you to do effects like mirrors, cut-outs, stencil shadows and more. Each of
|
---|
| 781 | your batches of rendering is likely to ignore the stencil buffer,
|
---|
| 782 | update it with new values, or apply it to mask the output of the render.
|
---|
| 783 | The stencil test is:<PRE>
|
---|
| 784 | (Reference Value & Mask) CompareFunction (Stencil Buffer Value & Mask)</PRE>
|
---|
| 785 | The result of this will cause one of 3 actions depending on whether the test fails,
|
---|
| 786 | succeeds but with the depth buffer check still failing, or succeeds with the
|
---|
| 787 | depth buffer check passing too.
|
---|
| 788 | @par
|
---|
| 789 | Unlike other render states, stencilling is left for the application to turn
|
---|
| 790 | on and off when it requires. This is because you are likely to want to change
|
---|
| 791 | parameters between batches of arbitrary objects and control the ordering yourself.
|
---|
| 792 | In order to batch things this way, you'll want to use OGRE's separate render queue
|
---|
| 793 | groups (see RenderQueue) and register a RenderQueueListener to get notifications
|
---|
| 794 | between batches.
|
---|
| 795 | @par
|
---|
| 796 | There are individual state change methods for each of the parameters set using
|
---|
| 797 | this method.
|
---|
| 798 | Note that the default values in this method represent the defaults at system
|
---|
| 799 | start up too.
|
---|
| 800 | @param func The comparison function applied.
|
---|
| 801 | @param refValue The reference value used in the comparison
|
---|
| 802 | @param mask The bitmask applied to both the stencil value and the reference value
|
---|
| 803 | before comparison
|
---|
| 804 | @param stencilFailOp The action to perform when the stencil check fails
|
---|
| 805 | @param depthFailOp The action to perform when the stencil check passes, but the
|
---|
| 806 | depth buffer check still fails
|
---|
| 807 | @param passOp The action to take when both the stencil and depth check pass.
|
---|
| 808 | @param twoSidedOperation If set to true, then if you render both back and front faces
|
---|
| 809 | (you'll have to turn off culling) then these parameters will apply for front faces,
|
---|
| 810 | and the inverse of them will happen for back faces (keep remains the same).
|
---|
| 811 | */
|
---|
| 812 | virtual void setStencilBufferParams(CompareFunction func = CMPF_ALWAYS_PASS,
|
---|
| 813 | uint32 refValue = 0, uint32 mask = 0xFFFFFFFF,
|
---|
| 814 | StencilOperation stencilFailOp = SOP_KEEP,
|
---|
| 815 | StencilOperation depthFailOp = SOP_KEEP,
|
---|
| 816 | StencilOperation passOp = SOP_KEEP,
|
---|
| 817 | bool twoSidedOperation = false) = 0;
|
---|
| 818 |
|
---|
| 819 |
|
---|
| 820 |
|
---|
| 821 | /** Sets the current vertex declaration, ie the source of vertex data. */
|
---|
| 822 | virtual void setVertexDeclaration(VertexDeclaration* decl) = 0;
|
---|
| 823 | /** Sets the current vertex buffer binding state. */
|
---|
| 824 | virtual void setVertexBufferBinding(VertexBufferBinding* binding) = 0;
|
---|
| 825 |
|
---|
| 826 | /** Sets whether or not normals are to be automatically normalised.
|
---|
| 827 | @remarks
|
---|
| 828 | This is useful when, for example, you are scaling SceneNodes such that
|
---|
| 829 | normals may not be unit-length anymore. Note though that this has an
|
---|
| 830 | overhead so should not be turn on unless you really need it.
|
---|
| 831 | @par
|
---|
| 832 | You should not normally call this direct unless you are rendering
|
---|
| 833 | world geometry; set it on the Renderable because otherwise it will be
|
---|
| 834 | overridden by material settings.
|
---|
| 835 | */
|
---|
| 836 | virtual void setNormaliseNormals(bool normalise) = 0;
|
---|
| 837 |
|
---|
| 838 | /**
|
---|
| 839 | Render something to the active viewport.
|
---|
| 840 |
|
---|
| 841 | Low-level rendering interface to perform rendering
|
---|
| 842 | operations. Unlikely to be used directly by client
|
---|
| 843 | applications, since the SceneManager and various support
|
---|
| 844 | classes will be responsible for calling this method.
|
---|
| 845 | Can only be called between _beginScene and _endScene
|
---|
| 846 |
|
---|
| 847 | @param op A rendering operation instance, which contains
|
---|
| 848 | details of the operation to be performed.
|
---|
| 849 | */
|
---|
| 850 | virtual void _render(const RenderOperation& op);
|
---|
| 851 |
|
---|
| 852 | /** Gets the capabilities of the render system. */
|
---|
| 853 | const RenderSystemCapabilities* getCapabilities(void) const { return mCapabilities; }
|
---|
| 854 |
|
---|
| 855 | /** Binds a given GpuProgram (but not the parameters).
|
---|
| 856 | @remarks Only one GpuProgram of each type can be bound at once, binding another
|
---|
| 857 | one will simply replace the exsiting one.
|
---|
| 858 | */
|
---|
| 859 | virtual void bindGpuProgram(GpuProgram* prg) = 0;
|
---|
| 860 |
|
---|
| 861 | /** Bind Gpu program parameters. */
|
---|
| 862 | virtual void bindGpuProgramParameters(GpuProgramType gptype, GpuProgramParametersSharedPtr params) = 0;
|
---|
| 863 | /** Unbinds GpuPrograms of a given GpuProgramType.
|
---|
| 864 | @remarks
|
---|
| 865 | This returns the pipeline to fixed-function processing for this type.
|
---|
| 866 | */
|
---|
| 867 | virtual void unbindGpuProgram(GpuProgramType gptype) = 0;
|
---|
| 868 |
|
---|
| 869 | /** sets the clipping region.
|
---|
| 870 | */
|
---|
| 871 | virtual void setClipPlanes(const PlaneList& clipPlanes) = 0;
|
---|
| 872 |
|
---|
| 873 | /** Utility method for initialising all render targets attached to this rendering system. */
|
---|
| 874 | virtual void _initRenderTargets(void);
|
---|
| 875 |
|
---|
| 876 | /** Utility method to notify all render targets that a camera has been removed,
|
---|
| 877 | incase they were referring to it as their viewer.
|
---|
| 878 | */
|
---|
| 879 | virtual void _notifyCameraRemoved(const Camera* cam);
|
---|
| 880 |
|
---|
| 881 | /** Internal method for updating all render targets attached to this rendering system. */
|
---|
| 882 | virtual void _updateAllRenderTargets(void);
|
---|
| 883 |
|
---|
| 884 | /** Set a clipping plane. */
|
---|
| 885 | virtual void setClipPlane (ushort index, const Plane &p);
|
---|
| 886 | /** Set a clipping plane. */
|
---|
| 887 | virtual void setClipPlane (ushort index, Real A, Real B, Real C, Real D) = 0;
|
---|
| 888 | /** Enable the clipping plane. */
|
---|
| 889 | virtual void enableClipPlane (ushort index, bool enable) = 0;
|
---|
| 890 |
|
---|
| 891 | /** Sets whether or not vertex windings set should be inverted; this can be important
|
---|
| 892 | for rendering reflections. */
|
---|
| 893 | virtual void setInvertVertexWinding(bool invert);
|
---|
| 894 | /** Sets the 'scissor region' ie the region of the target in which rendering can take place.
|
---|
| 895 | @remarks
|
---|
| 896 | This method allows you to 'mask off' rendering in all but a given rectangular area
|
---|
| 897 | as identified by the parameters to this method.
|
---|
| 898 | @note
|
---|
| 899 | Not all systems support this method. Check the RenderSystemCapabilities for the
|
---|
| 900 | RSC_SCISSOR_TEST capability to see if it is supported.
|
---|
| 901 | @param enabled True to enable the scissor test, false to disable it.
|
---|
| 902 | @param left, top, right, bottom The location of the corners of the rectangle, expressed in
|
---|
| 903 | <i>pixels</i>.
|
---|
| 904 | */
|
---|
| 905 | virtual void setScissorTest(bool enabled, size_t left = 0, size_t top = 0,
|
---|
| 906 | size_t right = 800, size_t bottom = 600) = 0;
|
---|
| 907 |
|
---|
| 908 | /** Clears one or more frame buffers on the active render target.
|
---|
| 909 | @param buffers Combination of one or more elements of FrameBufferType
|
---|
| 910 | denoting which buffers are to be cleared
|
---|
| 911 | @param colour The colour to clear the colour buffer with, if enabled
|
---|
| 912 | @param depth The value to initialise the depth buffer with, if enabled
|
---|
| 913 | @param stencil The value to initialise the stencil buffer with, if enabled.
|
---|
| 914 | */
|
---|
| 915 | virtual void clearFrameBuffer(unsigned int buffers,
|
---|
| 916 | const ColourValue& colour = ColourValue::Black,
|
---|
| 917 | Real depth = 1.0f, unsigned short stencil = 0) = 0;
|
---|
| 918 | /** Returns the horizontal texel offset value required for mapping
|
---|
| 919 | texel origins to pixel origins in this rendersystem.
|
---|
| 920 | @remarks
|
---|
| 921 | Since rendersystems sometimes disagree on the origin of a texel,
|
---|
| 922 | mapping from texels to pixels can sometimes be problematic to
|
---|
| 923 | implement generically. This method allows you to retrieve the offset
|
---|
| 924 | required to map the origin of a texel to the origin of a pixel in
|
---|
| 925 | the horizontal direction.
|
---|
| 926 | */
|
---|
| 927 | virtual Real getHorizontalTexelOffset(void) = 0;
|
---|
| 928 | /** Returns the vertical texel offset value required for mapping
|
---|
| 929 | texel origins to pixel origins in this rendersystem.
|
---|
| 930 | @remarks
|
---|
| 931 | Since rendersystems sometimes disagree on the origin of a texel,
|
---|
| 932 | mapping from texels to pixels can sometimes be problematic to
|
---|
| 933 | implement generically. This method allows you to retrieve the offset
|
---|
| 934 | required to map the origin of a texel to the origin of a pixel in
|
---|
| 935 | the vertical direction.
|
---|
| 936 | */
|
---|
| 937 | virtual Real getVerticalTexelOffset(void) = 0;
|
---|
| 938 |
|
---|
| 939 | /** Gets the minimum (closest) depth value to be used when rendering
|
---|
| 940 | using identity transforms.
|
---|
| 941 | @remarks
|
---|
| 942 | When using identity transforms you can manually set the depth
|
---|
| 943 | of a vertex; however the input values required differ per
|
---|
| 944 | rendersystem. This method lets you retrieve the correct value.
|
---|
| 945 | @see Renderable::useIdentityView, Renderable::useIdentityProjection
|
---|
| 946 | */
|
---|
| 947 | virtual Real getMinimumDepthInputValue(void) = 0;
|
---|
| 948 | /** Gets the maximum (farthest) depth value to be used when rendering
|
---|
| 949 | using identity transforms.
|
---|
| 950 | @remarks
|
---|
| 951 | When using identity transforms you can manually set the depth
|
---|
| 952 | of a vertex; however the input values required differ per
|
---|
| 953 | rendersystem. This method lets you retrieve the correct value.
|
---|
| 954 | @see Renderable::useIdentityView, Renderable::useIdentityProjection
|
---|
| 955 | */
|
---|
| 956 | virtual Real getMaximumDepthInputValue(void) = 0;
|
---|
| 957 |
|
---|
| 958 | /** Defines a listener on the custom events that this render system
|
---|
| 959 | can raise.
|
---|
| 960 | @see RenderSystem::addListener
|
---|
| 961 | */
|
---|
| 962 | class _OgreExport Listener
|
---|
| 963 | {
|
---|
| 964 | public:
|
---|
| 965 | Listener() {}
|
---|
| 966 | virtual ~Listener() {}
|
---|
| 967 |
|
---|
| 968 | /** A rendersystem-specific event occurred.
|
---|
| 969 | @param eventName The name of the event which has occurred
|
---|
| 970 | @param parameters A list of parameters that may belong to this event,
|
---|
| 971 | may be null if there are no parameters
|
---|
| 972 | */
|
---|
| 973 | virtual void eventOccurred(const String& eventName,
|
---|
| 974 | const NameValuePairList* parameters = 0) = 0;
|
---|
| 975 | };
|
---|
| 976 | /** Adds a listener to the custom events that this render system can raise.
|
---|
| 977 | @remarks
|
---|
| 978 | Some render systems have quite specific, internally generated events
|
---|
| 979 | that the application may wish to be notified of. Many applications
|
---|
| 980 | don't have to worry about these events, and can just trust OGRE to
|
---|
| 981 | handle them, but if you want to know, you can add a listener here.
|
---|
| 982 | @par
|
---|
| 983 | Events are raised very generically by string name. Perhaps the most
|
---|
| 984 | common example of a render system specific event is the loss and
|
---|
| 985 | restoration of a device in DirectX; which OGRE deals with, but you
|
---|
| 986 | may wish to know when it happens.
|
---|
| 987 | @see RenderSystem::getRenderSystemEvents
|
---|
| 988 | */
|
---|
| 989 | virtual void addListener(Listener* l);
|
---|
| 990 | /** Remove a listener to the custom events that this render system can raise.
|
---|
| 991 | */
|
---|
| 992 | virtual void removeListener(Listener* l);
|
---|
| 993 |
|
---|
| 994 | /** Gets a list of the rendersystem specific events that this rendersystem
|
---|
| 995 | can raise.
|
---|
| 996 | @see RenderSystem::addListener
|
---|
| 997 | */
|
---|
| 998 | virtual const StringVector& getRenderSystemEvents(void) const { return mEventNames; }
|
---|
| 999 | protected:
|
---|
| 1000 |
|
---|
| 1001 |
|
---|
| 1002 | /** The render targets. */
|
---|
| 1003 | RenderTargetMap mRenderTargets;
|
---|
| 1004 | /** The render targets, ordered by priority. */
|
---|
| 1005 | RenderTargetPriorityMap mPrioritisedRenderTargets;
|
---|
| 1006 | /** The Active render target. */
|
---|
| 1007 | RenderTarget * mActiveRenderTarget;
|
---|
| 1008 |
|
---|
| 1009 | // Texture manager
|
---|
| 1010 | // A concrete class of this will be created and
|
---|
| 1011 | // made available under the TextureManager singleton,
|
---|
| 1012 | // managed by the RenderSystem
|
---|
| 1013 | TextureManager* mTextureManager;
|
---|
| 1014 |
|
---|
| 1015 | /// Used to store the capabilities of the graphics card
|
---|
| 1016 | RenderSystemCapabilities* mCapabilities;
|
---|
| 1017 |
|
---|
| 1018 | // Active viewport (dest for future rendering operations)
|
---|
| 1019 | Viewport* mActiveViewport;
|
---|
| 1020 |
|
---|
| 1021 | CullingMode mCullingMode;
|
---|
| 1022 |
|
---|
| 1023 | bool mVSync;
|
---|
| 1024 | bool mWBuffer;
|
---|
| 1025 |
|
---|
| 1026 | size_t mFaceCount;
|
---|
| 1027 | size_t mVertexCount;
|
---|
| 1028 |
|
---|
| 1029 | /// Saved set of world matrices
|
---|
| 1030 | Matrix4 mWorldMatrices[256];
|
---|
| 1031 |
|
---|
| 1032 | /// Saved manual colour blends
|
---|
| 1033 | ColourValue mManualBlendColours[OGRE_MAX_TEXTURE_LAYERS][2];
|
---|
| 1034 |
|
---|
| 1035 | bool mInvertVertexWinding;
|
---|
| 1036 |
|
---|
| 1037 | /// List of names of events this rendersystem may raise
|
---|
| 1038 | StringVector mEventNames;
|
---|
| 1039 |
|
---|
| 1040 | /// Internal method for firing a rendersystem event
|
---|
| 1041 | virtual void fireEvent(const String& name, const NameValuePairList* params = 0);
|
---|
| 1042 |
|
---|
| 1043 | typedef std::list<Listener*> ListenerList;
|
---|
| 1044 | ListenerList mEventListeners;
|
---|
| 1045 |
|
---|
| 1046 | };
|
---|
| 1047 | }
|
---|
| 1048 |
|
---|
| 1049 | #endif
|
---|