@database Hardsprite.guide

@$VER: Hardsprite V1.00 - by Andrea Galimberti - (C) Brighting Brain Brothers

This guide file has been created using AutoGuide V1.05 - By Fabio Rotondo (fsoft@intercom.it).

@node main "AFC Module: hardsprite / Main"


               ** Hardsprite V1.00 - Original By Andrea Galimberti **

                         Part of Amiga Foundation Classes

                            


    @{" Introduction  " LINK obj_intro}       @{" Author(s) Info " LINK author}


    Requires:

    Base: $8001

    COMMANDS                          BRIEF DESCRIPTION
    -----------------------------------------------------------------------
    @{" hardsprite()                     " LINK hardsprite} Initialises the Object
    @{" image()                          " LINK sprite_image} Stores the sprite image
    @{" changeImage()                    " LINK sprite_changeimage} Changes the sprite image
    @{" move()                           " LINK sprite_move} Moves the sprite
    @{" version()                        " LINK sprite_version} Gets object version

    @{" ERROR TABLE " LINK Error_Table}

@endnode

@node author "Author(s) Info"

    Original By:  Andrea Galimberti

    E Version By: Andrea Galimberti


@endnode

@node obj_intro "Hardsprite / Introduction"

   Hardsprite.


   This object allows to easily access and manipulate the so called Simple
Sprites, that is to say Hardware Sprites.  You can use each of the 8
sprites and move it to a location relative to a viewport or to the whole
view (be it the Intuition one or a custom one you created by hand).
Obviously, you can change the image of the sprites (but it cannot be more
than 16 pixels wide, 4 colours).

@endnode

@node Error_Table "Hardsprite / Error Table"

Val (Hex)  | Description
-----------+------------------------------------------------------
  $0000    | No Memory

@endnode

@node hardsprite "AFC module: hardsprite / hardsprite()"

          NAME: hardsprite(number=-1)

   DESCRIPTION: Builds a hardsprite object

        INPUTS: number of hardware sprite to use (from 0 to 7).  If the
                requested sprite is not available this function will return
                FALSE.  The default value of -1 means that it will be
                allocated the first sprite available.

       RESULTS: TRUE if all went ok.
                FALSE if the reqired sprite is already in use and so it
                couldn't be allocated.

      SEE ALSO:

@endnode

@node sprite_image "AFC module: hardsprite / image()"

          NAME: image(height, list:PTR TO INT)

   DESCRIPTION: this method stores the image to be used with the sprite.
                Whenever this method is called, it will discard the
                previous image.

        INPUTS: height (in lines) of the image,
                a typed list (it MUST be typed to INT) in the following
                form:

                           [ $0000, $0000,
                             $0000, $0000,
                             ...          ]:INT

                               ^      ^
                               |      |
                               |      second bitplane (16 bits wide)
                               |
                               first bitplane (16 bits wide)

                This way you can select one of 4 colours for each pixel of
                the sprite's image.

       RESULTS: returns FALSE if: sprite non allocated (with hardsprite()),
                                  height<=0,
                                  pointer to list =NIL.
                Raise "No Memory" if it cannot allocate the (CHIP) memory
                for the image.

      SEE ALSO:

@endnode

@node sprite_changeimage "AFC module: hardsprite / changeImage()"

          NAME: changeImage(viewport)

   DESCRIPTION: changes the sprite image to the stored one.

        INPUTS: pointer to a viewport structure.  If this pointer is <>NIL
                then the change will affect only the chosen viewport; if
                pointer=NIL then the change is relative to the current
                view.

       RESULTS: FALSE if viewport<0 or sprite not allocated.
                Otherwise TRUE.

      SEE ALSO: @{" image() " LINK sprite_image}

@endnode

@node sprite_move "AFC module: hardsprite / move()"

          NAME: move(viewport, x, y)

   DESCRIPTION: moves the sprite to the selected location (x,y) on a
                viewport.

        INPUTS: viewport: pointer to a viewport structure; if this pointer
                is NIL then the coordinates are relative to the current
                view.

       RESULTS: NONE

      SEE ALSO:

@endnode

@node sprite_version "AFC module: hardsprite / version()"

          NAME: version()

   DESCRIPTION: gets version number of the Sprite module

        INPUTS: NONE

       RESULTS: hardsprite version, hardsprite revision

      SEE ALSO:

@endnode

