Axiom To Ogre v1.6 - Axiom : A 3D Rendering Engine in C#

Axiom To Ogre v1.6

From Axiom

Jump to: navigation, search
 Not Started or Tested
 In Progress or Partially Implemented
 Implemented and Compatible ( See notes )
 Can't or Won't Implement

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

"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

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.
Powered by MediaWiki GNU Free Documentation License 1.2