Top |
What the Blorb Layer DoesWhat the Blorb Layer Does — The platform-independent functions in the Blorb layer |
giblorb_result_t | |
#define | giblorb_method_DontLoad |
#define | giblorb_method_Memory |
#define | giblorb_method_FilePos |
#define | giblorb_ID_Exec |
#define | giblorb_ID_Snd |
#define | giblorb_ID_Pict |
#define | giblorb_ID_Data |
#define | giblorb_ID_Copyright |
#define | giblorb_ID_AUTH |
#define | giblorb_ID_ANNO |
#define | giblorb_ID_TEXT |
#define | giblorb_ID_BINA |
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.
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.
giblorb_err_t
giblorb_destroy_map (giblorb_map_t *map
);
Deallocates map
and all associated memory. This does
not close the original stream.
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.
map |
The Blorb resource map to load a chunk from. |
|
method |
The loading method to use, one of |
|
res |
Return location for the result. |
|
chunktype |
The type of chunk to load. |
|
count |
The chunk number of type |
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.
map |
The Blorb resource map to load a chunk from. |
|
method |
The loading method to use, one of |
|
res |
Return location for the result. |
|
chunknum |
The chunk number to load. |
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.
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
.
map |
The Blorb resource map to load a resource from. |
|
method |
The loading method to use, one of |
|
res |
Return location for the result. |
|
usage |
The type of data resource to load. |
|
resnum |
The resource number to load. |
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.
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()
.
glui32 |
The chunk number (for use in |
|
glui32 |
The length of the data |
|
glui32 |
The type of the chunk. |
#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.
#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.
#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.
#define giblorb_ID_Exec (giblorb_make_id('E', 'x', 'e', 'c'))
Resource usage constant representing an executable program.
#define giblorb_ID_Snd (giblorb_make_id('S', 'n', 'd', ' '))
Resource usage constant representing a sound file.
#define giblorb_ID_Pict (giblorb_make_id('P', 'i', 'c', 't'))
Resource usage constant representing an image file.
#define giblorb_ID_Data (giblorb_make_id('D', 'a', 't', 'a'))
Resource usage constant representing a data file.
#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.
#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.
#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.
#define giblorb_ID_TEXT (giblorb_make_id('T', 'E', 'X', 'T'))
Resource usage constant representing a text data file.