e59f8eda74
Add the EmbeddedResourceManager class as well as AbstractEmbeddedResource and two derived concrete classes: RawEmbeddedResource and ZlibEmbeddedResource. The purpose of this is to provide a way for FlightGear to use data from files without relying on FG_ROOT to be set. The whole system (SimGear and FlightGear parts) was described in detail at [1]. I'll probably include a copy in $FG_ROOT/Docs too for fear of the link becoming dead one day. Basically, classes derived from AbstractEmbeddedResource provide access to some data---the source of which is a priori of static storage class---and handle the conversion from whatever format it is stored in to allow convenient use of said data. At the very least, they allow obtaining ready-to-use data as an std::string, as well as reading it incrementally via an std::streambuf or an std::istream interface. ZlibEmbeddedResource instances also provide access to the compressed size of the data (i.e., as stored in static memory) as well as its uncompressed size, without requiring any prior decompression. EmbeddedResourceManager is a class which FlightGear will normally instantiate exactly once---it has createInstance() and instance() static methods for this. It maintains a map between resource paths and instances of concrete classes derived from AbstractEmbeddedResource. It also provides convenience methods allowing to access a resource data in one step (not requiring to manually fetch the AbstractEmbeddedResource-derived object corresponding to the given resource path before calling the appropriate method of this object). From the EmbeddedResourceManager's point of view, resource paths (keys of the map) are just plain std::string instances in the current implementation. However, unless there is a good reason not to, I think it's a good idea to only use values obtained with SGPath::utf8Str()[2]. This is precisely what fgrcc, the resource compiler in the FlightGear repository, does; so, unless you register resources manually, your resource paths will automatically comply with this suggestion. [1] https://sourceforge.net/p/flightgear/mailman/message/35870025/ [2] This allows later addition of methods listing all resources under a given virtual path, as well as optimized resource lookup using a tree-like data structure instead of an std::unordered_map (not justified now IMO).
95 lines
3.9 KiB
C++
95 lines
3.9 KiB
C++
// -*- coding: utf-8 -*-
|
|
//
|
|
// EmbeddedResourceManager_private.hxx --- Private implementation class for
|
|
// SimGear's EmbeddedResourceManager
|
|
// Copyright (C) 2017 Florent Rougon
|
|
//
|
|
// This library is free software; you can redistribute it and/or
|
|
// modify it under the terms of the GNU Library General Public
|
|
// License as published by the Free Software Foundation; either
|
|
// version 2 of the License, or (at your option) any later version.
|
|
//
|
|
// This library is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
// Library General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU Library General Public
|
|
// License along with this library; if not, write to the Free Software
|
|
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
|
|
// MA 02110-1301 USA.
|
|
|
|
#ifndef FG_EMBEDDEDRESOURCEMANAGERPRIVATE_HXX
|
|
#define FG_EMBEDDEDRESOURCEMANAGERPRIVATE_HXX
|
|
|
|
#include <string>
|
|
#include <memory> // std::unique_ptr, std::shared_ptr
|
|
#include <unordered_map>
|
|
#include <vector>
|
|
|
|
#include "EmbeddedResource.hxx"
|
|
|
|
namespace simgear
|
|
{
|
|
|
|
class EmbeddedResourceManager::Impl
|
|
{
|
|
public:
|
|
explicit Impl();
|
|
|
|
// Each “locale” for which addResource() has been used has an associated
|
|
// resource pool, that is a sort of directory of all resources declared in
|
|
// this locale. The resource pool for a given locale (e.g., 'fr' or 'de_DE')
|
|
// maps resource virtual paths to the corresponding resource descriptors
|
|
// (via std::shared_ptr<const AbstractEmbeddedResource> instances).
|
|
//
|
|
// Note: for optimal lookup performance, a tree would probably be better,
|
|
// since the expected use for each key here is to store a virtual
|
|
// path. But such an optimization is likely unneeded in most cases.
|
|
typedef std::unordered_map< std::string,
|
|
std::shared_ptr<const AbstractEmbeddedResource> >
|
|
ResourcePool;
|
|
|
|
// Return the list of “locales” to scan to implement fallback behavior when
|
|
// fetching a resource for the specified locale. This list will be searched
|
|
// from left to right. Examples:
|
|
//
|
|
// "" -> [""]
|
|
// "fr" -> ["fr", ""]
|
|
// "fr_FR" -> ["fr_FR", "fr", ""]
|
|
static std::vector<std::string> localesSearchList(const std::string& locale);
|
|
// Same as localesSearchList(), except it returns the resource pools instead
|
|
// of the “locale” strings, and only those pools that are not empty.
|
|
std::vector< std::shared_ptr<ResourcePool> > listOfResourcePoolsToSearch(
|
|
const std::string& locale) const;
|
|
// Look up, in each of the pools referred to by 'poolSearchList', the
|
|
// resource associated to 'virtualPath'. Return the first match.
|
|
static std::shared_ptr<const AbstractEmbeddedResource> lookupResourceInPools(
|
|
const std::string& virtualPath,
|
|
const std::vector< std::shared_ptr<ResourcePool> >& poolSearchList);
|
|
|
|
// Implement the corresponding EmbeddedResourceManager public methods
|
|
std::string getLocale() const;
|
|
std::string selectLocale(const std::string& locale);
|
|
|
|
// Ditto
|
|
void addResource(const std::string& virtualPath,
|
|
std::unique_ptr<const AbstractEmbeddedResource> resourcePtr,
|
|
const std::string& locale);
|
|
|
|
std::string selectedLocale;
|
|
// After each call to selectLocale(), we update this member to contain
|
|
// precisely the (ordered) list of pools to search for a resource in the
|
|
// selected “locale”. This allows relatively cheap resource lookups,
|
|
// assuming the desired “locale” doesn't change all the time.
|
|
std::vector< std::shared_ptr<ResourcePool> > poolSearchList;
|
|
|
|
// Maps each “locale name” to the corresponding resource pool.
|
|
std::unordered_map< std::string,
|
|
std::shared_ptr<ResourcePool> > localeToResourcePoolMap;
|
|
};
|
|
|
|
} // of namespace simgear
|
|
|
|
#endif // of FG_EMBEDDEDRESOURCEMANAGERPRIVATE_HXX
|