8.17 Resource library

This library contains functions to load the resources of a GEM program (menu bars, dialog boxes, icons etc.) into memory and manipulate them there, as well as ascertaining the addresses of the relevant objects. The following routines are available for this purpose:

• rsrc_free	Releases memory occupied by an application's resource
• rsrc_gaddr	Obtains address of an object in a resource data set
• rsrc_load	Loads a resource file
• rsrc_obfix	Converts character-based to pixel-based coordinates
• rsrc_rcfix	Fixes up coordinates and pointers in memory
• rsrc_saddr	Stores address of an object
• sys_recalc_cicon_colours	Passes RGB-triplets in promille for icon conversion in 'direct colour' screen modes

Note: Laying off such objects to a resource file has the invaluable advantage of permitting changes to the appearance (and particularly the language of any text) in a simple way without having to make any modifications to the program itself.

8.17.1 rsrc_free

Name:	»Resource free« - Release memory occupied by a resource file.
Opcode:	111
Syntax:	int16_t rsrc_free ( void );
Description:	The call rsrc_free frees the memory previously occupied by a resource file (allocated by rsrc_load). Note: It is imperative to call this function at the termination of a program!
Return value:	An error has arisen only if the value 0 is returned.
Availability:	All AES versions.
Group:	Resource library
See Also:	Binding rsrc_load

8.17.1.1 Bindings for rsrc_free

int16_t rsrc_free ( void );

Binding:

int16_t rsrc_free (void)
{
   return ( crys_if(111) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	111 # Function opcode
control+2	control[1]	0 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_out	int_out[0]	Return value

8.17.2 rsrc_gaddr

Name:

»Resource get address« - Obtain address of an object in a resource set.

Opcode:

112

Syntax:

int16_t rsrc_gaddr ( int16_t re_gtype, int16_t re_gindex, void *gaddr );

Description:

The call rsrc_gaddr obtains the start addresses of various object structures of resource files loaded into memory with rsrc_load. The following apply:

Parameter

Meaning

re_gtype

Type of structure searched for:

R_TREE	0	=	Object tree
R_OBJECT	1	=	Individual OBJECT
R_TEDINFO	2	=	TEDINFO structure
R_ICONBLK	3	=	ICONBLK structure
R_BITBLK	4	=	BITBLK structure
R_STRING	5	=	Free string data
R_IMAGEDATA	6	=	Free image data
R_OBSPEC	7	=	ob_spec field in OBJECT
R_TEPTEXT	8	=	te_ptext in TEDINFO
R_TEPTMPLT	9	=	te_ptmplt in TEDINFO
R_TEPVALID	10	=	te_pvalid in TEDINFO
R_IBPMASK	11	=	ib_pmask in ICONBLK
R_IBPDATA	12	=	ib_pdata in ICONBLK
R_IBPTEXT	13	=	ib_ptext in ICONBLK
R_BIPDATA	14	=	ib_pdate in BITBLK
R_FRSTR	15	=	ad_frstr free string
R_FRIMG	16	=	ad_frimg free image

re_gindex

Index of the structure searched for

gaddr

Address of the desired structure

Note: If one wants to search for a text pointer within a TEDINFO structure, for instance, then one must not pass the index of the associated object, but the index of the TEDINFO structure. The same applies in essence to other codings.

Return value:

An error has arisen only if the value 0 is returned (= object does not exist).

Availability:

All AES versions.

Group:

Resource library

See Also:

Binding rsrc_load

8.17.2.1 Bindings for rsrc_gaddr

int16_t rsrc_gaddr ( int16_t re_gtype, int16_t re_gindex, void *gaddr );

Binding:

int16_t rsrc_gaddr (int16_t re_gtype, int16_t re_gindex,
                    void *gaddr)
{
   int_in[0]  = re_gtype;
   int_in[1]  = re_gindex;
   control[4] = 1;

   crys_if (112);

   control[4] = 0;
   *gaddr = addr_out[0];

   return ( int_out[0] );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	112 # Function opcode
control+2	control[1]	2 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	1 # Entry in addr_out
int_in	int_in[0]	re_gtype
int_in+2	int_in[1]	re_gindex
int_out	int_out[0]	Return value
addr_out	addr_out[0]	gaddr

8.17.3 rsrc_load

Name:	»Resource load« - Loads a specified resource file into memory.
Opcode:	110
Syntax:	int16_t rsrc_load ( CONST int8_t *re_lpfname );
Description:	The call rsrc_load serves for loading a resource file and initializing it (allocating memory); furthermore, all OBJECT coordinates are converted from character-based coordinates to screen coordinates. The parameter re_lpfname contains the NULL-terminated filename of the resource file to load. Note: The file will be looked for in all directories that the AES knows about. As of PC-GEM Version 2.0, incidentally, all object trees that have a box as a root (e.g. all dialog boxes) will have the SHADOWED flag set for it in ob_state. This means that all dialog boxes will be drawn with a shadow instead of an outline frame. The origin of this lies in the legal disputes between Apple and Digital Research. However, the SHADOWED bit can be reset (after rsrc_load) at run-rime and the normal OUTLINED bit set once more. Warning: Conversion of bit-images and icons from the standard format to the device-specific format does not occur at this stage. If required, this must be perfomed by the programmer himself. MagiC as of Version 3 and Geneva can load resources in the Interface format. With other AESs this possibility can be checked with appl_getinfo (opcode 2).
Return value:	An error has arisen only if the value 0 is returned.
Availability:	All AES versions.
Group:	Resource library
See Also:	Binding rsrc_free shel_find vr_trnfm

8.17.3.1 Bindings for rsrc_load

int16_t rsrc_load ( CONST int8_t *re_lpfname );

Binding:

int16_t rsrc_load (CONST int8_t *re_lpfname)
{
   addr_in[0] = re_lpfname;
   return ( crys_if(110) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	110 # Function opcode
control+2	control[1]	0 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	1 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
addr_in	addr_in[0]	re_lpfname
int_out	int_out[0]	Return value

8.17.4 rsrc_obfix

Name:

»Resource object fix« - Convert an object's coordinates from character-based to pixel-based.

Opcode:

114

Syntax:

int16_t rsrc_obfix ( OBJECT *re_otree, int16_t re_oobject );

Description:

The call rsrc_obfix converts the size and position of a displayed object from character-based to pixel-based coordinates at the current screen resolution. (This is required because all objects in RSC files have their coordinates based on character positions rather than screen coordinates to ensure correct display of trees and objects at any screen resolution.) The following apply:

Parameter	Meaning

re_otree	Address of the relevant object tree
re_oobject	Index of the object to convert

Note: A call of this function is always required if objects are created at run-time, or are not loaded with rsrc_load.

The conversion is performed by multiplying the lower byte of the coordinate specification with the size of a character from the system font, and then adding the (signed) upper byte. Exception: For a width of exactly 80 characters, the width of the screen is substituted; this is used for the background object of the menu tree for instance.

Return value:

This always has the value 1.

Availability:

All AES versions.

Group:

Resource library

See Also:

Binding rsrc_load rsrc_rcfix

8.17.4.1 Bindings for rsrc_obfix

int16_t rsrc_obfix ( OBJECT *re_otree, int16_t re_oobject );

Binding:

int16_t rsrc_obfix (OBJECT *re_otree, int16_t re_oobject)
{
   int_in[0]  = re_oobject;
   addr_in[0] = re_otree;

   return ( crys_if(114) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	114 # Function opcode
control+2	control[1]	1 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	1 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	re_oobject
addr_in	addr_in[0]	re_otree
int_out	int_out[0]	Return value

8.17.5 rsrc_rcfix

Name:

»Resource coordinate fix« - Fix up coordinates and pointers in memory.

Opcode:

115

Syntax:

int16_t rsrc_rcfix ( RSHDR *rc_header );

Description:

The function rsrc_rcfix, present in MagiC and MultiTOS, fixes up resource data already loaded into memory by the application. During this the coordinates are converted from character- to pixel-coordinates.

If an application has already loaded an RSC file before the function is called, then it must be released with rsrc_free before the rsrc_rcfix call is made. The same applies at the termination of the application.

The advantage of this function consists in the ability of incorporating the resource file of the program into the program code itself. It then suffices to just call rsrc_rcfix, and loading with rsrc_load can then be dispensed with. The following applies:

rc_header:

Address of the RSC header in memory; the RSC data must lie after this

Return value:

This will be 0 if unsuccessful, else non-zero.

Availability:

Available only in MagiC and AES versions 4.0 and greater. The presence of this call should also be checked for using appl_getinfo (Opcode 4).

Group:

Resource library

See Also:

Binding rsrc_load rsrc_obfix

8.17.5.1 Bindings for rsrc_rcfix

int16_t rsrc_rcfix ( RSHDR *rc_header );

Binding:

int16_t rsrc_rcfix ( RSHDR *rc_header )
{
   addr_in[0] = rc_header;
   return ( crys_if(115) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	115 # Function opcode
control+2	control[1]	0 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	1 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
addr_in	addr_in[0]	rc_header
int_out	int_out[0]	Return value

8.17.6 rsrc_saddr

Name:

Resource store address« - Store address of an object.

Opcode:

113

Syntax:

int16_t rsrc_saddr ( int16_t re_stype, int16_t re_sindex, void *saddr );

Description:

The call rsrc_saddr stores the start address of a data structure in memory. The following apply:

Parameter

Meaning

re_stype

Type of structure:

R_TREE	0	=	Object tree
R_OBJECT	1	=	Individual OBJECT
R_TEDINFO	2	=	TEDINFO structure
R_ICONBLK	3	=	ICONBLK structure
R_BITBLK	4	=	BITBLK structure
R_STRING	5	=	Free string data
R_IMAGEDATA	6	=	Free image data
R_OBSPEC	7	=	ob_spec field in OBJECT
R_TEPTEXT	8	=	te_ptext in TEDINFO
R_TEPTMPLT	9	=	te_ptmplt in TEDINFO
R_TEPVALID	10	=	te_pvalid in TEDINFO
R_IBPMASK	11	=	ib_pmask in ICONBLK
R_IBPDATA	12	=	ib_pdata in ICONBLK
R_IBPTEXT	13	=	ib_ptext in ICONBLK
R_BIPDATA	14	=	ib_pdata in BITBLK
R_FRSTR	15	=	ad_frstr free string
R_FRIMG	16	=	ad_frimg free image

re_sindex

Position within the data structure

saddr

Address to be saved in data structure

Return value:

An error has arisen only if the value 0 is returned.

Availability:

All AES versions.

Group:

Resource library

See Also:

Binding rsrc_gaddr OBJECT

8.17.6.1 Bindings for rsrc_saddr

int16_t rsrc_saddr ( int16_t re_stype, int16_t re_sindex, void *saddr );

Binding:

int16_t rsrc_saddr (int16_t re_stype, int16_t re_sindex,
                    void *saddr)
{
   int_in[0]  = re_stype;
   int_in[1]  = re_sindex;
   addr_in[0] = saddr;

   return ( crys_if(113) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	113 # Function opcode
control+2	control[1]	2 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	1 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	re_stype
int_in+2	int_in[1]	re_sindex
addr_in	addr_in[0]	saddr
int_out	int_out[0]	Return value

8.17.7 sys_recalc_cicon_colours

Name:	???
Opcode:	0
Syntax:	void sys_recalc_cicon_colours( uint16_t colour_values[3256] );
Description:	Pass RGB-triplets in promille (1/1000th) for the icon conversion with 'direct colour' screen modes. Only used from MagxDesk.
Return value:	unknown.
Availability:	As of MagiC 5.20 from 20.11.97
Group:	Resource library
See Also:	Binding

8.17.7.1 Bindings for sys_recalc_cicon_colours

void *sys_recalc_cicon_colours( uint16_t colour_values[3*256] );

Binding:

void *sys_recalc_cicon_colours( uint16_t colour_values[3*256] );
{
   int_in[0]  = 5;
   addr_in[0] = colour_values;

   crys_if(0);
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	0 # Function opcode
control+2	control[1]	0 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	1 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	5
addr_in	addr_in[0]	colour_values