VgaGames4

VgaGames4 - object man-pages

[.. upper level ..]

# vg4->object->create()

Create an object-instance.

SYNTAX
struct VG_Object * vg4->object->create(const char *objid, int subid, unsigned int parent_instanceid, int drawlevel, void *opriv)
FUNCTION PARAMETERS

objid | Object-ID (e.g. name of object)
subid | Arbitrary sub-ID for object-ID, or 0 = no sub-ID
parent_instanceid | Instance-ID of parent, or 0 = irrelevant
drawlevel | Level-number for drawing order (begins with 1 = lowest level)
opriv | Private struct for object-instance

RETURN VALUE
Returns created object-instance
DESCRIPTION
Create an object-instance. From the object objid a new instance will be created. The subid may be used to sub-classify this instance. If the object-instance is related to a parent-instance, parent_instanceid should be set. This calls the function f_childexit() of the parent-instance, if exists, when this object-instance is destroyed, to inform the parent, that the child was gone. The drawlevel indicates the order of drawing when the function f_draw() is called for all object-instances. At first all object-instances of drawlevel=1 will be drawn, then all of drawlevel=2 and so on. opriv is the private structure of the object-instance holding its variables, e.g. position, healthiness ... The functions of the returned object-instance must be set individually. Not all functions must exist, their values may remain NULL: - f_free() is used to destroy the private struct of the object-instance will be called from vg4->object->destroy() - f_run() is used to move the object-instance will be called from vg4->object->call_run() - f_draw() is used to draw the object-instance will be called from vg4->object->call_draw() - f_data() is used to exchange data of the object-instance will be called from vg4->object->call_data() The instance-ID for this object-instance will be set automatically. Instance-IDs are always unique over all object-instances.
EXAMPLE

    obj-otest.c

    /* object "OTEST" */
    #define OBJID "OTEST"

    /* private structure */
    struct s_objvars {
      int posx, posy;
      struct VG_Image *imgp;
    };

    unsigned int new_OTEST(int, int);

    static void f_free(void *, void *);
    static VG_BOOL f_run(void *, struct VG_Object *);
    static void f_draw(void *, struct VG_Object *);

    /* export-function to create a new object-instance of "OTEST" */
    unsigned int
    new_OTEST(int subid, int drawlevel)
    {
      struct VG_Object *objp;
      struct s_objvars *objvars;

      /* allocate private struct */
      objvars = calloc(1, sizeof(*objvars));
      if (objvars == NULL) { return 0; }

      /* set private struct */
      objvars->posx = 0;
      objvars->posy = 0;
      objvars->imgp = vg4->image->load("img/otest.bmp");

      /* create object-instance */
      objp = vg4->object->create(OBJID, subid, 0, drawlevel, objvars);
      /* set functions */
      objp->f_free = f_free;
      objp->f_run = f_run;
      objp->f_draw = f_draw;
      /* f_data() and f_childexit() are not needed here */

      return objp->instanceid;
    }

    /* free private struct of object-instance, called from vg4->object->destroy() */
    static void
    f_free(void *vgame, void *opriv)
    {
      struct s_objvars *objvars = (struct s_objvars *)opriv;

      (void)vgame;

      /* free contents of private struct and itself */
      vg4->image->destroy(objvars->imgp);
      free(objvars);
    }

    /* move object-instance, called from vg4->object->call_run() */
    static VG_BOOL
    f_run(void *vgame, struct VG_Object *objp)
    {
      struct s_objvars *objvars = (struct s_objvars *)objp->opriv;

      /* move it and check for collisions */
      [...]

      return VG_TRUE;
    }

    /* draw object-instance, called from vg4->object->call_draw() */
    static void
    f_draw(void *vgame, struct VG_Object *objp)
    {
      struct s_objvars *objvars = (struct s_objvars *)objp->opriv;

      /* draw it */
      [...]
    }

    game.c

    /* create new object-instance of "OTEST" */
    new_OTEST(0, 1);

SEE ALSO
vg4->object->instance_getobj()