HomeAESObject libraryShell library

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.

See also: About the AES   Style guidelines

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

C: 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

C: 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

C: 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

C: 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

C: 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

C: 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 (sub-opcode 5)
Syntax: void *sys_recalc_cicon_colours( uint16_t colour_values[3*256] );
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

C: 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;               /* Subcode 5: */
   addr_in[0] = colour_values;

   crys_if(0);
}
GEM-Arrays:

Address Element Contents
control control[0] 0 # Function opcode
control+2 control[1] 1 # Entry in int_in
control+4 control[2] 0 # 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

HomeAESObject libraryShell library