What the Blorb Layer Does

What the Blorb Layer Does — The platform-independent functions in the Blorb layer

Functions

Types and Values

Includes

#include <libchimara/glk.h>
#include <libchimara/gi-blorb.h>

Description

These are the functions which are implemented in gi_blorb.c. They will be compiled into the library, but they are the same on every platform. In general, only the library needs to call these functions. The Glk program should allow the library to do all the resource handling.

Functions

giblorb_create_map ()

giblorb_err_t
giblorb_create_map (strid_t file,
                    giblorb_map_t **newmap);

Reads Blorb data out of a Glk stream. It does not load every resource at once; instead, it creates a map in memory which makes it easy to find resources. A pointer to the map is stored in newmap . This is an opaque object; you pass it to the other Blorb-layer functions.

Parameters

file

An input stream pointing to a Blorb file.

 

newmap

Return location for a Blorb resource map.

 

Returns

a Blorb error code.


giblorb_destroy_map ()

giblorb_err_t
giblorb_destroy_map (giblorb_map_t *map);

Deallocates map and all associated memory. This does not close the original stream.

Parameters

map

A Blorb resource map to deallocate.

 

Returns

a Blorb error code.


giblorb_load_chunk_by_type ()

giblorb_err_t
giblorb_load_chunk_by_type (giblorb_map_t *map,
                            glui32 method,
                            giblorb_result_t *res,
                            glui32 chunktype,
                            glui32 count);

Loads a chunk of a given type. The count parameter distinguishes between chunks of the same type. If count is zero, the first chunk of that type is loaded, and so on.

To load a chunk of an IFF FORM type (such as AIFF), you should pass in the form type, rather than FORM.

This introduces a slight ambiguity — you cannot distiguish between a FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is almost certainly a mistake.

The returned data is written into res , according to method .

The chunknum field is filled in with the number of the chunk. (This value can then be passed to giblorb_load_chunk_by_number() or giblorb_unload_chunk().) The length field is filled in with the length of the chunk in bytes. The chunktype field is the chunk's type, which of course will be the type you asked for.

If you specify giblorb_method_DontLoad, no data is actually loaded in. You can use this if you are only interested in whether a chunk exists, or in the chunknum and length parameters.

If you specify giblorb_method_FilePos, data.startpos is filled in with the file position of the chunk data. You can use glk_stream_set_position() to read the data from the stream.

If you specify giblorb_method_Memory, data.ptr is filled with a pointer to allocated memory containing the chunk data. This memory is owned by the map, not you. If you load the chunk more than once with giblorb_method_Memory, the Blorb layer is smart enough to keep just one copy in memory. You should not deallocate this memory yourself; call giblorb_unload_chunk() instead.

Parameters

map

The Blorb resource map to load a chunk from.

 

method

The loading method to use, one of giblorb_method_DontLoad, giblorb_method_Memory, or giblorb_method_FilePos.

 

res

Return location for the result.

 

chunktype

The type of chunk to load.

 

count

The chunk number of type chunktype to load.

 

Returns

a Blorb error code.


giblorb_load_chunk_by_number ()

giblorb_err_t
giblorb_load_chunk_by_number (giblorb_map_t *map,
                              glui32 method,
                              giblorb_result_t *res,
                              glui32 chunknum);

This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a given chunk number. The type of the chunk can be found in the chunktype field of giblorb_result_t. You can get the chunk number from the chunknum field, after calling one of the other load functions.

Parameters

map

The Blorb resource map to load a chunk from.

 

method

The loading method to use, one of giblorb_method_DontLoad, giblorb_method_Memory, or giblorb_method_FilePos.

 

res

Return location for the result.

 

chunknum

The chunk number to load.

 

Returns

a Blorb error code.


giblorb_unload_chunk ()

giblorb_err_t
giblorb_unload_chunk (giblorb_map_t *map,
                      glui32 chunknum);

Frees the chunk data allocated by giblorb_method_Memory. If the given chunk has never been loaded into memory, this has no effect.

Parameters

map

The Blorb resource map to unload a chunk from.

 

chunknum

The chunk number to unload.

 

Returns

a Blorb error code.


giblorb_load_resource ()

giblorb_err_t
giblorb_load_resource (giblorb_map_t *map,
                       glui32 method,
                       giblorb_result_t *res,
                       glui32 usage,
                       glui32 resnum);

Loads a resource, given its usage and resource number. Currently, the three usage values are giblorb_ID_Pict (images), giblorb_ID_Snd (sounds), and giblorb_ID_Exec (executable program). See the Blorb specification for more information about the types of data that can be stored for these usages.

Note that a resource number is not the same as a chunk number. The resource number is the sound or image number specified by a Glk program. Chunk number is arbitrary, since chunks in a Blorb file can be in any order. To find the chunk number of a given resource, call giblorb_load_resource() and look in res.chunknum.

Parameters

map

The Blorb resource map to load a resource from.

 

method

The loading method to use, one of giblorb_method_DontLoad, giblorb_method_Memory, or giblorb_method_FilePos.

 

res

Return location for the result.

 

usage

The type of data resource to load.

 

resnum

The resource number to load.

 

Returns

a Blorb error code.


giblorb_count_resources ()

giblorb_err_t
giblorb_count_resources (giblorb_map_t *map,
                         glui32 usage,
                         glui32 *num,
                         glui32 *min,
                         glui32 *max);

Counts the number of chunks with a given usage (image, sound, or executable.) The total number of chunks of that usage is stored in num . The lowest and highest resource number of that usage are stored in min and max . You can leave any of the three pointers NULL if you don't care about that information.

Parameters

map

The Blorb resource map in which to count the resources.

 

usage

The type of data resource to count.

 

num

Return location for the number of chunks of usage .

 

min

Return location for the lowest resource number of usage .

 

max

Return location for the highest resource number of usage .

 

Returns

a Blorb error code.

Types and Values

giblorb_result_t

typedef struct {
    glui32 chunknum; /* The chunk number (for use in

        giblorb_unload_chunk(), etc.) */
    union {
        void *ptr; /* A pointer to the data (if you used

            giblorb_method_Memory) */
        glui32 startpos; /* The position in the file (if you

            used giblorb_method_FilePos) */
    } data;
    glui32 length; /* The length of the data */
    glui32 chunktype; /* The type of the chunk. */
} giblorb_result_t;

Holds information about a chunk loaded from a Blorb file, and the method of accessing the chunk data. data is a union of ptr , a pointer to the data (if you used giblorb_method_Memory) and startpos , the position in the file (if you used giblorb_method_FilePos). See giblorb_load_chunk_by_type() and giblorb_load_chunk_by_number().

Members

glui32 chunknum;

The chunk number (for use in giblorb_unload_chunk(), etc.)

 

glui32 length;

The length of the data

 

glui32 chunktype;

The type of the chunk.

 

giblorb_method_DontLoad

#define giblorb_method_DontLoad (0)

Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or giblorb_load_resource() to obtain information about a chunk without actually loading it.


giblorb_method_Memory

#define giblorb_method_Memory (1)

Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or giblorb_load_resource() to load a chunk into memory.


giblorb_method_FilePos

#define giblorb_method_FilePos (2)

Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or giblorb_load_resource() to get the position in the Blorb file at which the chunk data starts.


giblorb_ID_Exec

#define giblorb_ID_Exec      (giblorb_make_id('E', 'x', 'e', 'c'))

Resource usage constant representing an executable program.


giblorb_ID_Snd

#define giblorb_ID_Snd       (giblorb_make_id('S', 'n', 'd', ' '))

Resource usage constant representing a sound file.


giblorb_ID_Pict

#define giblorb_ID_Pict      (giblorb_make_id('P', 'i', 'c', 't'))

Resource usage constant representing an image file.


giblorb_ID_Data

#define giblorb_ID_Data      (giblorb_make_id('D', 'a', 't', 'a'))

Resource usage constant representing a data file.


giblorb_ID_Copyright

#define giblorb_ID_Copyright (giblorb_make_id('(', 'c', ')', ' '))

Resource usage constant representing the copyright message (date and holder, without the actual copyright symbol). There should only be one such chunk per file.


giblorb_ID_AUTH

#define giblorb_ID_AUTH      (giblorb_make_id('A', 'U', 'T', 'H'))

Resource usage constant representing the name of the author or creator of the file. This could be a login name on multi-user systems, for example. There should only be one such chunk per file.


giblorb_ID_ANNO

#define giblorb_ID_ANNO      (giblorb_make_id('A', 'N', 'N', 'O'))

Resource usage constant representing any textual annotation that the user or writing program sees fit to include.


giblorb_ID_TEXT

#define giblorb_ID_TEXT      (giblorb_make_id('T', 'E', 'X', 'T'))

Resource usage constant representing a text data file.


giblorb_ID_BINA

#define giblorb_ID_BINA      (giblorb_make_id('B', 'I', 'N', 'A'))

Resource usage constant representing a binary data file.