Re: [AD] Indexed datafiles

[Elias Pschernig <elias@xxxxxxxxxx>]

On Thu, 2005-12-22 at 16:01 +0100, Elias Pschernig wrote:
> On Thu, 2005-12-22 at 13:20 +0100, Hrvoje Ban wrote:
> > 4.2 is out, so I'm posting my load_datafile_object_indexed patch
> > again.
> 
> Thanks. I'll apply it (to 4.3) if nobody objects.

Ok, done. Attached is a patch to update examples and docs accordingly.

-- 
Elias Pschernig

Index: examples/exdata.c
===================================================================
--- examples/exdata.c	(revision 5577)
+++ examples/exdata.c	(working copy)
@@ -48,12 +48,6 @@
       return 1;
    }
 
-   /* select the palette which was loaded from the datafile */
-   set_palette(datafile[THE_PALETTE].dat);
-
-   /* aha, set a palette and let Allegro convert colors when blitting */
-   set_color_conversion(COLORCONV_TOTAL);
-   
    /* display the bitmap from the datafile */
    textout_ex(screen, font, "This is the bitmap:", 32, 16,
 	      makecol(255, 255, 255), -1);
@@ -68,6 +62,23 @@
    /* unload the datafile when we are finished with it */
    unload_datafile(datafile);
 
+   /* Demonstrate how to speed up loading a single object with an index */
+   DATAFILE_INDEX *index = create_datafile_index("example.dat");
+   DATAFILE *palette_object = load_datafile_object_indexed(index, THE_PALETTE);
+   DATAFILE *font_object = load_datafile_object_indexed(index, BIG_FONT);
+
+   /* select the palette which was loaded from the datafile */
+   set_palette(palette_object->dat);
+
+   textout_ex(screen, font_object->dat, "..now with the right palette!",
+	      16, 160, makecol(0, 255, 0), -1);
+
+   readkey();
+
+   /* Clean up */
+   unload_datafile_object(palette_object);
+   destroy_datafile_index(index);
+
    return 0;
 }
 
Index: docs/src/allegro._tx
===================================================================
--- docs/src/allegro._tx	(revision 5577)
+++ docs/src/allegro._tx	(working copy)
@@ -10859,6 +10859,7 @@
 
 @@void @unload_datafile_object(DATAFILE *dat);
 @xref load_datafile_object
+@eref exdata
 @shortdesc Frees an object previously loaded by load_datafile_object().
    Frees an object previously loaded by load_datafile_object(). Use this to
    avoid memory leaks in your program.
@@ -10882,6 +10883,43 @@
    Returns a pointer to a single DATAFILE element whose `dat' member points to
    the object, or NULL if the object could not be found.
 
+@\DATAFILE_INDEX *@create_datafile_index(const char *filename);
+@xref destroy_datafile_index, load_datafile_object_indexed
+@xref Using datafiles
+@eref exdata
+@shortdesc Creates an index for a datafile.
+   Creates an index for a datafile, to speed up loading single objects out of
+   it. This is mostly useful for big datafiles, which you don't want to load as
+   a whole. The index will store the offset of all objects inside the dataile,
+   and then you can load it quickly with "load_datafile_object_indexed" later.
+   Use destroy_datafile_index to free the memory used by it again.
+   Example:
+<codeblock>
+   DATAFILE_INDEX *index = create_datafile_index("huge.dat");
+   DATAFILE *object = load_datafile_object_indexed(index, 1234);
+   ...
+   unload_datafile_object(object);
+   destroy_datafile_index(index);<endblock>
+@retval
+   A pointer value which you can pass to load_datafile_object_indexed.
+
+@@DATAFILE *@load_datafile_object_indexed(const DATAFILE_INDEX *index, int item)
+@xref create_datafile_index, load_datafile_object, unload_datafile_object
+@eref exdata
+@shortdesc Loads a single object from a datafile index.
+   This loads a single object, using the index created previously with
+   create_datafile_index. See create_datafile_index for an example.
+@retval
+   Returns a pointer to a single DATAFILE element whose "dat" member points to
+   the object, or NULL if the object could not be loaded.
+
+@@void @destroy_datafile_index(DATAFILE_INDEX *index)
+@xref create_datafile_index
+@eref exdata
+@shortdesc Destroys a datafile index.
+   This function frees the memory used by a datafile index created with
+   create_datafile_index earlier.
+
 @@const char *@get_datafile_property(const DATAFILE *dat, int type);
 @xref Using datafiles, DAT_ID, empty_string
 @shortdesc Returns the property string for the object.
@@ -15138,9 +15176,11 @@
 
 @@Example @exdata
 @xref DATAFILE, END_OF_MAIN, allegro_error, allegro_init, allegro_message
-@domain.hid blit, font, install_keyboard, load_datafile, makecol, readkey
-@domain.hid replace_filename, screen, set_color_conversion, set_gfx_mode
-@domain.hid set_palette, textout_ex, unload_datafile
+@xref blit, create_datafile_index, destroy_datafile_index, font
+@xref install_keyboard, load_datafile, load_datafile_object_indexed
+@xref makecol, readkey, replace_filename, screen, set_color_conversion
+@xref set_gfx_mode, set_palette, textout_ex, unload_datafile
+@xref unload_datafile_object
 @shortdesc Accessing the contents of datafiles.
    This program demonstrates how to access the contents of an
    Allegro datafile (created by the grabber utility). The example