ShoggothNotes         ChangeLog and porting notes for OGRE 1.6.0 "Shoggoth"

Welcome to the ChangeLog and porting notes for OGRE 1.6.0 "Shoggoth"

H.P. Lovecraft wrote:
"It was a terrible, indescribable thing vaster than any subway train – a shapeless congerie of protoplasmic bubbles, faintly self-luminous, and with myriads of temporary eyes forming and un-forming as pustules of greenish light all over the tunnel-filling front that bore down upon us, crushing the frantic penguins and slithering over the glistening floor that it and its kind had swept so evilly free of all litter." - H. P. Lovecraft, At The Mountains of Madness


Table of contents

What's New

  • Script Changes
    • NewScriptFeatures are enabled by default, see OGRE_USE_NEW_COMPILERS in OgreConfig.h
    • Unified script syntax (.os), can contain anything that would have been in type-specific scripts (.material, .particle etc)
    • Import other scripts via the 'import' directive
    • More flexible syntax, quoted identifiers supported
    • Substitutable variables are supported
    • Interception of script parsing events now possible for custom behaviour
  • Material Changes
    • 'manual_named_constants' directive added for assembler shaders to allow you to associate named parameters stored in a file with assembler. The file can be created from the GpuNamedParameters from high-level source if you want to precompile them.
    • 'gpu_vendor_rule' and 'gpu_device_rule' allow you to influence the techniques which are used with inclusive/exclusive matching rules on the vendor and device name. Can help tune your materials for vendor or device-specific behaviour.
    • '#include' directive now supported in HLSL and Cg shaders
    • Added MaterialManager::Listener
      • Can implement default Technique setting when using a material scheme for which there isn't a specific Technique
      • Can use to change materials for all objects easily per viewport by using a new scheme name
    • Added Pass::setPolygonModeOverrideable / script 'polygon_mode_overrideable'
      • Allows pass-level control over whether the camera's polygon mode should affect rendering
    • Added 'light_scissor' option to Pass
      • Allows pass fragment processing to be limited to a scissor rectangle of the light coverage in that pass
      • Additive texture and stencil shadows now use scissor automatically for additive colour passes, previously just used for rendering stencil shadow volumes
    • Added 'iteration_depth_bias' option to pass. Allows you to increment the depth bias on a pass by a specific amount each iteration if you wish
    • 'light_number' GPU parameter binding added
    • 'light_count' GPU parameter binding added
    • 'spotlight_viewproj_matrix' and 'spotlight_worldviewproj_matrix' added so you can use matrices from spotlights even without having set up texture shadows or an explicit texture projector
    • Added 'light_clip_planes' option to Pass
      • Clips triangles to a cube (point lights) or pyramid (spot lights)
      • Available when the pass is only using one light and you need to restrict complexity
    • Added 'separate_scene_blend' option to Pass
      • Allows the use of separate blend operations for colour and alpha between rendered pixel and existing frame buffer
    • Added pass option 'illumination_stage'
      • Allows material writers to assert control over the illumination pass compilation (additive shadows)
      • You can now incorporate sequences you could not before in your additive lighting materials
      • For example, allows you to include specular effects by pulling the decal pass into the per-light pass if that works for your material (offset mapping used as an example)
    • Added 'gamma' option to texture declaration in texture_unit (sRGB support)
      • Causes hardware to perform gamma space to linear space conversion when sampling the texture
      • Useful only for 8-bit per channel colour textures (not floating point textures or normal maps)
      • Can improve quality results from shaders because they mostly assume calculations are done in linear space
      • You will need to convert results back to gamma space when rendering to an 8-bit per channel render target either via a shader instruction or enabling the gamma correction option in RenderWindow or on the render texture
    • Added 'transparent_sorting' option to Pass, allows you to disable depth sorting for transparencies
    • Added 'alpha_to_coverage' option to Pass, allowing you to use alpha to coverage to multisample alpha-rejected textures. Even though this is a Dx10 feature, it is available on Dx9 for recent ATI and NVIDIA cards, and OpenGL on all cards that implement it.
  • Frustum / Camera Changes
    • Orthographic projection now allows explicit setting of orthographic window size
    • Added Camera::getCameraToViewportBoxVolume. Similar to getCameraToViewportRay but generates a PlaneBoundedVolume from a screen-space rectangle which can be used in a PlaneBoundedVolumeListSceneQuery to do rubber-band selections
    • Added Frustum::setFrustumExtents - allows you to specify the left/right/top/bottom planes manually and thus create any shape frustum you need to, even without the camera being in the centre of it
  • MovableObject changes
    • An object will no longer render its debug display if set to visible (e.g. via a cascading visibility update), you have to explicitly turn on the debug display. This is available via MovableObject::setDebugDisplayEnabled and SceneNode::setDebugDisplayEnabled
    • Added visitRenderables() method - allows you to get a callback to a Renderable::Visitor class for all Renderables that this object will potentially add to the render queue. Identifies LOD and debug renderables.
  • Scaling Issues
    • By default now, renormalisation of normals is automatic if there is a non-unit scale on the main world matrix rather than the Entity::setNormaliseNormals option. If the user wants to optimise this, they can prevent the SceneManager doing it in all cases by calling SceneManager::setNormaliseNormalsOnScale(false) and then explicitly enabling the option per Pass instead. In the case of an array of world matrices being used, if the first world matrix isn't a guide then the shader writer should handle the renormalisation.
    • By default now, Ogre will flip the culling mode of objects that are rendered with a negative scale (ie they are reflected by the transform of the node). This means you can now negatively scale objects and they will be rendered correctly. You can disable this behaviour by calling SceneManager::setFlipCullingOnNegativeScale(false)
  • Compositor Changes
    • You can now define Multiple Render Targets (MRT) in compositor scripts.
      • To define a MRT, just list all the formats one after the other in the 'texture' definition.
      • To reference a MRT subsurface later in a render_quad pass, use the optional extra 'mrtIndex' at the end of the 'input' command
      • Note: as at this time, D3D requires that all surfaces of the MRT are of the same bit depth, and GL requires them to be of the same format
    • Compositors now detect when the viewport they are attached to is using sRGB or multisample antialiasing, and apply the same settings to any intermediate textures which are having the original scene rendered to them (explicitly via a 'render_scene' pass or implicitly via 'input previous')
    • The 'texture' directive now supports specifying a size which is a multiple of the main target size. You can use 'target_width_scaled' and 'target_height_scaled', each followed by a floating-point scaling factor, so 'target_width_scaled 0.5' for example would result in a texture with a width of half the size of the target the compositor is applied to.
  • FrameListener changes
    • Added new callback 'frameRenderingQueued'. This callback occurs after all rendering commands have been sent to all render targets, but before the double-buffered targets (windows) are asked to swap their buffers. This allows you to perform some useful work on the CPU in the main thread whilst the GPU chews over the queued rendering commands. On return from the callback, the buffers will be swapped. This is equivalent to running your own rendering loop in previous versions and using RenderWindow::update(false) then RenderWindow::swapBuffers separately, but it now makes the technique available in the standard render loop.
  • SceneManager changes
    • Chaster's 'Portal Connected Zone' SceneManager added
    • 'Camera relative rendering' option added so that in large scenes where you are far from the origin, precision issues on the GPU can be mitigated by only transforming objects relative to the camera. See SceneManager::setCameraRelativeRendering
  • ManualObject changes
    • 4D texture coordinates now supported
    • 32-bit indexes now supported
  • Tangents generation changes
    • New TangentSpaceCalc class can be used to calculate tangents for any geometry more easily, not just Mesh
    • Now generates tangents based on a UV-area weighted, triangle angle weighted basis resulting in less biasing from small / thin triangles
    • Now has options for splitting vertices when the tangent space basis is either mirrored or rotated around a vertex.
    • Tangents can now be stored as a 4-component vector, with the 'w' component containing the parity. Multiply the binormal/bitangent you calculate in your shader by this to render models with mirrored UVs correctly.
  • Resource changes
    • Resource now has a lightweight way to observe whether it has been reloaded since you last looked at it, via getStateCount(). Other changes known to make derived data out of date may also increment this number. This allows Entity to now pick up when Mesh has been altered and refresh itself on next render.
    • You can now query for file modification times via ResourceGroupManager::resourceModifiedTime
  • RenderSystemCapabilities changes
    • RenderSystem capabilities can now be serialised and these configs used to emulate lesser hardware
    • More information about graphics card is exposed in this structure now, including device name, driver version and also enumerates the most common vendors
  • SkyBox changes
    • Skyboxes now detect and can use materials which use the 'combinedUVW' option to cubic_texture. Allows you to use the same single combined DDS for both reflection maps and skybox (previously the skybox had to be 6 separate images)
  • RenderWindow changes
    • You can now request the hardware to perform linear-to-sRGB colour space conversions for you, before the blending calculation. Use the 'gamma' name-value pair option on creation of a window or the "sRGB Gamma Conversion" render system config option for the auto-window.
  • Render to Texture changes
    • You can now enable sRGB conversion on render textures when you create them
    • Multisample antialiasing is now supported when rendering to textures, specify the number of samples when you create the texture
    • MRTs with different bit depths are now supported if the hardware exposes the facility (check RSC_MRT_DIFFERENT_BIT_DEPTHS)
  • Image Changes
    • Ogre can now detect the format of an image without needing a file extension, so you can load data from streams without knowing what file it came from. The Codec system has been expanded to provide support for recognising 'magic' signatures.
  • Light changes
    • Lights now have a 'power' value as well as a colour, for HDR lights (defaults to 1.0)
    • Derived light colour auto-params are now factored by the light power
    • Lights can now have their own shadow far distance settings (default is to continue to use the SceneManager global one)
  • Animation Changes
    • You can now use 'skeletal blend masks' to simplify the process of combining multiple layered animations to subsets of skeletons, or temporarily masking out the application of predefined animation to given bones (e.g. in order to manually control them). You create & apply these through AnimationState.
    • AnimationTrack::Listener allows you to override interpolation and drive animation procedurally if you wish
  • Threading changes
    • OGRE_THREAD_SUPPORT can now take 3 values, 0=no threading, 1=full background loading, 2=semithreading (background preparing). The new option allows you to use a background thread just to perform I/O or calculate data, but for the main thread still to be responsible for dealing with the rendersystem. This means less synchronisation is required (since the rendersystem can still run without any threading protection) and thus there are fewer overheads involved in using background loading, at the expense of a slightly more complicated setup.
  • Renderable changes
    • Added preRender and postRender methods that let you further customise the render operations that are performed by a specific Renderable
  • Archive changes
    • Added Archive::getModifiedTime to allow you to query for file changes
  • Camera changes
    • Camera now has an optional 'LOD Camera' which can be used to make LOD decisions based on a different camera
  • Shadow changes
    • Texture shadows now base LOD on the main view's camera, not on the shadow camera
    • Multiple textures per light are now supported, allowing techniques such as Parallel Split Shadow Maps, Dual-parabaloid Shadow Maps and Cubic Shadow Maps to be implemented
    • Implementation of Parallel Split Shadow Maps (PSSM) is included, use the new class PSSMShadowCameraSetup. Integrated shadows are required since shaders are required to pick the appropriate shadow map. See PlayPen::testTextureShadowsIntegratedPSSM for an example.
  • Geometry shader support
    • Currently supported in OpenGL only (until Dx10 renderer complete)
    • ParticleGS and IsoSurf demos added
    • RenderToVertexBuffer support also added
  • Memory management changes
    • Custom allocators now supported
    • New debug memory tracker for tracking memory usage by pool, and identifying leaks

Porting notes

  • Root changes
    • getCurrentFrameNumber has been removed and replaced with getNextFrameNumber. The reason is that it now reflects the frame in which any changes you're making will take effect; the distinction is needed for those wanting to perform changes in the FrameListener::frameRenderingQueued callback. Changes made here will be made in the same frame number as the next frame to be rendered, so state changed here will persist for the next frame.
    • If you run your own rendering loop and have to raise frame events yourself, you must now call Root::_fireFrameRenderingQueued as well as the frame started / ended event firing methods. It is here that the frame number is incremented now.
  • ExampleFrameListener changes
    • The default behaviour of frameStarted is now contained in frameRenderingQueued as an example of using the new event.
  • Frustum changes
    • When set to orthographic mode, the Frustum size is no longer based on the FOV and near clip plane. Instead, set the orthographic window specifically using setOrthoWindow / setOrthoWindowHeight. Only the height is stored, the width is derived from the aspect ratio.
  • Renderable changes
    • getWorldPosition and getWorldOrientation removed from Renderable interface, not used
      • NOTE: the Node::* versions of the same name have also been removed. Use _getDerivedPosition/_getDerivedOrientation instead.
    • Renderable::Visitor added as an abstract way to enquire on a Renderable contained in any other object. Also see MovableObject changes.
    • Renderable::getClipPlanes method has been removed. Wasn't used for anything in OGRE and there are more useful ways the finite number of clip planes available can be used
  • SceneManager changes
    • ShadowListener has been changed to SceneManager::Listener and additional methods have been added
    • SceneManager::renderSingleObject now takes a non-const Renderable pointer
    • QueuedRenderableVisitor::visit now takes a non-const Renderable pointer, and a non-const RenderablePass pointer
  • RenderQueue changes
    • RenderableListener::renderableQueued interface changed, please check your implementations
  • Shadow changes
    • The default additive texture and stencil shadows now use a scissor rectangle based on the light coverage when rendering the additive colour passes. Previously the scissor was only used when rendering the stencil shadow volumes. Should not affect your scenes unless you are using a shader which used to apply light outside the light's attenuation range; if you did do this, the light will now be cropped.
  • Entity changes
    • setNormaliseNormals has been removed. Renormalisation is now automatic (see Changelog for details)
  • Compositor changes
    • CompositionTechnique::TextureDefinition no longer has a single 'format' member, instead it has a 'formatList' member into which you should push requested formats (only a single entry unless you want to use MRTs)
  • RenderSystemCapabilities changes
    • A few 'numBlah' methods have been renamed to the more standard 'getNumBlah' equivalent
  • RenderSystem changes
    • createRenderTexture has been removed. It has been deprecated for 2 versions, you should be using TextureManager::create with a usage mode of TU_RENDERTARGET
    • 'initialise' and 'createRenderWindow' are now called '_initialise' and '_createRenderWindow' respectively, to indicate that it's important to call Root's versions of these methods. Failure to do so can cause some key initialisation to be missed on the first window.
  • FileSystem changes
    • By default, hidden files and folders are ignored in the traversal now. You can change this via FileSystem::setIgnoreHidden, but it's useful for operating in CVS / SVN folders for example where the metadata folders are now skipped.
  • Script changes
    • You must prefix all top-level entries in the script system with the type - e.g. 'particle_system' and 'overlay'
    • If you have any problems with the new compilers you can revert to the old ones as a last resort by changing OgreConfig.h and rebuilding Ogre
  • Header changes
    • OgreMemoryMacros.h and OgreNoMemoryMacros.h no longer exist, you should delete any reference you have to them
  • DataStream changes
    • MemoryDataStream changes
      • If you pass a pointer to existing memory and set the 'freeOnClose' parameter to 'true', it is imperitive that you allocated the memory using OGRE_ALLOC_T or OGRE_MALLOC and used a category of MEMCATEGORY_GENERAL to ensure the freeing of memory matches up.
      • If you allow MemoryDataStream to allocate the memory itself, but free the memory yourself later (you set freeOnClose to false), you must free using OGRE_FREE(ptr, MEMCATEGORY_GENERAL), again to match up with the original allocation.
    • FileStreamDataStream changes
      • If you ask FileStreamDataStream to delete the std::ifstream for you on destruction, you must have allocated it with OGRE_NEW_T with a category of MEMCATEGORY_GENERAL
  • Image changes
    • If you transfer ownership of data to / from Image via the loadDynamicImage method, you must make sure that memory is allocated and freed consistently. Again, allocate and free via OGRE_ALLOC_T or OGRE_MALLOC and OGRE_FREE and use the MEMCATEGORY_GENERAL category.
  • SharedPtr changes
    • SharedPtr now has an optional second parameter to the constructor and bind() methods, indicating the method by which the memory should be freed. It defaults to OGRE_DELETE which is sufficient for instances constructed with new or OGRE_NEW. If you constructed using the new memory functions OGRE_NEW_T or OGRE_ALLOC_T then you should change this parameter to make it use OGRE_DELETE_T and OGRE_FREE respectively, so that the deallocation matches up. Only MEMCATEGORY_GENERAL is supported.
  • Archive changes
    • New method added: 'getModifiedTime' - this must be implemented by custom archives to return the file modification time
  • ShadowCameraSetup changes
    • An additional parameter, 'iteration', has been added to the getShadowCamera method to allow the support of multiple shadow textures per light. All ShadowCameraSetup implementations must be updated to include this new signature
  • ResourceBackgroundQueue changes
    • ResourceBackgroundQueue::Listener methods have changed signature; operationCompleted and operationCompletedInThread now have an additional parameter containing the result of the operation, allowing you to detect errors.