Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-FileRSHDR

                            The .RSC File Format


Resource files contain application specific data which is generally
loaded at run-time. RSC files contain OBJECT trees (see the discussion of
the OBJECT structure in Chapter 6: AES ), strings, and images.

Two resource file formats are currently supported. TOS versions less than
4.0 support the original RSC format while TOS 4.0 and greater will now
support the older format and a new extensible format. The original format
will be discussed first followed by an explanation of the changes incurred
by the newer format.

The RSC Header (see RSHDR structure)

Resource files begin with an 18 WORD header as follows:

WORD    Field Name   Contents

  0     rsh_vrsn     Contains the version number of the resource file.
                     This value is 0x0000 or 0x0001 in old format RSC
                     files and has the third bit set (i.e. 0x0004) in the
                     new file format.

  1     rsh_object   Contains an offset from the beginning of the file to
                     the OBJECT structures.

  2     rsh_tedinfo  Contains an offset from the beginning of the file to
                     the TEDINFO structures.

  3     rsh_iconblk  Contains an offset from the beginning of the file to
                     the ICONBLK structures.

  4     rsh_bitblk   Contains an offset from the beginning of the file to
                     the BITBLK structures.

  5     rsh_frstr    Contains an offset from the beginning of the file to
                     the string pointer table.

  6     rsh_string   Contains an offset from the beginning of the file to
                     the string data.

  7     rsh_imdata   Contains an offset from the beginning of the file to
                     the image data.

  8     rsh_frimg    Contains an offset from the beginning of the file to
                     the image pointer table.

  9     rsh_trindex  Contains an offset from the beginning of the file to
                     the tree pointer table.

 10     rsh_nobs     Number of OBJECTs in the file.

 11     rsh_ntree    Number of object trees in the file.

 12     rsh_nted     Number of TEDINFOs in the file.

 13     rsh_nib      Number of ICONBLKs in the file.

 14     rsh_nbb      Number of BITBLKs in the file.

 15     rsh_nstring  Number of free strings in the file.

 16     rsh_nimages  Number of free images in the file.

 17     rsh_rssize   Size of the resource file (in bytes). Note that this
                     is the size of the old format resource file. If the
                     newer format file is being used then this value can
                     be used as an offset to the extension array.

Many of the header entries represent offsets from the beginning of the
file. These offsets are expressed as positive unsigned WORDs making the
standard file a maximum size of 64k bytes.
Object Trees

Each RSC file may contain a number of object trees. rsh_object contains
an offset from the beginning of the file to the object trees (stored
consecutively). The LONG array pointed to by rsh_trindex can be used to
separate the object trees in the list. There are rsh_ntree LONGs in this
array. Each array entry can be used as an array index to a different
object tree. After being loaded in memory by rsrc_load(), the members at
rsh_trindex are filled in with the absolute pointers to their respective
trees.

Each individual OBJECT is stored differently on disk then in memory. In
the file, pointers to TEDINFOs, BITBLKs, and ICONBLKs are stored as
absolute indexes into the arrays of these members stored in the file.
Therefore a G_TEXT OBJECT whose ob_spec field would normally point
a TEDINFO in memory would contain the value 0 if that TEDINFO were the
first TEDINFO contained in the file.

String pointers are represented on disk by their absolute offset from the
beginning of the file. Image pointers in BITBLK and ICONBLK structures are
likewise pointed to through absolute file offsets, not indexes.

Free Strings and Images

rsh_frstr points to a table of LONGs which each specify an offset from
the start of the RSC file to a free string. rsh_frimg points to a table of
LONGs which each specify an offset from the start of the file to a BITBLK
structure.

AES 3.30 Resource Format

Beginning with AES 3.30, the resource file format was altered to allow
for new OBJECT types. The only OBJECT which currently takes advantage of
this format is G_CICON. G_CICONs can only be stored in files of the new
format. The new format can be identified by the third bit of rsh_vrsn
being set.

The Extension Array

Immediately following the old resource data (using rsh_rssize as an
offset) an extension array is added. The first entry in this array is
a LONG containing the true size of the RSC file. Notice that values such
as these are now stored as LONGs to allow the size of RSC files to exceed
64k. Due to the method in which some older resource elements were stored
many components of RSC files will still be constrained to 64k.

Following the file size is a LONG word for each extension present
followed by a 0L which terminates the array. Currently only one extension
exists (CICONBLK) and it always occupies the first extension slot. As
additional extensions are added, a value of -1L for any entry will
indicate that there are no resource elements of that type in the file. For
example an extension array that does contain CICONBLKs would look like
this.

           ...basic resource file...

           LONG filesize

           LONG cicon_offset

           0L

The CICONBLK Extension

The G_CICON object type adds the ability to display color icons from the
AES. The ob_spec of the object indexes a CICONBLK structure stored in the
extension area. Each CICONBLK must contain a monochrome icon and a color
icon for as many different resolutions as desired. When drawn, the AES
will pick the icon that is the closest match for the current screen
display. If there is no color icon present which the AES is able to
convert, the monochrome icon is displayed.

The cicon_offset pointer gives an offset from the beginning of the
resource file to a file segment which contains the CICON data. This
segment contains a CICONBLK pointer table followed by the actual

CICONBLKs.

The CICONBLK pointer table is simply a longword 0L for each CICONBLK
present in the file. These pointers are filled in by the AES when loaded.
The list is terminated by a -1L.
Immediately following the pointer table is one of the following variable
length structures for each CICONBLK:

ICONBLK monoicon;       /* This is the standard monochrome resource. */
LONG n_cicons;          /* Number of CICONs of different resolutions. */
WORD mono_data[x];      /* Monochrome bitmap data. */
WORD mono_mask[x];      /* Monochrome bitmap mask. */
CHAR icon_text[12];     /* Icon text (maximum of 12 characters). */
/* for each resolution supported (n_cicons) include the following structure */

WORD num_planes;        /* Number of planes this icon was intended for */
LONG col_data;          /* Placeholder (calculated upon loading). */
LONG col_mask;          /* Placeholder (calculated upon loading). */
LONG sel_data;          /* Placeholder (must be non-zero if 'selected' data exists */
LONG sel_mask;          /* Placeholder (calculated upon loadind). */
LONG next_res;          /* 1L = more icons follow */
WORD color_data[n];     /* n WORDs of image data (n is num_planes*WORDs in mono icon).*/
WORD color_mask[n];     /* n WORDs of image mask. */
WORD select_data[n];    /* Only present if sel_data is non-zero. */
WORD select_mask[n];    /* Only present if sel_data is non-zero. */

CICON Images

All color image data is stored in VDI device independent format on disk
and is automatically converted by vr_trnfm() upon rsrc_load().