OGRE示例Demo_BSP代码分析

最近在自学OGRE，自我感觉分析具体代码的时候就像在拨香蕉皮，一层嵌套另一层。

Resource life cycle感觉挺重要的，针对这个Demo分析下吧。

Class BspApplication中，有三个保护性成员变量

 protected:

 String mQuakePk3;                                   
 String mQuakeLevel;
 ExampleLoadingBar mLoadingBar;

 前面两个成员变量会在void setupResources(void)中被初始化

 ConfigFile cf;

 cf.load("quake3settings.cfg");

 mQuakePk3 = cf.getSetting("Pak0Location"); //从字面上看是读取资源路径
 mQuakeLevel = cf.getSetting("Map");           //字面上看跟地图有关

现在来看getSetting做了些什么，它的函数原型是，

String getSetting (const String& key, const String& section = StringUtil::BLANK, const String& defaultValue = StringUtil::BLANK) const

首先从直观上来判断，这个函数寻找脚本中的一个键值，然后返回一个字符串给接受着，例子中的键值分别是PakOLocation和Map.那么返回的字符串到底有何用呢，为了找到答案还是查阅下ogre的API手册，我的当前版本是1.4.0，OGRE世纪版本是1.6.1看来老了点，凑合用吧。。。。

手册上对该函数解释是 Gets the first setting from the file with the named key， 貌似是说返回键值指定的第一个设置，很模糊，接着看下面参数解释。。。

Parameters: 
  key  The name of the setting                                        
  section  The name of the section it must be in (if any)

看来还是没什么实际意义（对此手册很无语。。。），为了继续探寻，先看函数具体代码了

   

 String ConfigFile::getSetting(const String& key, const String& section, const String& defaultValue) const
    {
        
        SettingsBySection::const_iterator seci = mSettings.find(section);
        if (seci == mSettings.end())
        {
            return defaultValue;
        }
        else
        {
            SettingsMultiMap::const_iterator i = seci->second->find(key);
            if (i == seci->second->end())
            {
                return StringUtil::BLANK;
            }
            else
            {
                return i->second;
            }
        }
    }

此代码段给出的信息貌似不多，首先知道的是SettingsBySection是一个Map结构，定义为

typedef std :: map<String, SettingsMultiMap*> SettingsBySection,

其中第二项SettingsMultiMap是一个multimap结构，定义为

typedef std::multimap<String, String> SettingsMultiMap;

然后它定义了一个Iterator来找到脚本中符合section的一项，原程序中使用了默认值StringUtil::BLANK，于是接着if-else展开为三项，如果没有找到该值，就返回defaultValue,即StringUtil::BLANK,找到的话，执行

SettingsMultiMap::const_iterator i = seci->second->find(key);

等号右边表达比较诡异，只能更深层次挖掘，second的定义为

typedef struct tagSQL_DAY_SECOND
{
  SQLUINTEGER  day;
  SQLUINTEGER  hour;
  SQLUINTEGER  minute;
  SQLUINTEGER  second; //unsigned long型
  SQLUINTEGER  fraction;
} SQL_DAY_SECOND_STRUCT;

看来和秒有关系？实在想不出为什么。。。因为和秒相关太离谱，只能根据单词意思 “第二”做另外假设

因为结构声明上map里嵌套了一个multimap,second表示是在内层map中查找吧！

那么第二层else的意思就是如果在内层map中没有找到键值，就返回StringUtil::BLANK，如果找到就返回seci->second

为了确认这种推断，现在来用quake3settings.cfg做验证，这个配置文件相关内容是：

（令我很无语，这文件只有两行。。。）

Pak0Location: ../../../Media/packs/chiropteraDM.pk3 
Map: maps/chiropteradm.bsp

那么，在这个cfg文件被加载后，按照刚才对getSettings的分析，首先，它尝试再文件中寻找StringUtil::BLANK（就是字符串"BLANK"）如果最后一个元素匹配，那就返回"BLANK"，如果没有则进入内层map寻找key的值，这里键值是PakOLocation,很显然找到并返回 Pak0Location: ../../../Media/packs/chiropteraDM.pk3，找键值map时候同理。

 

以上分析中关注了从配置文件中读取信息，下面来分析一下cf.load("quake3settings.cfg")看OGRE怎样load文件。

经查找源代码，发现load函数根据传入参数不同有三个样本

void load(const String& filename, const String& separators = "/t:=", bool trimWhitespace = true);
        /// load from a filename (using resource group locations)
 

void load(const String& filename, const String& resourceGroup, const String& separators = "/t:=", bool trimWhitespace = true);
        /// load from a data stream
 

void load(const DataStreamPtr& stream, const String& separators = "/t:=", bool trimWhitespace = true);
        /// load from a filename (not using resource group locations)

并且前两个函数最终都调用了第三个load函数来进行加载，可以看出第二个函跟resourceGroup产生了互动，第三个使用了datastream. 先来分析第一个吧，第一个load的具体代码是

 

  void ConfigFile::load(const String& filename, const String& separators, bool trimWhitespace)
    {
        loadDirect(filename, separators, trimWhitespace);
    }

无奈接着找loadDirect,它的具体代码是

 void ConfigFile::loadDirect(const String& filename, const String& separators, 
  bool trimWhitespace)
 {
  /* Open the configuration file */
  std::ifstream fp;
        // Always open in binary mode
  fp.open(filename.c_str(), std::ios::in | std::ios::binary);
  if(!fp)
   OGRE_EXCEPT(
   Exception::ERR_FILE_NOT_FOUND, "'" + filename + "' file not found!", "ConfigFile::load" );

  // Wrap as a stream
  DataStreamPtr stream(OGRE_NEW FileStreamDataStream(filename, &fp, false));
  load(stream, separators, trimWhitespace);

 }

结构还算清晰，已经开始触及底层类了，主要分析下最后两行吧。。。

首先stream返回一个DataStreamPtr类型指针，DataStreamPtr是SharedPtr模板的一个实现，stream的参数是一个类的实例，此类是从DataStream派生而来，那么分析一下它具体的构造函数吧

 

 /** Construct stream from an STL stream
        @param s Pointer to source stream
        @param freeOnClose Whether to delete the underlying stream on 
            destruction of this class
        */
  FileStreamDataStream(std::ifstream* s, 
            bool freeOnClose = true);

描述上说明了这个stream类有STL支持，第二参数表示在释放该类实例时候要不要释放数据流。总而言之它的功能建立了一个与要加载文件的一个流供接下来的load函数使用。那么接下来看一看load(stream, separators, trimWhitespace);具体做了什么吧，首先是原函数代码。。。

 void ConfigFile::load(const DataStreamPtr& stream, const String& separators, 
        bool trimWhitespace)
    {
        /* Clear current settings map */
        clear();

        String currentSection = StringUtil::BLANK;
        SettingsMultiMap* currentSettings = OGRE_NEW_T(SettingsMultiMap, MEMCATEGORY_GENERAL)();
        mSettings[currentSection] = currentSettings;

        /* Process the file line for line */
        String line, optName, optVal;
        while (!stream->eof())
        {
            line = stream->getLine();
            /* Ignore comments & blanks */
            if (line.length() > 0 && line.at(0) != '#' && line.at(0) != '@')
            {
                if (line.at(0) == '[' && line.at(line.length()-1) == ']')
                {
                    // Section
                    currentSection = line.substr(1, line.length() - 2);
     SettingsBySection::const_iterator seci = mSettings.find(currentSection);
     if (seci == mSettings.end())
     {
      currentSettings = OGRE_NEW_T(SettingsMultiMap, MEMCATEGORY_GENERAL)();
      mSettings[currentSection] = currentSettings;
     }
     else
     {
      currentSettings = seci->second;
     } 
                }
                else
                {
                    /* Find the first seperator character and split the string there */
                    std::string::size_type separator_pos = line.find_first_of(separators, 0);
                    if (separator_pos != std::string::npos)
                    {
                        optName = line.substr(0, separator_pos);
                        /* Find the first non-seperator character following the name */
                        std::string::size_type nonseparator_pos = line.find_first_not_of(separators, separator_pos);
                        /* ... and extract the value */
                        /* Make sure we don't crash on an empty setting (it might be a valid value) */
                        optVal = (nonseparator_pos == std::string::npos) ? "" : line.substr(nonseparator_pos);
                        if (trimWhitespace)
                        {
                            StringUtil::trim(optVal);
                            StringUtil::trim(optName);
                        }
                        currentSettings->insert(std::multimap<String, String>::value_type(optName, optVal));
                    }
                }
            }
        }
    }

 

现在来分析void loadResources(void)函数

首先是mLoadingBar.start(mWindow, 1, 1, 0.75)，mLoadingBar被定义为ExampleLoadingBar的一个实例，该类的start函数具体代码如下

 

virtual void start(RenderWindow* window,

         unsigned short numGroupsInit = 1,

         unsigned short numGroupsLoad = 1,

         Real initProportion = 0.70f)

     {

         mWindow = window;

         mNumGroupsInit = numGroupsInit;

         mNumGroupsLoad = numGroupsLoad;

         mInitProportion = initProportion;

         // We need to pre-initialise the 'Bootstrap' group so we can use

         // the basic contents in the loading screen

         ResourceGroupManager::getSingleton().initialiseResourceGroup("Bootstrap");

 

         OverlayManager& omgr = OverlayManager::getSingleton();

         mLoadOverlay = (Overlay*)omgr.getByName("Core/LoadOverlay");

         if (!mLoadOverlay)

         {

              OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND,

                   "Cannot find loading overlay", "ExampleLoadingBar::start");

         }

         mLoadOverlay->show();

 

         // Save links to the bar and to the loading text, for updates as we go

         mLoadingBarElement = omgr.getOverlayElement("Core/LoadPanel/Bar/Progress");

         mLoadingCommentElement = omgr.getOverlayElement("Core/LoadPanel/Comment");

         mLoadingDescriptionElement = omgr.getOverlayElement("Core/LoadPanel/Description");

 

         OverlayElement* barContainer = omgr.getOverlayElement("Core/LoadPanel/Bar");

         mProgressBarMaxSize = barContainer->getWidth();

         mLoadingBarElement->setWidth(0);

 

         // self is listener

         ResourceGroupManager::getSingleton().addResourceGroupListener(this);

     }

纵观整个代码段，首先涉及到的关键语句是ResourceGroupManager::getSingleton().initialiseResourceGroup("Bootstrap");

从表面上看这段代码初始化了Bootstrap资源，具体怎样实现还要继续深层次挖掘，那么void initialiseResourceGroup (const String& name)的具体代码是

 

void ResourceGroupManager::initialiseResourceGroup(const String& name)

     {

         OGRE_LOCK_AUTO_MUTEX

         LogManager::getSingleton().logMessage("Initialising resource group " + name);

         ResourceGroup* grp = getResourceGroup(name);

         if (!grp)

         {

              OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND,

                   "Cannot find a group named " + name,

                   "ResourceGroupManager::initialiseResourceGroup");

         }

         OGRE_LOCK_MUTEX(grp->OGRE_AUTO_MUTEX_NAME) // lock group mutex

 

         if (grp->groupStatus == ResourceGroup::UNINITIALSED)

         {

              // in the process of initialising

              grp->groupStatus = ResourceGroup::INITIALISING;

              // Set current group

              parseResourceGroupScripts(grp);

              mCurrentGroup = grp;

              createDeclaredResources(grp);

              grp->groupStatus = ResourceGroup::INITIALISED;

 

              // Reset current group

              mCurrentGroup = 0;

         }

     }

从这段代码可以看出，首先它在log上保存加载状态信息，并加入了异常处理，接下来，ResourceGroup出现了UNINIIALSED, INITIALISING和INITIALISED三个状态，状态切换过程中，有两个函数需要关注，一个是parseResourceGroupScripts(grp)，另一个是createDeclaredResources(grp)，如果想知道细节，看来还要继续挖掘。不过这里首先放出一副ResourceGroup状态图，它显示了resource lifecycle

 

 

 

此图标注详细，不做过多注释了，接下来还是先看函数parseResourceGroupScripts具体代码

void ResourceGroupManager::parseResourceGroupScripts(ResourceGroup* grp)

     {

 

         LogManager::getSingleton().logMessage(

              "Parsing scripts for resource group " + grp->name);

 

         // Count up the number of scripts we have to parse

        typedef std::list<FileInfoListPtr> FileListList;

        typedef SharedPtr<FileListList> FileListListPtr;

        typedef std::pair<ScriptLoader*, FileListListPtr> LoaderFileListPair;

        typedef std::list<LoaderFileListPair> ScriptLoaderFileList;

        ScriptLoaderFileList scriptLoaderFileList;

         size_t scriptCount = 0;

         // Iterate over script users in loading order and get streams

         ScriptLoaderOrderMap::iterator oi;

         for (oi = mScriptLoaderOrderMap.begin();

              oi != mScriptLoaderOrderMap.end(); ++oi)

         {

              ScriptLoader* su = oi->second;

              // MEMCATEGORY_GENERAL is the only category supported for SharedPtr

            FileListListPtr fileListList(OGRE_NEW_T(FileListList, MEMCATEGORY_GENERAL)(), SPFM_DELETE_T);

 

              // Get all the patterns and search them

              const StringVector& patterns = su->getScriptPatterns();

              for (StringVector::const_iterator p = patterns.begin(); p != patterns.end(); ++p)

              {

                   FileInfoListPtr fileList = findResourceFileInfo(grp->name, *p);

                   scriptCount += fileList->size();

                   fileListList->push_back(fileList);

              }

            scriptLoaderFileList.push_back(

                LoaderFileListPair(su, fileListList));

         }

         // Fire scripting event

         fireResourceGroupScriptingStarted(grp->name, scriptCount);

 

         // Iterate over scripts and parse

         // Note we respect original ordering

        for (ScriptLoaderFileList::iterator slfli = scriptLoaderFileList.begin();

            slfli != scriptLoaderFileList.end(); ++slfli)

        {

              ScriptLoader* su = slfli->first;

            // Iterate over each list

            for (FileListList::iterator flli = slfli->second->begin(); flli != slfli->second->end(); ++flli)

            {

                  // Iterate over each item in the list

                  for (FileInfoList::iterator fii = (*flli)->begin(); fii != (*flli)->end(); ++fii)

                  {

                       bool skipScript = false;

                    fireScriptStarted(fii->filename, skipScript);

                       if(skipScript)

                       {

                            LogManager::getSingleton().logMessage(

                                 "Skipping script " + fii->filename);

                       }

                       else

                       {

                            LogManager::getSingleton().logMessage(

                                 "Parsing script " + fii->filename);

                        DataStreamPtr stream = fii->archive->open(fii->filename);

                        if (!stream.isNull())

                        {

                                 if (mLoadingListener)

                                     mLoadingListener->resourceStreamOpened(fii->filename, grp->name, 0, stream);

                            su->parseScript(stream, grp->name);

                        }

                    }

                       fireScriptEnded(fii->filename, skipScript);

                  }

            }

         }

 

         fireResourceGroupScriptingEnded(grp->name);

         LogManager::getSingleton().logMessage(

              "Finished parsing scripts for resource group " + grp->name);

     }

真是好长啊，无语了，接着读吧。。。。宏观上看了一下，感觉这个代码段借助STL定义了一些指针LIST来保存要加载资源的地址，然后对这些指针做逻辑安排，并将状态信息登陆到log里。在接下来的resourceloading中，这些指针应该会有用处。

 

从此段开始，我感觉再进行深层次代码上的挖掘会触及底层，因此偏离大的方向，所以，只对两个相关类以及一些函数的功能和属性进行概述性说明吧，两个相关类是FileInfo，ScriptLoader。

经过查找API手册，发现FileInfo是一个结构体，手册上对它的说明是

“Information about a file/directory within the archive will be returned using a FileInfo struct.”

 
 
Public Attributes
 
Archive * 
 archive
 
 
 The archive in which the file has been found (for info when performing multi-Archive searches, note you should still open through ResourceGroupManager). 
 
String 
 filename
 
 
 The file's fully qualified name. 
 
String 
 path
 
 
 Path name; separated by '/' and ending with '/'. 
 
String 
 basename
 
 
 Base filename. 
 
size_t 
 compressedSize
 
 
 Compressed size. 
 
size_t 
 uncompressedSize
 
 
 Uncompressed size. 
 

主要意思就是由Archive找到得文件信息都会保存在这个结构体中。接下来看scriptLoader,从手册中发现此类已经属于比较低层的类，因为许多manager类都继承了它的方法，比如SkeletonManager,TextureManager等等。手册上对此类的描述是“Abstract class defining the interface used by classes which wish to perform script loading to define instances of whatever they manage” 即此类属于抽象类，定义了一个接口，供继承自它的那些manager来调用，当这些manager要做脚本加载来定义实例的时候。顺手再放上一副类层次图吧，方便以后查阅

 

 

需要概述的函数有

1.fireResourceGroupScriptingStarted(grp->name, scriptCount)，2.fireResourceGroupScriptingEnded(grp->name)，

3.fireScriptStarted(fii->filename, skipScript)，

4.fireScriptEnded(fii->filename, skipScript)

5. mLoadingListener->resourceStreamOpened(fii->filename, grp->name, 0, stream);

6.su->parseScript(stream, grp->name)，

 

第一个函数的具体代码是

     void ResourceGroupManager::fireResourceGroupScriptingStarted(const String& groupName, size_t scriptCount)

     {

         OGRE_LOCK_AUTO_MUTEX

         for (ResourceGroupListenerList::iterator l = mResourceGroupListenerList.begin();

              l != mResourceGroupListenerList.end(); ++l)

         {

              (*l)->resourceGroupScriptingStarted(groupName, scriptCount);

         }

     }

可以看出，此函数对ResourceGroupListenerList中的每一个元素调用resourceGroupScriptingStarted函数，那么resourceGroupScriptingStarted的具体代码是

     // ResourceGroupListener callbacks

     void resourceGroupScriptingStarted(const String& groupName, size_t scriptCount)

     {

         assert(mNumGroupsInit > 0 && "You stated you were not going to init "

              "any groups, but you did! Divide by zero would follow...");

         // Lets assume script loading is 70%

         mProgressBarInc = mProgressBarMaxSize * mInitProportion / (Real)scriptCount;

         mProgressBarInc /= mNumGroupsInit;

         mLoadingDescriptionElement->setCaption("Parsing scripts...");

         mWindow->update();

     }

这个函数是ResourceGroupListener调用的回调函数，在每一个windowupdate之后，都会增加进度条长度。

第二个函数具体代码是

void ResourceGroupManager::fireResourceGroupScriptingEnded(const String& groupName)

     {

         OGRE_LOCK_AUTO_MUTEX

         for (ResourceGroupListenerList::iterator l = mResourceGroupListenerList.begin();

              l != mResourceGroupListenerList.end(); ++l)

         {

              (*l)->resourceGroupScriptingEnded(groupName);

         }

     }

跟函数1是一个组合，最终对list中的每个元素调用resourceGroupScriptingEnded,其具体代码是

     void resourceGroupScriptingEnded(const String& groupName)

     {

     }

很惊奇这段代码形同虚设，父类中同名函数是纯虚函数，看来这个函数是留作以后扩充用的。

 

函数3的具体代码是

     void ResourceGroupManager::fireScriptStarted(const String& scriptName, bool &skipScript)

     {

         OGRE_LOCK_AUTO_MUTEX

         for (ResourceGroupListenerList::iterator l = mResourceGroupListenerList.begin();

              l != mResourceGroupListenerList.end(); ++l)

         {

              bool temp = false;

              (*l)->scriptParseStarted(scriptName, temp);

              if(temp)

                   skipScript = true;

         }

     }

调用了scriptParseStarted函数，其具体代码是

     void scriptParseStarted(const String& scriptName, bool &skipThisScript)

     {

         mLoadingCommentElement->setCaption(scriptName);

         mWindow->update();

     }

其中定义OverlayElement* mLoadingCommentElement，那么setCaption方法具体做的是

   void OverlayElement::setCaption( const DisplayString& caption )

    {

        mCaption = caption;

        _positionsOutOfDate();

}

设置了一个标题字符串，之后又调用_positionsOutOfDate()，那么它做的是

     void OverlayElement::_positionsOutOfDate(void)

     {

         mGeomPositionsOutOfDate = true;

}

 

 /// Flag indicating if the vertex positions need recalculating

        bool mGeomPositionsOutOfDate;

将OoverlayElement类中的此标记置为true,说明顶点位置需要重新计算。那么整体这个代码段取得了要读脚本的标题，标记顶点位置要更新，之后更新置窗口。

 

函数4的具体代码是

  void ResourceGroupManager::fireScriptEnded(const String& scriptName, bool skipped)

    {

        OGRE_LOCK_AUTO_MUTEX

            for (ResourceGroupListenerList::iterator l = mResourceGroupListenerList.begin();

                l != mResourceGroupListenerList.end(); ++l)

            {

                (*l)->scriptParseEnded(scriptName, skipped);

            }

    }

那么scriptParseEnded的具体代码是

     void scriptParseEnded(const String& scriptName, bool skipped)

     {

         mLoadingBarElement->setWidth(

              mLoadingBarElement->getWidth() + mProgressBarInc);

         mWindow->update();

}

这段代码增加进度条长度，并更新到窗口。

 

函数5的具体代码

/** This event is called when a resource stream has been opened, but not processed yet.

         @remarks

              You may alter the stream if you wish or alter the incoming pointer to point at

              another stream if you wish.

         */

    virtual void resourceStreamOpened(const String &name, const String &group, Resource *resource, DataStreamPtr& dataStream) = 0;

这个方法在ResourceLoadingListener类中被定义为纯虚函数，解释为资源流被打开但是还没有处理的时候来调用它，那么在实例中调用它的类对象是mLoadingListener，是ResourceLoadingListener对象

（怎么会调用了一个纯虚函数。。。汗。。。怀疑是否符合规则），这段先放着了，暂时猜测这样的做法是留出接口，等待将来扩充用

 

下面来看su->parseScript(stream, grp->name)的具体实现，发现su调用的parseScript也是本类ScriptLoader中的纯虚函数,猜测同上.

 

那么到此initialiseResourceGroup函数分析完毕，它主要实现的功能是定位资源。下一篇继续分析createDeclaredResources(grp)。

 

本文来自CSDN博客，转载请标明出处：http://blog.csdn.net/sgao2/archive/2009/07/22/4371344.aspx