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-File
                               userblk


G_PROGDEF objects allow programmers to define custom objects and link
them transparently in the resource. The ob_spec field of G_PROGDEF objects
contains a pointer to an APPLBLK (USERBLK) as defined below:

typedef struct appl_blk
{
    WORD        (*ab_code)(PARMBLK *);
    LONG        ab_parm;
} APPLBLK;

ab_code is a pointer to a user-defined routine which will draw the
object. The routine will be passed a pointer to a PARMBLK structure
containing the information it needs to render the object. The routine must
be defined with stack checking off and expect to be passed its parameter
on the stack. ab_parm is a user-defined value which is copied into the
PARMBLK structure as defined below:

typedef struct parm_blk
{
    OBJECT      *tree;
    WORD        pb_obj;
    WORD        pb_prevstate;
    WORD        pb_currstate;
    WORD        pb_x;
    WORD        pb_y;
    WORD        pb_w;
    WORD        pb_h;
    WORD        pb_xc;
    WORD        pb_yc;
    WORD        pb_wc;
    WORD        pb_hc;
    LONG        pb_parm;
} PARMBLK;

tree points to the OBJECT tree of the object being drawn. The object is
located at index pb_obj.

The routine is passed the old ob_state of the object in pb_prevstate and
the new ob_state of the object in pb_currstate. If pb_prevstate and
pb_currstate is equal then the object should be drawn completely,
otherwise only the drawing necessary to redraw the object from
pb_prevstate to pb_currstate are necessary.

pb_x, pb_y, pb_w, and pb_h give the screen coordinates of the object.
pb_xc, pb_yc, pb_wc, and pb_hc give the rectangle to clip to. pb_parm
contains a copy of the ap_parm value in the APPLBLK structure.

The custom routine should return a WORD containing any remaining ob_state
bits you wish the AES to draw over your custom object.

Because the drawing routing will be called from the context of the AES,
using the stack heavily or defining many local variables is not
recommended.