[.. upper level ..]

Animation functions

A sprite is a collection of images, optionally with simple soundfiles, in order to draw an object with animations.

A film is a collection of successive film-pictures, which are images (and sound) arranged on the whole window.

• Structures and Enumerations


• Sprites
• Creating and destroying sprites
• VG3_sprite_new()
  
  Return an initialized empty sprite.
• VG3_sprite_load()
  
  Load a sprite from file.
• VG3_sprite_clone()
  
  Clone a sprite as a new sprite (copy).
• VG3_sprite_free()
  
  Destroy a sprite.


• Setting and getting sprite properties
• VG3_sprite_commonparam()
  
  Set or get common attributes of a sprite.
• VG3_sprite_addelem()
  
  Add an image and/or sound to a sprite.


• Running sprites
• VG3_sprite_get()
  
  Return actual image and/or sound from a sprite for drawing and/or playing.
• VG3_sprite_rewind()
  
  Rewind a sprite to the beginning.
• VG3_sprite_imagesize()
  
  Return a calculated average size of a sprite, e.g. to use it for a constant collision rectangle.


• Film
• VG3_film_play()
  
  Play a film as described in a film-text-file.

Example

  /* Create an animated sprite with an image "sunnyboy.bmp"
   * which rotates this image twice around
   * and show it until the sprite ends
   */

  struct vg3_window *wstruct;
  int winw, winh;

  /* open window */
  wstruct = VG3_window_new(argv[0], VGAG3_VGAVERSION_LOW, VGAG3_WINSCALE_BESTSCALE);
  if (wstruct == NULL) { fprintf(stderr, "%s\n", VG3_error()); exit(1); }

  /* get the size of the window */
  VG3_window_getsize(wstruct, &winw, &winh);

  /* create a sunnyboy sprite,
   * which rotates a sunnyboy image two times,
   * and show it
   */
  { struct vg3_sprite *sprt;
    int repeat;
    struct vg3_image_attributes imgattr;
    struct vg3_image *imgptr;

    /* create an empty animated sprite */
    sprt = VG3_sprite_new(wstruct);
    if (sprt == NULL) { fprintf(stderr, "%s\n", VG3_error()); goto byebye; }

    /* set default values:
     * repeat sprite two times
     * one game-loop for each sprite element
     */
    { struct vg3_hash *hset = VG3_hash_new();
      VG3_hash_setint(hset, "LOOP", sizeof("LOOP"), 1);
      VG3_hash_setint(hset, "LIFETIME", sizeof("LIFETIME"), 2);
      VG3_sprite_commonparam(sprt, hset, NULL, NULL, NULL);
      VG3_hash_free(hset);
    }

    /* add 360 sprite elements,
     * each showing the sunnyboy image rotated according to value of repeat
     */
    for (repeat = 1; repeat <= 360; repeat++) {
      VGAG3_IMAGE_ATTRIBUTES_DEFAULT(&imgattr);
      imgattr.rotate = repeat;
      VG3_sprite_addelem(sprt, 0, "sunnyboy.bmp", &imgattr, NULL, 0);
    }

    /* game-loop */
    VG3_discard_input(wstruct);
    for (;;) {
      /* clear window */
      VG3_draw_clear(wstruct, NULL, VGAG3_COLOR_BLACK);

      /* get next sprite element,
       * if sprite ended, exit game-loop
       */
      if (!VG3_sprite_get(sprt, &imgptr, &imgattr, NULL)) { break; }

      /* draw image, if not NULL, onto the middle of the window */
      if (imgptr != NULL) {
        VG3_image_copy(wstruct, NULL, imgptr, winw / 2, winh / 2, &imgattr, 0);
      }

      /* update window and get key-strokes */
      VG3_window_update(wstruct, 0, 0);
      if (VG3_inputevent_update(wstruct) > 0) { break; }

      /* quit? */
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_SPACE, VGAG3_IS_NEW_PRESSED)) { break; }
      if (VG3_key_ispressed(wstruct, VGAG3_KEY_ENTER, VGAG3_IS_NEW_PRESSED)) { break; }

      /* wait up to 10 msec */
      VG3_wait_time(10);
    }
    VG3_discard_input(wstruct);

    /* free the sprite */
    VG3_sprite_free(sprt);
  }

  /* if an error occurred after creating the window, close it before exiting */
  byebye:
  /* close window */
  VG3_window_free(wstruct);