SourceForge project page
Web Links


Example 1

Let's say, your game is using following, rather standard looking config file, and you want to parse it using SDL_Config:


   screen_size_x = 640
   screen_size_y = 480

   fullscreen = false

Code which you would use to parse this file with SDL_Config could look like this:

  CFG_File config;

  if ( CFG_OK != CFG_OpenFile("config_file.cfg", &config ) )
     // error ...
  if ( CFG_OK == CFG_SelectGroup("Video", 0) )
    Sint32 screen_size_x = CFG_ReadInt("screen_size_x", 640);
    Sint32 screen_size_y = CFG_ReadInt("screen_size_y", 480);

    bool fullscreen = CFG_ReadBool("fullscreen", true);

    // use them


First, there goes the definition of object of class CFG_File, which will be responsible for storing informations about our config file's data. What's important, is that you don't need to initialize / deinitialize library in any way.

In next line we open and parse config file with name "config_file.cfg" (what extension you use is up to you) using function CFG_OpenFile(). It returns number, which indicates whether everything went ok, or were there any errors. Obviously, if returned number equals CFG_ERROR or CFG_CRITICAL_ERROR, then error occured and you have to deal with it in a way specific to your project :-) You may use function CFG_GetError to obtain textual description in english of what has happened.

Next we select group "Video", so that all following operations will be performed only on it. As you see, this function also returns number which indicates whether any errors occured etc.

After selecting group, we read the values that we are interested in. CFG_ReadInt takes as its first parameter name of entry and the second one, is default value, which will be returned when such entry wasn't found. It returns value from found entry (or default one). Pretty simple, right? :-) The same logic applies to CFG_ReadBool, CFG_ReadFloat and CFG_ReadText, the only thing which changes is type of second parameter and returned value's type (to bool, float and const char *).

As you probably suspect, CFG_CloseFile(0) closes currently selected file. If you would like to close other file than currently selected, you would pass to this function pointer to it instead of 0.

That's all, file has been parsed. Is this easy or what? ;-)

Example 2

Let's say that your config file can have an arbitrary number of groups, so you can't made any assumptions when parsing it, ie.


  File which holds the information about levels used by game.
  Group names ("Level_1" etc.) have no meaning



   name = "Blood bath"
   model = "bloodbath.md3"

   name = "Bloob bath"
   model = "bloobbath.md3"


   name = "Boob bath"
   model = "boobbath.md3"

   // etc.

Iteration over sections in SDL_Config is very easy:

  CFG_File config;

  int result = CFG_OpenFile("config_file.cfg", &config );

  // typical error detection code etc.

  for ( CFG_StartGroupIteration(); !CFG_IsLastGroup(); CFG_SelectNextGroup() )
    std :: string name = CFG_ReadText("name", "");
    std :: string model = CFG_ReadText("model", "");


And that's it, for() will loop over all groups in file (except for global group) selecting them one after another (in original or alphabethical order). You can call all Read/Write functions and as usual, they'll operate on that currently selected group. If you don't like the need to postfix group names with numbers in order to make them unique, and want to have all groups with the same name yet be able to operate on them, defining CFG_USE_MULTIMAP allows for it.

Example 3

Multi value entries are one of the extensions of ini format introduced by SDL_Config. They're really useful in real world. For example, let's say that you want to store list of quotes that AI opponent might scream in battle. Here's how you can do it:


    name = "Kane"
    health = 540
    texture = "Textures/kane.png"
    weapon = "machine_gun"
    battle_quotes =  "Burn baby!", "We've found a witch!", "I'm gonna boil you alive", "Get over here"

How to handle above cfg file? Let's say that this time we'lll be using SDL_Config's C++ interface:

  ConfigFile config("opponents.cfg");

  if (!config.IsOpen())
   return "error"; // deal with error


  for ( config.StartMultiValueEntryIteration("battle_quotes"); !config.IsLastMultiValueEntry(); config.SelectNextMultiValueEntry() )
   std::string quote = config.ReadText(CFG_MULTI_VALUE_ENTRY_ITERATION, 0);
   // that's it!

Posted by Koshmaar on December 31 2005 16:10:496346 Reads - Print


Forgotten your password?
Request a new one here.
Banners Logo

Get Firefox!

Copyright © Hubert "Koshmaar" Rutkowski 2005