00001 /*! \file 00002 * X-Forge Util <br> 00003 * Copyright 2000-2003 Fathammer Ltd 00004 * 00005 * $Id: XFuConfigurationData.h,v 1.17 2003/08/12 13:33:52 lars Exp $ 00006 * $Date: 2003/08/12 13:33:52 $ 00007 * $Revision: 1.17 $ 00008 */ 00009 00010 #ifndef XFUCONFIGURATIONDATA_H_INCLUDED 00011 #define XFUCONFIGURATIONDATA_H_INCLUDED 00012 00013 00014 #include <xfutil/XFuConfiguration.h> 00015 00016 class XFcGLResourceSurface; 00017 class XFuPrinter; 00018 00019 00020 //! Defines audio info flags for configuration data audio properties. 00021 /*! Audio properties' audio info flags determine which optional fields 00022 * have been filled with data read from the configuration data file. 00023 */ 00024 enum XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS 00025 { 00026 XFUCDAIF_NONE = 0x00, //!< No optional fields present. 00027 XFUCDAIF_SAMPLING_RATE = 0x01, //!< Sampling rate field. 00028 XFUCDAIF_VOLUME = 0x02, //!< Volume field. 00029 XFUCDAIF_PANNING = 0x04, //!< Panning field. 00030 XFUCDAIF_PRIORITY = 0x08, //!< Priority field. 00031 XFUCDAIF_LOOPING = 0x10, //!< Looping field. 00032 XFUCDAIF_LOOPSTART = 0x20, //!< Loop start field. 00033 XFUCDAIF_LOOPEND = 0x40, //!< Loop end field. 00034 }; 00035 00036 00037 //! Sound sample configuration data type. 00038 /*! \sa XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS 00039 */ 00040 class XFuConfigurationDataSoundInfo 00041 { 00042 00043 public: 00044 00045 CHAR *mFilename; //!< Filename of the sound sample. 00046 FLOAT32 mSamplingRate; //!< Sampling rate. 00047 REAL mVolume; //!< Volume (1.0=original volume). 00048 REAL mPanning; //!< Panning [0..1]. 00049 UINT16 mPriority; //!< Priority. 00050 INT mLooping; //!< Non-zero if the sample is looping. 00051 INT32 mLoopStart; //!< Loop start point. 00052 INT32 mLoopEnd; //!< Loop end point. 00053 UINT32 mFlags; //!< Flags, see XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS. 00054 00055 XFuConfigurationDataSoundInfo() : 00056 mFilename(NULL), mSamplingRate(0.0f), mVolume(REALi(0)), mPanning(REALi(0)), 00057 mPriority(0), mLooping(0), mLoopStart(0), mLoopEnd(0), mFlags(0) {} 00058 00059 virtual ~XFuConfigurationDataSoundInfo() 00060 { 00061 delete[] mFilename; 00062 mFilename = NULL; 00063 } 00064 00065 }; 00066 00067 00068 //! Music configuration data type. 00069 /*! \sa XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS 00070 */ 00071 class XFuConfigurationDataMusicInfo 00072 { 00073 00074 public: 00075 00076 CHAR *mFilename; //!< Filename of the sound sample. 00077 FLOAT32 mSamplingRate; //!< Sampling rate. 00078 INT m16Bit; //!< Non-zero if 16 bit mixing requested, otherwise 8 bit. 00079 INT mStereo; //!< Non-zero if stereo requested, otherwise mono. 00080 REAL mVolume; //!< Volume (1.0=original volume). 00081 UINT16 mPriority; //!< Priority. 00082 UINT32 mFlags; //!< Flags, see XFUCONFIGURATIONDATA_AUDIO_INFO_FLAGS. 00083 00084 XFuConfigurationDataMusicInfo() : 00085 mFilename(NULL), mSamplingRate(0.0f), m16Bit(0), mStereo(0), 00086 mVolume(REALi(0)), mPriority(0), mFlags(0) {} 00087 00088 virtual ~XFuConfigurationDataMusicInfo() 00089 { 00090 delete[] mFilename; 00091 mFilename = NULL; 00092 } 00093 00094 }; 00095 00096 00097 //! Configured data container. 00098 /*! 00099 * Reads and parses a set of configuration data keys from a file. 00100 * The format of the configuration file is such that there is one property 00101 * on each row in a text file. Each property is a pair of a key and a value, 00102 * delimited by a '=' char, for example: 00103 * \code fileName = HelloWorld.xff \endcode 00104 * 00105 * Optionally the key can also have a type prefix which is delimited from the 00106 * rest of the key with a ':' (colon) char, for example: 00107 * \code image : cursor = arrow.tga \endcode 00108 * Recognized builtin types are parsed when the configuration file is processed. 00109 * For some types the data is also loaded at the same time. Note that for 00110 * recognized types the key is reformatted to use the short form before adding 00111 * to the data container, which affects only fetching of data with regular 00112 * get-method instead of a type specific getType-style method. If multiple keys 00113 * refer to exact same value which results in loading of a resource, the 00114 * resource is loaded only once so that the same loaded resource is shared 00115 * between the keys. 00116 * 00117 * Builtin types have getType-style methods which can be used to read the 00118 * data easily by the key omitting the type prefix. Builtin types also have 00119 * both long and short forms of the type, so the previous example could be 00120 * also written: 00121 * \code i:cursor = arrow.tga \endcode 00122 * 00123 * Leading and trailing spaces are trimmed. Lines starting with character '#' 00124 * are treated as comment lines and are ignored. Optional parts of 00125 * value strings can be omitted. 00126 * 00127 * Recognized builtin types: 00128 * <table><tr> 00129 * <th>Long Type<th>Short<br>Type<th>Value String Format and Description 00130 * 00131 * <tr><td>\c image <td>\c i 00132 * <td>Value string: <tt>filename,type</tt> 00133 * \li filename - filename of image which is loaded as a XFcGLResourceSurface 00134 * when the configuration file is processed. 00135 * \li type - optional image format as a number (see XFCGFXFORMAT). 00136 * 00137 * Example: 00138 * \code 00139 * image:menu.cursor = arrow.tga 00140 * i:splash = splash.tga \endcode 00141 * 00142 * <tr><td>\c printer <td>\c p 00143 * <td>Value string: <tt>filename,spacing,type,colorkey</tt> 00144 * \li filename - filename where to load the printer font image from. 00145 * \li spacing - default spacing for the printer. 00146 * \li type - 0:standard printer (XFuPrinter), 1:RLE sprite printer (XFuRLESpritePrinter). 00147 * \li colorkey - optional color key, hex strings can be used with 0x or # prefix. 00148 * 00149 * Example: 00150 * \code 00151 * printer:menu.printer = smallfont.tga,0,1,#0000ff 00152 * p:digitprinter = digits.tga,2,0 \endcode 00153 * 00154 * <tr><td>\c sound <td>\c s 00155 * <td>Value string: <tt>filename,samplingrate,volume,panning,priority,looping,loopstart,loopend</tt> 00156 * \li filename - filename of a sound sample. 00157 * \li samplingrate - optional sampling rate as a real number (-1 = default). 00158 * \li volume - optional volume as a real number (1.0 = original volume, -1 = default). 00159 * \li panning - optional panning as a real number [0..1] (-1 = default). 00160 * \li priority - optional priority as an integer [0..65535] (-1 = default). 00161 * \li looping - optional looping flag, 0:no looping, 1:looping. 00162 * \li loopstart - optional loop start point as an integer. 00163 * \li loopend - optional loop end point as an integer. 00164 * 00165 * Example: 00166 * \code 00167 * sound:menu.select = menuselect.wav 00168 * s:menu.move = menumove.wav,-1,0.5 \endcode 00169 * 00170 * <tr><td>\c music <td>\c m 00171 * <td>Value string: <tt>filename,samplingrate,chanmode,bitmode,volume,priority</tt> 00172 * \li filename - filename of the music data. 00173 * \li samplingrate - sampling rate for mixing the music as a real number. 00174 * \li chanmode - channel mode, 0:mono, 1:stereo. 00175 * \li bitmode - bits to use, 0:8 bits, 1:16 bits. 00176 * \li volume - optional volume as a real number (1.0 = original volume, -1 = default). 00177 * \li priority - optional priority as an integer [0..65535]. 00178 * 00179 * Example: 00180 * \code 00181 * music:menumusic = menu.xm,16000,0,0,0.3,0 00182 * music:gamemusic = game.xm,8000,0,0,0.15,0 \endcode 00183 * 00184 * </table> 00185 * 00186 * \note XFuConfigurationData object owns all objects it has loaded, so you shouldn't 00187 * delete manually any objects you access via this class. 00188 * \todo Type handler registration interface. 00189 * 00190 * \sa getImage 00191 * \sa XFcGLResourceSurface 00192 * \sa getPrinter 00193 * \sa XFuPrinter 00194 * \sa XFuRLESpritePrinter 00195 * \sa getRectangle 00196 * \sa XFcRectangle 00197 * \sa getSound 00198 * \sa XFuConfigurationDataSoundInfo 00199 * \sa getMusic 00200 * \sa XFuConfigurationDataMusicInfo 00201 * \sa XFuConfiguration 00202 * \sa XFcAudio 00203 */ 00204 class XFuConfigurationData : public XFuConfiguration 00205 { 00206 00207 public: 00208 00209 //! Static constructor. 00210 /*! \return new configuration data object if successful, or NULL if unsuccessful. 00211 */ 00212 static XFuConfigurationData * create(); 00213 00214 //! Static constructor. 00215 /*! \param aFilename filename of configuration data to load. 00216 * \return new configuration data object if successful, or NULL if unsuccessful. 00217 */ 00218 static XFuConfigurationData * create(const CHAR *aFilename); 00219 00220 //! Static constructor. 00221 /*! \param aFile open file pointing to configuration data to load. 00222 * \return new configuration data object if successful, or NULL if unsuccessful. 00223 * \note Configuration data is assumed to continue to end of the file. 00224 */ 00225 static XFuConfigurationData * create(XFcFile *aFile); 00226 00227 //! Virtual destructor. 00228 virtual ~XFuConfigurationData(); 00229 00230 //! Returns the value of a property as a string, or NULL if not found. 00231 /*! \param aKey key of the property to return. 00232 */ 00233 virtual CHAR * get(const CHAR *aKey); 00234 00235 //! Returns a configuration data image by key, or NULL if not found. 00236 /*! \param aKey key of the image omitting the type prefix and delimiter. 00237 * \return pointer to the image surface, or NULL if not found. 00238 */ 00239 virtual XFcGLResourceSurface * getImage(const CHAR *aKey); 00240 00241 //! Returns a configuration data printer by key, or NULL if not found. 00242 /*! \param aKey key of the printer omitting the type prefix and delimiter. 00243 * \return pointer to the printer, or NULL if not found. 00244 */ 00245 virtual XFuPrinter * getPrinter(const CHAR *aKey); 00246 00247 //! Returns a configuration data sound info by key, or NULL if not found. 00248 /*! \param aKey key of the sound omitting the type prefix and delimiter. 00249 * \return pointer to sound info, or NULL if not found. 00250 */ 00251 virtual XFuConfigurationDataSoundInfo * getSound(const CHAR *aKey); 00252 00253 //! Returns a configuration data music info by key, or NULL if not found. 00254 /*! \param aKey key of the music omitting the type prefix and delimiter. 00255 * \return pointer to music info, or NULL if not found. 00256 */ 00257 virtual XFuConfigurationDataMusicInfo * getMusic(const CHAR *aKey); 00258 00259 //! Gets a property value by key, and then parses and returns the value as a rectangle. 00260 /*! 00261 * Rectangle value string format: <tt>x,y,width,height</tt>. 00262 * \li x - X-component of the rectangle as an integer. 00263 * \li y - optional Y-component of the rectangle as an integer. 00264 * \li width - optional width of the rectangle as an integer. 00265 * \li height - optional height of the rectangle as an integer. 00266 * 00267 * Example: 00268 * \code 00269 * rectangle:laptime.position = 10,10 00270 * r:viewport = 4,4,160,120 \endcode 00271 * 00272 * \param aDest returned rectangle, if successful. 00273 * \param aKey key of the property value to be parsed. 00274 * \return 1 if successful (rectangle was found), or 0 if unsuccessful. 00275 */ 00276 virtual INT getRectangle(XFcRectangle &aDest, const CHAR *aKey); 00277 00278 //! Sets the value of a property. 00279 /*! If the key contains a type prefix delimited by ':' character from the 00280 * rest of the key, and the type is a recognized builtin type, the value 00281 * is parsed and possibly loaded according to the type. Properties with 00282 * recognized builtin types can be accessed with type specific 00283 * getType-style method. If the possible type prefix is unrecognized then 00284 * the value must be accessed with get-method. 00285 * \param aKey full key of the property to set value for. 00286 * \param aValue value of the property. 00287 */ 00288 virtual void put(const CHAR *aKey, const CHAR *aValue); 00289 00290 //! Loads new configuration file and merges its data to the current set. 00291 /*! \param aFilename filename of the configuration data file to load. 00292 * \return 1 if successful, 0 if unsuccessful (e.g. file not found). 00293 */ 00294 virtual INT load(const CHAR *aFilename); 00295 00296 //! Loads new configuration file and merges its data to the current set. 00297 /*! \param aFile open file pointing to the configuration data to load. 00298 * \return 1 if successful, 0 if unsuccessful (e.g. file not found). 00299 * \note Configuration data is assumed to continue to end of the file. 00300 */ 00301 virtual INT load(XFcFile *aFile); 00302 00303 //! Parses a rectangle value string. 00304 /*! \return rectangle filled with available values, or an empty rectangle (0,0,0,0) if unsuccessful. 00305 */ 00306 static XFcRectangle parseRectangleString(const CHAR *aValue); 00307 00308 //! Sets deferred loading mode status. 00309 /*! When deferred loading mode is enabled, all recognized object types held 00310 * by this configuration data container are loaded only when an object is 00311 * requested for the first time. By default deferred loading is disabled 00312 * and all recognized types are loaded on load of a configuration file. 00313 * Deferred loading must be enabled before calling load. 00314 */ 00315 void setDeferredLoadingEnabled(INT aEnabled); 00316 00317 protected: 00318 00319 //! Internal image container type. 00320 /*! \internal */ 00321 typedef XFcHashtable<XFuStringKey, XFcGLResourceSurface *> ImageSet; 00322 //! Internal printer container type. 00323 /*! \internal */ 00324 typedef XFcHashtable<XFuStringKey, XFuPrinter *> PrinterSet; 00325 //! Internal sound info container type. 00326 /*! \internal */ 00327 typedef XFcHashtable<XFuStringKey, XFuConfigurationDataSoundInfo *> SoundSet; 00328 //! Internal music info container type. 00329 /*! \internal */ 00330 typedef XFcHashtable<XFuStringKey, XFuConfigurationDataMusicInfo *> MusicSet; 00331 00332 //! Protected constructor. 00333 XFuConfigurationData(); 00334 00335 //! Initializes a newly constructed object. 00336 /*! \return 1 if successful, 0 if unsuccessful. 00337 */ 00338 INT init(); 00339 00340 //! Adds and possibly loads a new image to the internal image container. 00341 void addImage(const CHAR *aValue); 00342 //! Adds and possibly loads a new printer to the internal printer container. 00343 void addPrinter(const CHAR *aValue); 00344 //! Adds a new sound to the internal sound container. 00345 void addSound(const CHAR *aValue); 00346 //! Adds a new music to the internal music container. 00347 void addMusic(const CHAR *aValue); 00348 00349 //! Loads a new image to the internal image container. 00350 void loadImage(ImageSet::iterator &aIterator); 00351 //! Loads a new printer to the internal printer container. 00352 void loadPrinter(PrinterSet::iterator &aIterator); 00353 00354 //! Allocates and returns a new key with a specified prefix char. 00355 CHAR * makePrefixedKey(const CHAR aPrefix, const CHAR *aKey); 00356 00357 //! Non-zero if deferred loading is enabled. 00358 INT mDeferredLoadingEnabled; 00359 00360 ImageSet *mImages; //!< Internal image container. 00361 PrinterSet *mPrinters; //!< Internal printer container. 00362 SoundSet *mSounds; //!< Internal sound container. 00363 MusicSet *mMusics; //!< Internal music container. 00364 00365 }; 00366 00367 00368 #endif // !XFUCONFIGURATIONDATA_H_INCLUDED 00369
![]() | ||||
![]() |
Confidential Copyright © 2002-2003 Fathammer | with doxygen by Dimitri van Heesch |