CEGUI笔记

CEGUI笔记

开发环境：
CEGUI 0.74，OGRE 1.72

教程：
CEGUI and Ogre
http://www.ogre3d.org/tikiwiki/tiki-print.php?page_ref_id=262&page=Basic%20Tutorial%207#Initializing_CEGUI

The Beginners Guide to Getting CEGUI Rendering
http://www.cegui.org.uk/api_reference/rendering_tutorial.html

CEGUI使用的基本三步骤

1. 创建CEGUI::Renderer对象.
2. 创建CEGUI::System 对象(passing in the renderer created above).
3. 在帧循环中调用CEGUI::System::renderGUI function to perform the rendering.

当然还需要做一些必要的初始化工作、与输入设备交互的准备工作
• The Beginners Guide to resource loading with ResourceProviders
• The Beginners Guide to Data Files and Defaults Initialisation
• The Beginners Guide to Injecting Inputs.

 

创建CEGUI::Renderer对象

为了创建CEGUI::Renderer对象,有两条路可以走:简单的和难的。

A.简单:bootstrapSystem快速创建。这种方式同时创建了renderer和system

CEGUI::OgreRenderer &  myRenderer  =  CEGUI::OgreRenderer::bootstrapSystem();

    booststrapSystem代码

OgreRenderer &  OgreRenderer::bootstrapSystem()
{
    if (System::getSingletonPtr())
        CEGUI_THROW(InvalidRequestException("OgreRenderer::bootstrapSystem: "
            "CEGUI::System object is already initialised."));

    OgreRenderer& renderer = create();
    OgreResourceProvider& rp = createOgreResourceProvider();
    OgreImageCodec& ic = createOgreImageCodec();
    System::create(renderer, &rp, static_cast<XMLParser*>(0), &ic);

    return renderer;
}

B.复杂:手动创建
如果不想使用bootstrapSystem创建对象，你可以手动创建。注意:如果已经使用了bootstrapSystem，则不能再手动创建。手动创建需要创建renderer和system。
1.创建CEGUI::Renderer对象

//  Create an OgreRenderer object that uses the default Ogre rendering
//  window as the default output surface.
CEGUI::OgreRenderer &  myRenderer  =  CEGUI::OgreRenderer::create();

2.创建CEGUI::System

CEGUI::System::create( myRenderer );

    system源码：

System &  System::create(Renderer &  renderer, ResourceProvider *  resourceProvider,
                       XMLParser *  xmlParser, ImageCodec *  imageCodec,
                       ScriptModule *  scriptModule,  const  String &  configFile,
                        const  String &  logFile)
{
    return *new System(renderer, resourceProvider, xmlParser, imageCodec,
                       scriptModule, configFile, logFile);
}

    可以发现system的创建函数就是完成system的构造。构造函数的第2个参数开始都带默认参数。

  - 删除Renderer

CEGUI::OgreRenderer::destroySystem();

 - 取回Renderer
CEGUI::Renderer中竟然没有取回renderer的方法!跟踪代码后发现只有system唯一一处保存了renderer。那么当然的就可以这样取回renderer了：

CEGUI::System  & sys  =  CEGUI::System::getSingleton();
CEGUI::Renderer *  ceguiRenderer  =  sys.getRenderer( void );

 

渲染CEGUIUI

不同的渲染引擎方式都不一样,一般就是在帧渲染中调用渲染方法:

System::getSingleton().renderGUI();

但是在Ogre中，CEGUI很巧妙的避免在帧渲染中手动添加代码，使用了监听者处理CEGUI渲染：

 1 // ! call stack
 2 CEGUIOgreRenderer_d.dll ! CEGUI::OgreGUIFrameListener::frameRenderingQueued
 3 OgreMain_d.dll ! Ogre::Root::_fireFrameRenderingQueued
 4 OgreMain_d.dll ! Ogre::Root::_fireFrameRenderingQueued
 5 OgreMain_d.dll ! Ogre::Root::_updateAllRenderTargets
 6 OgreMain_d.dll ! Ogre::Root::renderOneFrame
 7 OgreMain_d.dll ! Ogre::Root::startRendering
 8
 9 // !source code
10 bool  OgreGUIFrameListener::frameRenderingQueued( const  Ogre::FrameEvent & )
11 {
12    if (d_enabled)
13        System::getSingleton().renderGUI();
14
15    return true;
16}

那么cegui的帧监听者是如何创建的呢？
首先这个监听者是个静态对象，并且是用了全局唯一的方式声明。好像和单间模式的作用差不多。也许是作者的个人习惯吧。

//  Internal Ogre::FrameListener based class.  This is how we noew hook into the
//  rendering process (as opposed to render queues previously)
static   class  OgreGUIFrameListener :  public  Ogre::FrameListener
{
public:
    OgreGUIFrameListener();

    void setCEGUIRenderEnabled(bool enabled);
    bool isCEGUIRenderEnabled() const;

    bool frameRenderingQueued(const Ogre::FrameEvent& evt);

private:
    bool d_enabled;

}  S_frameListener;

其次这个监听者是在bootstrapSystem中创建的，正好是在OgreRenderer创建的同时创建

// ! call stack
CEGUIOgreRenderer_d.dll ! CEGUI::OgreRenderer::constructor_impl
CEGUIOgreRenderer_d.dll ! CEGUI::OgreRenderer::OgreRenderer
CEGUIOgreRenderer_d.dll ! CEGUI::OgreRenderer::create
CEGUIOgreRenderer_d.dll ! CEGUI::OgreRenderer::bootstrapSystem

// ! source code
void  OgreRenderer::constructor_impl(Ogre::RenderTarget &  target)
{
    d_renderSystem = d_ogreRoot->getRenderSystem();

    d_displaySize.d_width  = target.getWidth();
    d_displaySize.d_height = target.getHeight();

    // create default target & rendering root (surface) that uses it
    d_defaultTarget = new OgreWindowTarget(*this, *d_renderSystem, target);
    d_defaultRoot = new RenderingRoot(*d_defaultTarget);

    // hook into the rendering process
    d_ogreRoot->addFrameListener(&S_frameListener);
}

    至此cegui的帧渲染水落石出。

注入按键事件

CEGUI::System  & sys  =  CEGUI::System::getSingleton();

  // !按下 ，同事需要注入字符，以便于处理非英语国家的utf8字符
sys.injectK;
sys.injectChar(arg.text);

// ! 按键弹起
CEGUI::System::getSingleton().injectKeyUp(arg.key);

 

注入鼠标事件

 code:

CEGUI::System::getSingleton().injectMouseButtonDown(convertButton(id));

CEGUI::System::getSingleton().injectMouseButtonUp(convertButton(id));

CEGUI::System  & sys  =  CEGUI::System::getSingleton().injectMouseMove(arg.state.X.rel, arg.state.Y.rel);

CEGUI::MouseButton convertButton(OIS::MouseButtonID buttonID)
{
    switch (buttonID)
    {
    case OIS::MB_Left:
        return CEGUI::LeftButton;
    case OIS::MB_Right:
        return CEGUI::RightButto  case OIS::MB_Middle:
        return CEGUI::MiddleButton;
    default:
        return CEGUI::LeftButton;
    }
}

 

 

加载CEGUI编辑器产生的窗口

code:

CEGUI::Window  * guiRoot  =  CEGUI::WindowManager::getSingleton().loadWindowLayout( " TextDemo.layout " ); 
CEGUI::System::getSingleton().setGUISheet(guiRoot);

 

手动创建CEGUI窗口对象

code:

// ! 必须使用框架提供的管理器，窗口必须作为sheet的子窗口出现
CEGUI::WindowManager  & wmgr  =  CEGUI::WindowManager::getSingleton();
CEGUI::Window  * sheet  =  wmgr.createWindow( " DefaultWindow " ,  " CEGUIDemo/Sheet " );

// ! 创建一个窗口，此时并未接入sheet作为子窗口，所以并未展现
CEGUI::Window  * quit  =  wmgr.createWindow( " TaharezLook/Button " ,  " CEGUIDemo/QuitButton " );
quit -> setText( " Quit " );
quit -> setSize(CEGUI::UVector2(CEGUI::UDim( 0.15 ,  0 ), CEGUI::UDim( 0.05 ,  0 )));


// ! 窗口加入sheet以便展现
sheet -> addChildWindow(quit);
CEGUI::System::getSingleton().setGUISheet(sheet);

// ! 以上创建的是一个按钮，名字为“Quit”，为了响应按钮按下消息，需要在框架中注册监听消息,链接监听回调
quit -> subscribeEvent(CEGUI::PushButton::EventClicked, CEGUI::Event::Subscriber( & BasicTutorial7::quit,  this ));

 

渲染到纹理、画中画效果

code:

// ! 创建自定义纹理对象
Ogre::TexturePtr tex  =  mRoot -> getTextureManager() -> createManual(
     " RTT " ,
    Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,
    Ogre::TEX_TYPE_2D,
     512 ,
     512 ,
     0 ,
    Ogre::PF_R8G8B8,
    Ogre::TU_RENDERTARGET);
Ogre::RenderTexture  * rtex  =  tex -> getBuffer() -> getRenderTarget();

// ! 创建一个新的照相机和视口，记得关闭视口的一些特性例如Overlays,否则我们创建的CEGUI窗口和OGRE会出现重叠
Ogre::Camera  * cam  =  mSceneMgr -> createCamera( " RTTCam " );
cam -> setPosition( 100 ,  - 100 ,  - 400 );
cam -> lookAt( 0 ,  0 ,  - 300 );
Ogre::Viewport  * v  =  rtex -> addViewport(cam);
v -> setOverlaysEnabled( false );
v -> setClearEveryFrame( true );
v -> setBackgroundColour(Ogre::ColourValue::Black);

// ! 从CEGUI引导对象创建CEGUI纹理
// ! mRenderer(类型为CEGUI::OgreRenderer*)正是第一部创建的CEGUI引导对象，
CEGUI::Texture  & guiTex  =  mRenderer -> createTexture(tex);

// ! 创建CEGUI图像对象集。注意:与CEGUI窗口对象需要在窗口对象集(sheet)的管理下使用类似，图像对象也需要在图像对象集的管理下使用
CEGUI::Imageset  & imageSet  =
  CEGUI::ImagesetManager::getSingleton().create( " RTTImageset " , guiTex);
imageSet.defineImage( " RTTImage " ,
                     CEGUI::Point( 0.0f ,  0.0f ),
                     CEGUI::Size(guiTex.getSize().d_width,
                                 guiTex.getSize().d_height),
                     CEGUI::Point( 0.0f ,  0.0f ));

// ! 创建CEGUI窗口，之前已经介绍过，这里和它没有区别
CEGUI::Window  * si  =  CEGUI::WindowManager::getSingleton().createWindow( " TaharezLook/StaticImage " ,  " RTTWindow " );
si -> setSize(CEGUI::UVector2(CEGUI::UDim( 0.5f ,  0 ),
                            CEGUI::UDim( 0.4f ,  0 )));
si -> setPosition(CEGUI::UVector2(CEGUI::UDim( 0.5f ,  0 ),
                                CEGUI::UDim( 0.0f ,  0 )));

// ! 指定窗口中展现的图片，取得图像对象依然必须经过图像集对象
si -> setProperty( " Image " , CEGUI::PropertyHelper::imageToString( & imageSet.getImage( " RTTImage " )));

// ! 将窗口加入窗口集(sheet),前面已经介绍过
sheet -> addChildWindow(si);

加载CEGUI资源

考察一个这样加载资源的过程：

    CEGUI::SchemeManager::getSingleton().create( " TaharezLook.scheme " );

加载之前先设置schememanager的资源分组

    CEGUI::Scheme::setDefaultResourceGroup( " Schemes " );

在资源配置里这样设置：

[Schemes]
FileSystem = .. / media / cegui / datafiles / schemes

则创建"taharezlook.scheme"的时候会在"...datafiles/schemes"中查找对应的文件。

代码分析：

call stack

CEGUIOgreRenderer_d.dll ! CEGUI::OgreResourceProvider::loadRawDataContainer
CEGUIExpatParser_d.dll ! CEGUI::ExpatParser::parseXMLFile
CEGUIBase_d.dll ! CEGUI::Scheme_xmlHandler::Scheme_xmlHandler
CEGUIBase_d.dll ! CEGUI::NamedXMLResourceManager < CEGUI::Scheme,CEGUI::Scheme_xmlHandler > ::create
Tutorial7.exe ! Tutorial7::createScene

加载资源

 1 void  OgreResourceProvider::loadRawDataContainer( const  String &  filename,
 2                                                 RawDataContainer &  output,
 3                                                  const  String &  resourceGroup)
 4 {
 5    String orpGroup;
 6    if (resourceGroup.empty())
 7        orpGroup = d_defaultResourceGroup.empty() ?
 8            Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME.c_str() :
 9            d_defaultResourceGroup;
10    else
11        orpGroup = resourceGroup;
12
13    Ogre::DataStreamPtr input = Ogre::ResourceGroupManager::getSingleton().
14        openResource(filename.c_str(), orpGroup.c_str());
15
16    if (input.isNull())
17        CEGUI_THROW(InvalidRequestException(
18            "OgreCEGUIResourceProvider::loadRawDataContainer: Unable to open "
19            "resource file '" + filename + "' in resource group '" + orpGroup +
20            "'."));
21
22    Ogre::String buf = input->getAsString();
23    const size_t memBuffSize = buf.length();
24
25    unsigned char* mem = new unsigned char[memBuffSize];
26    memcpy(mem, buf.c_str(), memBuffSize);
27
28    output.setData(mem);
29    output.setSize(memBuffSize);
30}

由此可见ceguiogrerenderer将cegui的资源加载与ogre链接起来了。

用std::string替换CEGUI::String

幸运的是cegui开发小组已经完成了这个小工作，不幸的是这项工作在cegui 0.8才会有。不过也可以自己手动修改。这个修改作为cegui 的一个issue发布了：

Description

I have created a patch that allows CEGUI to use both the inbuilt utf32 String as well as std::string (with 8bit characters). std::string has lower memory requirements and can be (in very special circumstances) faster (easier pass by const reference, etc...). This is intended for library users not needing Unicode support (which I imagine is a large percentage).

Additional Information

This patch adds a configuration switch CEGUI_STRING_CLASS, three options are available: Unicode - utf32 inbuilt string - utf8 and utf32 support std::string - no unicode support std::string allocated with allocators - same but pass by reference can be harder but is allocated according to the allocator config This has not been committed yet! The only macro preprocessor if/ifdefs are in CEGUIString.h and CEGUIDefaultResourceProvider.h (in the Windows-only utf16 to utf8/char conversion functions).

详情: 0000421: Configuration option to use std::string as CEGUI::String

若干不胜其烦的小失误

大小写敏感---这个小错误让偶跟踪了一个多小时cegui源码，谁会想到是拼写错误呢