The CDPD Public Domain Collection for CDTV 3/CDPDIII.bin/pd/graphics/viewers/grasp/commands.man

Text File | 1992-09-09 | 13KB | 333 lines

    GL COMMANDS                                               03.09.92



    The following GRASP commands have been implemented in GL 2.1. This
    is a subset of those available in the real thing, chosen because
    they applied to the files that I have, and fit fairly well into
    the goal of converting files to play back efficiently.

    I added a few commands which you won't find in the MS-DOS format,
    because they were useful in converting files. They are marked with
    an A.

    Positioning in an Amiga GL file is relative to the top-left corner
    of the screen. When converting, it is often necessary to change
    the coordinates in commands to match this, as the MS-DOS default
    appears to be relative to the bottom-left of the screen.

    Optional parameters are delimited by square brackets. Some MS-DOS
    versions of these commands have other optional parameters
    following those listed. These are ignored by GL.


    BOX X0,Y0,X1,Y1,[WIDTH]

        Draws a box from X0,Y0 to X1,Y1, with a border WIDTH pixels
        wide. The default WIDTH is 1.

    CFADE FADE,X,Y,BUFFER,[SPEED],[DELAY]

        Fades a clip to the screen. See FADES below for a list of the
        supported fades. The clip will be positioned at X,Y on the
        screen. The BUFFER is the clip number to fade, and is the
        same as the BUFFER in the CLOAD command.

        The SPEED parameter is ignored. The DELAY parameter indicates
        a delay, in 100ths of a second, before the player should
        continue with the next command.

    CFREE NUM1,[NUM2],[NUM3],...

        Free 1 or more clip buffers. The memory allocated for the
        specified buffers will be returned to the system. It's ok if
        a buffer hasn't actually been loaded before calling this
        command - that buffer will just be ignored.

        Note that if you will be loading another clip into one of
        these buffers, and that clip is the same size or smaller than
        the current contents, then there isn't much point in calling
        CFREE. The CLOAD command will detect that the buffer space
        hasn't been freed, and will re-use it. If the new clip is
        larger, the CLOAD command will free the buffer, then
        reallocate it for the new clip size.

        GL will also automatically free everything when it exits.

    CHGCOLOR D1,S1,[D2,S2],[D3,S3],...

        Copy the value in color register S1 to color register D1, and
        so on for each pair of values.

    CLEARSCR

        Fills the screen with the current color. The initial current
        color is 0, but it can be changed with the COLOR command.

    CLOAD NAME,BUFFER,[TYPE]

        Loads clip buffer number given by BUFFER with the picture
        given by NAME. BUFFER should be a number between 1 and 128.
        The NAME search is done as follows: if NAME contains a '.'
        character, then a filename exactly matching NAME must exist.
        Otherwise, GL looks first for NAME.CLP, and if that's not
        found, it looks for NAME.#?.

        The optional TYPE is the kind of RAM to allocate for the clip,
        and if present should be either FAST or CHIP. Clips loaded
        into FAST RAM will not be displayed as quickly as those in
        CHIP RAM, but this is sometimes necessary when the amount of
        clip data you want to load exceeds available CHIP RAM. The
        MS-DOS version of this command has a SHIFTFLAG in this field -
        this means nothing on the Amiga. The default TYPE is CHIP.

    COLOR REGISTER

        Sets the default drawing pen to REGISTER. The initial current
        color is 0.

  A CPALETTE BUFFER

        Loads the color map from the clip buffer number BUFFER into
        the screen. MS-DOS clips normally don't have a palette, but
        Amiga clips do, and using CPALETTE to set the colors could
        mean that you can get rid of the PAL.PIC that many MS-DOS GL
        files use.

  A DAMAGE [OPT]

        Controls damage repair in double buffering. Commands that
        draw something set a "damage" rectangle after rendering,
        which covers the area of the screen they've changed. Then
        when a buffer swap is performed, the damage rectangle is
        copied from the visible buffer to the hidden buffer after the
        swap, to keep the buffers in sync.

        In some cases, this sort of damage control is redundant. This
        is especially true when the next drawing command uses exactly
        the same area the previous command used. So it would be handy
        to be able to turn it on/off, or even to let the script mark
        damage areas itself.

        OPT can be ON, OFF or ALL. ON turns damage repair on (the
        default). OFF turns it off. ALL turns it on, and forces an
        update of the entire screen. If OPT is not given, then the
        state of damage repair is toggled.

        Commands like FLY will automatically avoid damage repair when
        they can. For example, FLY with a STEP of 0 doesn't require a
        repair until the end of the command. It's the damage repair
        between commands like CFADE, PFADE and PUTUP that this
        command is aimed at removing.

    DATABEGIN LABEL

        Sets up pointers for argument indirection to just after
        LABEL. When a "@" is encountered in a command argument list,
        it is replaced with the next available token from the list
        pointed to by a preceding DATABEGIN command. The list of
        tokens is terminated by the end of the file, or by a
        "DATAEND" token.

        This is used in conjunction with POSITION to do debanimation.

    EXIT

        Ends the animation.

    FLY STARTX,STARTY,ENDX,ENDY,STEP,DELAY,NUM1,[NUM2],[NUM3],...

        Renders clip NUM1 at STARTX,STARTY then adds STEP to STARTX,
        STARTY and renders clip NUM2. Then adds STEP to STARTX,STARTY
        and renders clip NUM3. And so on. After rendering all the
        clips, GL pauses for DELAY 100ths of a second. Then it
        compares the current STARTX,STARTY with ENDX,ENDY, and if
        they are the same, it continues on to the next command.

        There can be up to 32 clip numbers following DELAY. In fact,
        there isn't a limit, but MS-DOS files have a limit of 32.

        FLY is often used with a STEP of 0, to show a series of clips
        in the same position, as an alternative to using a long
        series of CFADE commands.

    GOSUB LABEL

        Executes a subroutine at LABEL. A subroutine is terminated by
        the RETURN command. GOSUBs can be nested 10 levels deep.

        A label is a line starting with a word followed by a ':'
        character. The GOSUB command should not include the ':' after
        the LABEL.

    GOTO LABEL

        Transfers execution to LABEL.

        A label is a line starting with a word followed by a ':'
        character. The GOTO command should not include the ':' after
        the LABEL.

    LOOP

        Do the next iteration of the matching MARK command. If all
        the specified iterations have been done, continue with the
        next line.

    MARK NUMBER

        Set a mark for a matching LOOP command. The number is how
        many iterations of the script between the MARK and the LOOP
        should be performed.

        MARK/LOOP pairs can be nested 16 levels deep.

    PALETTE BUFFER

        Loads the color map from the picture buffer number BUFFER
        into the screen.

    PFADE FADE,BUFFER,[SPEED],[DELAY]

        Fades a picture to the screen. See FADES below for a list of
        the supported fades. The BUFFER is the picture number to
        fade, and is the same the BUFFER as the PLOAD command.

        The SPEED parameter is ignored. The DELAY parameter indicates
        a delay, in 100ths of a second, before the player should
        continue with the next command.

        The picture is faded in at 0,0 on the screen. For pictures
        that are smaller than the screen size, the MS-DOS version may
        have expected the picture to get faded in at the bottom-left
        corner.

        FADE number 0 is a special case. Instead of fading in a
        picture, the current color (see COLOR) is faded into the
        entire screen. Not all fades support this usage.

    PFREE NUM1,[NUM2],[NUM3],...

        Free 1 or more picture buffers. The memory allocated for the
        specified buffers will be returned to the system. It's ok if
        a buffer hasn't actually been loaded before calling this
        command - that buffer will just be ignored.

        Note that if you will be loading another picture into one of
        these buffers, and that picture is the same size or smaller
        than the current contents, then there isn't much point in
        calling PFREE. The PLOAD command will detect that the buffer
        space hasn't been freed, and will re-use it. If the new
        picture is larger, the PLOAD command will free the buffer,
        then reallocate it for the new picture size.

        GL will also automatically free everything when it exits.

    PLOAD NAME,BUFFER,[TYPE]

        Loads picture buffer number given by BUFFER with the picture
        given by NAME. BUFFER should be a number between 1 and 16.
        The NAME search is done as follows: if NAME contains a '.'
        character, then a filename exactly matching NAME must exist.
        Otherwise, GL looks first for NAME.PIC, and if that's not
        found, it looks for NAME.#?.

        The optional TYPE is the kind of RAM to allocate for the
        picture, and if present should be either FAST or CHIP.
        Pictures loaded into FAST RAM will not be displayed as quickly
        as those in CHIP RAM, but this is sometimes necessary when the
        amount of data you want to load exceeds available CHIP RAM.
        The default value is CHIP.

    POSITION BUUFER,X,Y

        Sets the top-left coordinates for picture buffer BUFFER to X,
        Y. This is usually used to scroll pictures larger than the
        screen, in a process called "debanimation".

        For example, given a picture that is 320x500 pixels in size,
        you can display the region from (0,200)-(319,399) on a
        320x200 screen by using the command POSITION 1,0,200.

        This command only affects PFADE 0.

    PUTUP X,Y,[BUFFER],[DELAY]

        This is synonymous with CFADE 0,X,Y,BUFFER,0,DELAY. The
        default BUFFER number is 1, and the default DELAY is 0. The
        semantics of the MS-DOS version of this command are slightly
        different, but that applies to things have haven't been
        implemented yet by this player.

    RETURN

        Ends a subroutine.

    TILE BUFFER

        Tiles the clip buffer BUFFER on the screen. Starting at the
        top-left of the screen, the clip is repeated to the right and
        down.

    VIDEO [MODE1],...,[MODEN],[WNNN],[HNNN],[DNNN]

        Selects a display mode and dimensions. The animation screen
        is opened when this command is executed.

        MODE can be either HAM, HIRES or LACE. More than one mode
        word may be specified. If HAM and HIRES are not used, then
        the default mode is LORES.

        WNNN gives the desired width in pixels. HNNN is the height,
        and DNNN is the depth in bitplanes.

    WAITKEY [DELAY],[LABEL]

        Pauses until the user hits a key. If DELAY is given, then the
        pause will timeout after DELAY 100ths of a second. If a
        timeout occurs and LABEL is present, execution is tranferred
        to LABEL.

    WINDOW X0,Y0,X1,Y1

        Specifies a clipping window. Areas outside this window will
        not be affected by most rendering commands. The only
        exception at this time is the BOX command.


    FADES

    At least 25 fades may referenced by the CFADE and PFADE commands.
    Those marked with an '*' are implemented. If an unimplemented
    fade is requested, fade 0 is used.

    *   0 Quick snap wipe
    *   1 Horizontal left to right wipe
    *   2 Horizontal right to left wipe
    *   3 Horizontal edge to center wipe
    *   4 Horizontal center to edge wipe
    *   5 Horizontal 1 pass filter wipe - both sides simultaneously
    *   6 Horizontal 2 pass filter wipe - from left, then from right
        7 Horizontal halves wipe - left to right, then right to left
        8 Horizontal halves wipe - left and right simultaneously
    *   9 Vertical top to bottom wipe
    *  10 Vertical bottom to top wipe
       11 Vertical edge to center wipe
       12 Vertical center to edge wipe
       13 Vertical filter wipe, top and bottom simultaneously
       14 Vertical halves wipe, top and bottom simultaneously
       15 Vertical halves wipe, left down, right up
       16 Vertical quarters wipe
       17 Vertical fingers wipe
       18 Vertical fingers/filter combination wipe
    *  19 Slither from top to bottom
    *  20 Sparkle fade (random)
       21 Diagonal wipe
       22 Aperature dissolve - edge to center
       23 Aperature dissolve - center to edge
       24 Clockwise clock dissolve
       25 Double slant dissolve