Resource Library

resource files More...

Macros
#define	rsrc_free()   mt_rsrc_free(aes_global)
#define	rsrc_gaddr(a, b, c)   mt_rsrc_gaddr(a,b,c,aes_global)
#define	rsrc_load(a)   mt_rsrc_load(a,aes_global)
#define	rsrc_obfix(a, b)   mt_rsrc_obfix(a,b,aes_global)
#define	rsrc_rcfix(a)   mt_rsrc_rcfix(a,aes_global)
#define	rsrc_saddr(a, b, c)   mt_rsrc_saddr(a,b,c,aes_global)

Functions
short	mt_rsrc_free (short *global_aes)
short	mt_rsrc_gaddr (short Type, short Index, void *Address, short *global_aes)
short	mt_rsrc_load (const char *Name, short *global_aes)
short	mt_rsrc_obfix (OBJECT *, short Index, short *global_aes)
short	mt_rsrc_rcfix (void *rc_header, short *global_aes)
short	mt_rsrc_saddr (short Type, short Index, void *Address, short *global_aes)

Detailed Description

resource files

The Resource Library is responsibe for the loading/unloading of resource files and the manipulation of resource objects in memory.

Macro Definition Documentation

#define rsrc_free

(

)

mt_rsrc_free(aes_global)

single-thread version of mt_rsrc_free()

#define rsrc_gaddr	(		a,
			b,
			c
	)		mt_rsrc_gaddr(a,b,c,aes_global)

single-thread version of mt_rsrc_gaddr()

#define rsrc_load

(

a

)

mt_rsrc_load(a,aes_global)

single-thread version of mt_rsrc_load()

#define rsrc_obfix	(		a,
			b
	)		mt_rsrc_obfix(a,b,aes_global)

single-thread version of mt_rsrc_obfix()

#define rsrc_rcfix

(

a

)

mt_rsrc_rcfix(a,aes_global)

single-thread version of mt_rsrc_rcfix()

#define rsrc_saddr	(		a,
			b,
			c
	)		mt_rsrc_saddr(a,b,c,aes_global)

single-thread version of mt_rsrc_saddr()

Function Documentation

short mt_rsrc_free

(

short *

global_aes

)

releases memory allocated by mt_rsrc_load() for an application's resource.

Parameters

global_aes

global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions.

See also

mt_rsrc_load()

mt_rsrc_free() should be called before an application which loaded a resource using mt_rsrc_load() exits.

short mt_rsrc_gaddr	(	short	Type,
		short	Index,
		void *	Address,
		short *	global_aes
	)

returns the address of an object loaded with mt_rsrc_load().

Parameters

Type	see below
Index	see below
Address	The pointer pointed to by Address will be filled in with the address of the Index -th resource object of type Type. Valid values for Type are: R_TREE R_OBJECT R_TEDINFO R_ICONBLK R_BITBLK R_STRING R_IMAGEDATA R_OBSPEC R_TEPTEXT R_TEPTMPLT R_TEPVALID R_IBPMASK R_IBPDATA R_IBPTEXT R_BIPDATA R_FRSTR R_FRIMG [option CHECK_NULLPTR] Address may be NULL
global_aes	global AES array

Returns

The correct return value is 0 if an error occurred or non-zero if Address is valid.

Since

All AES versions.

See also

mt_rsrc_saddr()

This function is most often used to obtain the address of OBJECT trees (R_TREE), 'free' strings (R_FRSTR), and 'free' images (R_FRIMG) after loading a resource file.

short mt_rsrc_load	(	const char *	Name,
		short *	global_aes
	)

loads and allocates memory for the named resource file.

Parameters

Name	is a character pointer to a NULL-terminated GEMDOS file specification of the resource to load.
global_aes	global AES array

Returns

1 if successful or zero if an error occurred.

Since

All AES versions.

See also

mt_rsrc_free()

In addition to loading the resource, all OBJECT coordinates are converted from character based coordinates to pixels based coordinates.

short mt_rsrc_obfix	(	OBJECT *	Tree,
		short	Index,
		short *	global_aes
	)

converts an object's coordinates from character-based to pixel-based.

Parameters

Tree	specifies the OBJECT tree containing the object...
Index	... to convert.
global_aes	global AES array

Returns

always returns a 0.

Since

All AES versions.

See also

mt_rsrc_load(), mt_rsrc_rcfix()

All objects in '.RSC' files have their coordinates based on character positions rather than screen coordinates to allow an object tree to be shown in any resolution. This function converts those character coordinates to pixel coordinates based on the current screen resolution.

short mt_rsrc_rcfix	(	void *	rc_header,
		short *	global_aes
	)

fixes up coordinates and memory pointers of raw resource data in memory.

Parameters

rc_header	is a pointer to an Atari Resource Construction Set (or compatible) resource file header in memory.
global_aes	global AES array

Returns

0 if unsuccessful or non-zero otherwise.

Since

Available only in AES versions 4.0 and greater. The presence of this call should also be checked for using mt_appl_getinfo() with AES_PROCESS mode.

See also

mt_rsrc_obfix()

If a resource has already been loaded with mt_rsrc_load() it must be freed by mt_rsrc_free() prior to this call. In addition, resources identified with this call must likewise be freed before program termination or another resource file is needed.

short mt_rsrc_saddr	(	short	Type,
		short	Index,
		void *	Address,
		short *	global_aes
	)

sets the address of a resource element.

Parameters

Type	specifies the type of resource element to set as defined under mt_rsrc_gaddr()
Index	specifies the index of the element to modify (0 based)
Address	specifies the actual address that will be placed in the appropriate data structure.
global_aes	global AES array

Returns

0 if an error occurred or non-zero otherwise.

Since

All AES versions.

See also

mt_rsrc_gaddr(), mt_rsrc_load()

Use only Type from 7 to 16 here (that is R_OBSPEC, R_TEPTEXT, R_TEPTMPLT, R_TEPVALID, R_IBPMASK, R_IBPDATA, R_IBPTEXT, R_BIPDATA, R_FRSTR or R_FRIMG ) ! Others destroy a part of the object tree.

In most cases, direct manipulation of the structures involved is quicker and easier than using this call.