Changes and Porting Tips for 0.7.0

Introduction

This is work in progress, so while this page will be kept as up-to-date as possible, what you read here on any given day will never be definitive and is subject to further change until such time as a stable release is made. There are no current download packages contain the code this page relates to; this code is only available from the cegui_mk2/trunk directory in the subversion repository (see HOWTO: Obtain the library source from subversion.

Also note that while attempts have been made to see that most of the major changes are listed on this page, it's entirely possible - even likely - that somewhere along the line some things have been missed out. In those cases, please visit the CEGUI forums

Organisation and Structure

The overall structure of the CEGUI code tree has been considerably modified:

• All actual code for the library and associated modules has been relocated beneath a 'cegui' directory, within this directory there is are src and include subdirectories that contain the source code and public headers respectively. Possibly one of the main advantages of this is that non-linux based systems will now have an identical header layout to what linux has always had.
• In addition to this main change, the datafiles directory has moved from Samples to the root directory.
• The XMLRefSchema directory has moved into the datafiles directory and is renamed xml_schemas.
• Other changes will largely have minimal impact so we've not covered everything in minute detail.

The file and directory naming for Renderer implementaions has been modified, although is now unified for all implementations:

• Headers are now accessed RendererModules/<name of API>/CEGUI<name of API><name of component>.h
  • Examples:
    • the OpenGL renderer header is at: RendererModules/OpenGL/CEGUIOpenGLRenderer.h
    • the Ogre geometry buffer header is at: RendererModules/Ogre/CEGUIOgreGeometryBuffer.h
    • the Direct3D10 render target header is at: RendererModules/Direct3D10/CEGUIDirect3D10RenderTarget.h

Windows / MSVC++ changes

The renderer module output has been unified with that of other systems, so for example, rather than OpenGLGUIRenderer.dll it's now CEGUIOpenGLRenderer.dll.

Apple Mac / Xcode changes

We are changing the default bundle locations regarding both embedded frameworks and loadable bundles.

• Previously all frameworks were incorrectly expected to be in the app bundle's Resources directory, additionally the XMLParser and ImageCodec based loadable modules (bundles) were packaged within the CEGUI framework itself, this has changed as follows:
  • All CEGUI related frameworks are to be placed in the correct location of the app bundles's Frameworks directory.
  • The XMLParser and ImageCodec based modules are to be placed within the app bundles PlugIns directory. This decision was taken because it's up to each app developer to decide which loadable bundles they want to support and so it's more logical to have those placed at the app level rather than embedded deeper within the CEGUI frameworks. Having said this, CEGUI will still look in the PlugIns location of the CEGUIBase framework for bundles; if you wish to reconfigure the loadable bundle targets to be placed there instead, CEGUI will find them (it's just that it's not the preferred default).

The main framework is renamed from CEGUI to CEGUIBase

• This is mostly to have parity across all platforms as far as module names go, although also reflects the fact that 'CEGUI' on the Mac is no longer a monolithic entity.

If you previously relied upon adding the framework to your project and using the CEGUI prefix in include lines, you will either have to add the framework Headers directory in the search paths, or change the include statements accordingly. (If you'd like this changed back, nag us!)

Window and WindowRenderer factory registration changes

There have been changes / additions to the way that new factories for Window and WindowRenderer subclasses are registered with the system. This removes the old preprocessor macro based system with a much cleaner template based arrangement that means you no longer need to directly create your factory classes and nor do you need to keep a static instance hanging around. The overall impact of this means that it's now incredibly simple to register new classes with the system

• If you have a Window subclass named 'MyWidget, to add this to the system you can now simply do:

<cpp/>CEGUI::WindowFactoryManager::addFactory<TplWindowFactory<MyWidget> >();

• If you have a WindowRenderer subclass named 'MyWidgetRenderer', to add this to the system you can now simply do:

<cpp/>CEGUI::WindowRendererManager::addFactory<TplWindowRendererFactory<MyWidgetRenderer> >();

• Anybody creating a WindowRenderSet module will find that the macro system previously employed for that purpose has been removed in favour of a class based approach. As well as making the code more transparent and generally easier to set up, it also means your module just needs to export a single function to returns a CEGUI::WindowRendererModule object; all other interactions are done via that object.

Window interface breaking / behavioural changes.

• getRenderCache is removed. You probably now want to be doing something with getGeometryBuffer.
• requestRedraw function is replaced by invalidate function (NB: function also changes from const to non-const)
• render function now takes a RenderingContext object pointer.
• drawSelf function replaces float z parameter with a const reference to a RenderingContext object.
• Protected member RenderCache d_renderCache is removed.
• Window::EventRenderingStarted and Window::EventRenderingEnded are now fired only when a Window object's GeometryBuffer content gets regenerated.
• Window 'inner rect' support is now functioning as it should; this means that many layouts - especially those using FrameWindow - will need to be updated. Or put another way, child content is now positioned and sized based upon the window client area (inner rect) as opposed to the overall area - this resolves long standing issues such as content getting hidden by the titlebar when sizing / switching skins.

Renderer breaking interface changes and related items.

• Renderer objects are no longer directly created or destroyed. Use the static create and destroy functions to create the renderer objects.
• Unused OrientationFlags enumeration is removed.
• addQuad function is removed. Geometry is now added directly to the per-window GeometryBuffer object(s).
• clearRenderList function is removed.
• setQueueingEnabled function is removed.
• isQueueingEnabled function is removed.
• doRender function is removed. Final rendering is now achieved by calling draw on the root RenderingSurface(s).
• getWidth and getHeight functions are removed.
• getSize function becomes getDisplaySize returning a const Size reference.
• getRect function is removed.
• getHorzScrennDPI and getVertScreenDPI are replaced with a single getDisplayDPI function returning a const Vector2 reference.
• resetZValue function is removed.
• advanceZValue function is removed.
• getCurrentZ function is removed.
• getZLayer function is removed.
• createTexture function taking a single float value is replaced by createTexture taking a const reference to a Size object.
• createResourceProvider function is removed. A DefaultResourceProvider is now used unless you explicitly provide an alternative.
• The protected member String d_identifierString is removed.
• The protected member ResourceProvider d_resourceProvider is removed.
• The renderer is no longer derived from EventSet. The Renderer::EventDisplaySizeChanged is moved to the System object. Informing the system that the display has changed size is now done by calling System::notifyDisplaySizeChanged, which in turn will set the display size back on the Renderer object. This gives a fully uniform interface for this procedure, and is better than the old ad-hoc approach.

For people wanting an overview of the new renderer arrangements, perhaps prior to porting an existing renderer module (or if you're looking to writing a new one), please see An Overview of Renderer Model 2 (pdf)

Texture breaking interface changes.

• getWidth and getHeight are replaced with a single getSize function returning a const Size reference.
• getOriginalWidth and getOriginalHeight are replaced with a single getOriginalDataSize function returning a const Size reference.
• getYScale and getXScale are replaced with a single getTexelScaling function returning a const Vector2 reference.
• loadFromMemory replaces the float buffWidth and buffHeight parameters with a single Size object reference buffer_size parameter.
• getRenderer function is removed.

Miscellany

• All Font, Imageset and Image drawing functions have an added parameter receiving a GeometryBuffer reference, and have had the float z parameter removed.
• ImagesetManager::createImageset overload taking a Texture pointer is replaced with a version taking a Texture reference.
• ImagesetManager::notifyScreenResolution function renamed to ImagesetManager::notifyDisplaySizeChanged.
• Imageset::notifyScreenResolution function renamed to Imageset::notifyDisplaySizeChanged.
• Imageset constructor taking a Texture pointer is replaced with a version taking a Texture reference.
• FontManager::notifyScreenResolution function renamed to FontManager::notifyDisplaySizeChanged.
• Font::notifyScreenResolution function renamed to Font::notifyDisplaySizeChanged.
• MouseCursor member d_position changes type from Vector3 to Vector2

More to come...

CrazyEddie 11:25, 22 March 2009 (UTC)