Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support

Apple IIgs
#76:    Miscellaneous Resource Formats

Revised by:     Matt Deatherage & Dave Lyons                     January 1991
Written by:     C.K. Haun, Llew Roberts & Dave Lyons             January 1990

This Technical Note describes resource structure formats for
previously-unpublished types.
Changes since May 1990:  Added information for rVersion and rComment resources.
Changed "ID" to "Type" in all the headings because that's what we really meant.
_____________________________________________________________________________

The format used to describe the resources is similar to that used in File Type
Notes, where the offsets, given in the form (+xxx), determine the offset from
the beginning of the resource.


Sampled Sound Resource (Type: $8024)

The following describes the Sampled Sound resource format.  It consists of a
ten-byte header followed by the sample data bytes.

    Format         (+000)    Word     This must always be zero.
    Wave Size      (+002)    Word     Sample size in pages (256 bytes per
page).  For example, an 8K sample takes
32 pages; a 128K sample requires $200
pages.
    Rel Pitch      (+004)    Word     The high byte of this word is a
semitone value; the low byte is a
fractional semitone.  These values are
used to tune the sample to correct
pitch.
    Stereo         (+006)    Word     The output channel for this sound is in
the low nibble of this word.
    Sample rate    (+008)    Word     The sampling rate of the sound, in
Hertz (Hz).
    Sound          (+010)    Bytes    The sampled sound data.  The bytes are
all 8-bit samples.  The sample starts
here and continues until the end of the
resource.

The resource compiler template is as follows:

#define rSoundSample    $8024

/*---------------------- rSoundSample --------------------*/
type rSoundSample {
    integer;        /* format */
    integer;        /* wave size */
    integer;        /* rel pitch */
    integer;        /* stereo channel */
    integer;        /* sample rate */
    wide array {
      hex byte;     /* raw 8 bit sound data */
    };
};

Cursor Resource (Type: $8027)

The following describes the Cursor resource format:

    height    (+000)    Word      The height of the cursor, in pixels.
    width     (+002)    Word      The width of the cursor, in Words.
    image     (+004)    Bytes     The image of the cursor.  There are
height*width Words in the cursor, or
                                  twice that many Bytes.

We will call the first byte beyond the image offset "ei" for "end of image."

    mask      (+ei)     Bytes     The mask of the cursor.  This is the
same size as the image.

We will call the first byte beyond the mask offset "em" for "end of mask."

    hotSpotY  (+em)     Word      The cursor's Y "hot spot."
    hotSpotX  (+em+2)   Word      The cursor's X "hot spot."
    flags     (+em+4)   Flag Word Cursor flags:
                                  Bit 7: 1 = 640 Mode, 0 = 320 Mode
                                  All other bits are reserved and must
be zero.
    reserved  (+em+6)   8 Bytes   Reserved, must be zero.

The resource compiler template is as follows:

#define rCursor $8027

/*---------------------- rCursor --------------------*/
type rCursor {
    height :
        hex integer;            /* height */
    width :
        hex integer;            /* width in words */
        hex string[2*$$Word(height)*$$Word(width)];    /* cursor image */
        hex string[2*$$Word(height)*$$Word(width)];    /* cursor mask */
        hex integer;            /* hotspot X */
        hex integer;            /* hotspot Y */
        hex integer;            /* flags */
        hex longint = 0;        /* reserved */
        hex longint = 0;        /* reserved */
    };
};

Following is a simple cursor example:

resource rCursor(1,fixed) {
        5,     /* height */
        2,     /* width */
        $"ffff0000"
        $"f00f0000"
        $"f00f0000"
        $"f00f0000"
        $"ffff0000",

        $"ffff0000"
        $"ffff0000"
        $"ffff0000"
        $"ffff0000"
        $"ffff0000",

        2,     /* hotspot Y */
        2,     /* hotspot X */
        $80    /* 640 mode */
};

Note that the resource is marked fixed so that its handle can be dereferenced
and passed to SetCursor.


Version Resource (Type: $8029)

Files may include a version resource with ID=1 for display by programs such as
the Finder.  The following describes the version resource format:

        version (+000)  Long    The application's version number, in Apple IIgs
Long Version format.  See Apple IIgs Technical Note #100, VersionVille, for
more details.
        reserved        (+004)  Word    Store zero here.
        name    (+006)  String  Pascal string containing the desired name.  May
be the null string.
        moreInfo        (+xxx)  String  Additional information to be displayed,
such as a copyright notice.  May be the null string.

The resource compiler template is as follows:

#define rVersion        $8029

/*---------------------- rVersion --------------------*/
type rVersion {
    longint;                    /* Apple IIgs Long Version */
    word;                       /* reserved two bytes */
    pstring;                    /* the application's name */
    pstring;                    /* the copyright notice */
};

Following is a simple version example for "Super Graphics Destroyer", version
2.0:

resource rVersion(1) {
        $0200A000,                              /* the version 2.0 */
        0,                                      /* reserved */
        "Super Graphics Destroyer",             /* our app's name */
        "c 1991 Pretty as a Picture, Inc."      /* the copyright notice */
}

Comment Resource (Type: $802A)

Files may include a comment resource with ID=1 for display by programs such as
the Finder.  The following describes the comment resource format:

        text    (+000)  Bytes   The comment.  This is unformatted, 8-bit text
suitable for displaying by a desktop program.  No length limit is imposed by
this resource format, although a practical limit of a few hundred characters is
recommended.

The resource compiler template is as follows:

#define rComment        $802A

/*---------------------- rComment --------------------*/
type rComment {
    string;
};


Rectangle List Resource (Type:  $C001)

The rectangle list (type rRectList) is provided to allow an extensible, easily
modifiable collection of QuickDraw II rectangle structures.  This capability
can enhance a developer's ability to modify on-screen displays without
recompiling an entire application.  This resource also enables easier
cross-development and parallel development for the Apple IIgs and the
Macintosh.

The following describes the rectangle list resource format:

    count   (+000)  Word    Number of rectangles in this resource.
    firstRectangle  (+002)  8 Bytes First QuickDraw II rectangle structure.
    ...                     Rectangles, eight bytes each.
    lastRectangle   (+002+(8*(count-1)))
                8 Bytes Last QuickDraw II rectangle structure.

The resource compiler template is as follows:

#define rRectList    $C001
type rRectList {
        integer = $$Countof(RectArray);
        array RectArray {
            Rect;
            };
};


_____________________________________________________________________________
Further Reference
  o  Apple IIgs Toolbox Reference, Volumes 2 & 3
  o  Apple IIgs Technical Note #100, VersionVille

