Ogre 的文档系统

    ogre里面的文档系统,他不存在真正的文件,他只是存储的是这些文件的名称和文件的目录信息.者一切的开始是从

ArchiveManager 这个类开始的,

    ArchiveManager这个类是一个文件的容器管理者,他管理者所有的文件信息,(这些信息包含这个文件的名称,全路径,目录,大小等信息,这些东西是在FileInfo这个结构体中定义的)在ArchiveManager 中有ArchiveFactoryMap类型的变量他用来管理这着所有的创建容器的工厂.还有一个ArchiveMap类型的变量他用来装载成所有的文档容器,他的成员函数如下,我给出了所有的申明,并加了中文的注释

    /** This class manages the available ArchiveFactory plugins.
    */
 //!文档管理者这个类主要是用来管理所有可以用到的文档,和文档的工厂,
 //!工厂和文档的关系就是:工厂制造一个文档,同时他保存这个文档的指针,
 //!同时文档管理者也会管理这些文档.工厂和文档都是抽象的,需要自己去实现
 //!具体的工厂类型和文档的类型,然后有管理者统一的管理.
    class _OgreExport ArchiveManager : public Singleton<ArchiveManager>
    {
    protected:
  //!ArchiveFactoryMap 这个类型的容器的定义,第一用来指定这个工厂是用来生产什么类型的容器
  //!第二个是具体的文件工厂的指针.
        typedef std::map<String, ArchiveFactory*> ArchiveFactoryMap;
        /// Factories available to create archives, indexed by archive type (String identifier e.g. 'Zip')
        ArchiveFactoryMap mArchFactories;
        /// Currently loaded archives
        typedef std::map<String, Archive*> ArchiveMap;
        ArchiveMap mArchives;   //!同时这个管理者还要自己来管理生产出来的东西.

    public:
        /** Default constructor - should never get called by a client app.
        */
        ArchiveManager() {}
        /** Default destructor.
        */
        virtual ~ArchiveManager();

        /** Opens an archive for file reading.
            @remarks
                The archives are created using class factories within
                extension libraries.
            @param filename
                The filename that will be opened
            @param refLibrary
                The library that contains the data-handling code
            @returns
                If the function succeeds, a valid pointer to an Archive
                object is returened.
            @par
                If the function fails, an exception is thrown.
        */
        Archive* load( const String& filename, const String& archiveType);

  /** Unloads an archive.
  @remarks
   You must ensure that this archive is not being used before removing it.
  */
  void unload(Archive* arch);
  /** Unloads an archive by name.
  @remarks
   You must ensure that this archive is not being used before removing it.
  */
  void unload(const String& filename);

        /** Adds a new ArchiveFactory to the list of available factories.
            @remarks
                Plugin developers who add new archive codecs need to call
                this after defining their ArchiveFactory subclass and
                Archive subclasses for their archive type.
        */
        void addArchiveFactory(ArchiveFactory* factory);
        /** Override standard Singleton retrieval.
        @remarks
        Why do we do this? Well, it's because the Singleton
        implementation is in a .h file, which means it gets compiled
        into anybody who includes it. This is needed for the
        Singleton template to work, but we actually only want it
        compiled into the implementation of the class based on the
        Singleton, not all of them. If we don't change this, we get
        link errors when trying to use the Singleton-based class from
        an outside dll.
        @par
        This method just delegates to the template version anyway,
        but the implementation stays in this single compilation unit,
        preventing link errors.
        */
        static ArchiveManager& getSingleton(void);
        /** Override standard Singleton retrieval.
        @remarks
        Why do we do this? Well, it's because the Singleton
        implementation is in a .h file, which means it gets compiled
        into anybody who includes it. This is needed for the
        Singleton template to work, but we actually only want it
        compiled into the implementation of the class based on the
        Singleton, not all of them. If we don't change this, we get
        link errors when trying to use the Singleton-based class from
        an outside dll.
        @par
        This method just delegates to the template version anyway,
        but the implementation stays in this single compilation unit,
        preventing link errors.
        */
        static ArchiveManager* getSingletonPtr(void);
    };

接下来要说的是ArchiveFactory这个类

他是一个纯虚的类,他继承FactoryObj< Archive >这个类,他里面没有什么的东西,FactoryObj是一个工厂的模板,可以根据自己的需要去生产出什么,但是首先需要去实现他的接口,.他就可以生产出一个特定类型的容器,

    /** Abstract factory class. Does nothing by itself, but derived classes can add
        functionality.
    */
 //!这个是一个工厂的模板,可以这样通俗的说,这个工厂可以根据你自己的实现来生产出不同的东西.
    template< typename T > class FactoryObj
    {
    public:
        virtual ~FactoryObj() {};

        /** Returns the factory type.
            @return
                The factory type.
        */
  //!得到这个工厂生产东西的类型.
        virtual const String& getType() const = 0;

        /** Creates a new object.
        @param name Name of the object to create
        @return
            An object created by the factory. The type of the object depends on
            the factory.
        */
  //!根据一个类型的字符串来产生一个东西.
        virtual T* createInstance( const String& name ) = 0;   
        /** Destroys an object which was created by this factory.
        @param ptr Pointer to the object to destroy
        */
  //!删除这个东西,这个东西由参数提供.
        virtual void destroyInstance( T* ) = 0;   
    };

最后要说的一个是容器类Archive

这个类是一个文档的容器,可以这样去想,我们平时的档案会被放到一个很打的袋子里面,很多人的文档都装在里面,那么以后就可以通过这个文档里面来查找某个人和某些人的信息,档案有很多不同的类型,你是当官的不可能和老百姓的放在一起把,所以就分开了不同的类型,同时你也可能会给这个档案袋分配一个名称,你可以/对这个档案袋进行各种不同的操作,他的函数的申明和注释:

//!这个是一个文件的容器类.这个类只是用来包含这些文件的名称和目录信息.
    class _OgreExport Archive 
    {
    protected:
        /// Archive name
        String mName;   //@这个容器的名称.
        /// Archive type code
        String mType;   //!这个容器存储什么类型的的文件
    public:

        /** Constructor - don't call direct, used by ArchiveFactory.
        */
        Archive( const String& name, const String& archType )
            : mName(name), mType(archType) {}

        /** Default destructor.
        */
        virtual ~Archive() {}

  /// Get the name of this archive
  const String& getName(void) const { return mName; }

  //!这个是用来控制在匹配文档的名称的时候是否区分大小写.
        /// Returns whether this archive is case sensitive  it matches files
        virtual bool isCaseSensitive(void) const = 0;

        /** Loads the archive.
        @remarks
            This initializes all the internal data of the class.
        @warning
            Do not call this function directly, it is ment to be used
            only by the ArchiveManager class.
        */
  //!加载一个文档的文件.
        virtual void load() = 0;

        /** Unloads the archive.
        @warning
            Do not call this function directly, it is ment to be used
            only by the ArchiveManager class.
        */
  //!卸载一个文档文件.
        virtual void unload() = 0;

        /** Open a stream on a given file.
        @note
            There is no equivalent 'close' method; the returned stream
            controls the lifecycle of this file operation.
        @param filename The fully qualified name of the file
        @returns A shared pointer to a DataStream which can be used to
            read / write the file. If the file is not present, returns a null
   shared pointer.
        */
  //!这个函数是用来根据参数提供的那个文件的名称(全路径)来打开指定的那个文件
  //!如果这个文件存在且打开成功那么就把这个文件的指针通过DataStreamPtr的形式返回回去
  //!你可以对这个文件进行读写的操作.他是一个智能的指针,因此他可以自己孔子自己的生命周期.
        virtual DataStreamPtr open(const String& filename) const = 0;

        /** List all file names in the archive.
        @note
            This method only returns filenames, you can also retrieve other
            information using listFileInfo.
        @param recursive Whether all paths of the archive are searched (if the
            archive has a concept of that)
        @param dirs Set to true if you want the directories to be listed
            instead of files
        @returns A list of filenames matching the criteria, all are fully qualified
        */
  //!这个函数是用来列举出这个文件的容器里面的所有的文件.只是列出这些文件的名称
  //!如果要得到这个文件的其他的信息,就需要调用下面的listFileInfo函数.
        virtual StringVectorPtr list(bool recursive = true, bool dirs = false/*是否包含目录信息*/) = 0;
       
        /** List all files in the archive with accompanying information.
        @param recursive Whether all paths of the archive are searched (if the
            archive has a concept of that)
        @param dirs Set to true if you want the directories to be listed
            instead of files
        @returns A list of structures detailing quite a lot of information about
            all the files in the archive.
        */
        virtual FileInfoListPtr listFileInfo(bool recursive = true, bool dirs = false) = 0;

        /** Find all file or directory names matching a given pattern
            in this archive.
        @note
            This method only returns filenames, you can also retrieve other
            information using findFileInfo.
        @param pattern The pattern to search for; wildcards (*) are allowed
        @param recursive Whether all paths of the archive are searched (if the
            archive has a concept of that)
        @param dirs Set to true if you want the directories to be listed
            instead of files
        @returns A list of filenames matching the criteria, all are fully qualified
        */
  //!这个函数是用来查找包含参数1提供的字符串的文件和目录名称,并且把这些文件名称
  //!组合成一个字符串数组进行返回.
        virtual StringVectorPtr find(const String& pattern, bool recursive = true,
            bool dirs = false) = 0;

        /** Find out if the named file exists (note: fully qualified filename required) */
  //!根据文件名称来查看这个文件是否存在,参数必须提供一个全路径名称.
        virtual bool exists(const String& filename) = 0;

        /** Find all files or directories matching a given pattern in this
            archive and get some detailed information about them.
        @param pattern The pattern to search for; wildcards (*) are allowed
        @param recursive Whether all paths of the archive are searched (if the
        archive has a concept of that)
        @param dirs Set to true if you want the directories to be listed
            instead of files
        @returns A list of file information structures for all files matching
            the criteria.
        */
  //!这个是用来查找与参数1指定的那个字符串相同的文件名称或者路径名称,并且组成一个
  //!字符串数组得到返回
        virtual FileInfoListPtr findFileInfo(const String& pattern,
            bool recursive = true, bool dirs = false) = 0;

        /// Return the type code of this Archive
  //!得到表示这个容器的类型的字符串.
        const String& getType(void) const { return mType; }
       
    };