Micro R&D 1/MicroRD-CD-ROM-Vol1-1994.iso/os30/gfx/animdemo.lha/Read.Me

Text File | 1993-01-26 | 11.3 KB | 343 lines

This file explains what the PlayRaw code does, describes the V39 and AA features
it uses, and the file format used.

First, a message from our lawyers:

(c) Copyright 1993 Commodore-Amiga, Inc.  All rights reserved.

This software is provided as-is and is subject to change; no warranties
are made.  All use is at your own risk.  No liability or responsibility
is assumed.

Now, on with the show.

The Animation
=============

The Animation is an approximately 3300 frame animation, rendered using VistaPro
(with MakePath generating the script). VistaPro was set to save each frame as a
24bit image. We then ran a rexx script to control ASDG's Art Department, which
loaded each frame, composed a mask of the cockpit on top, converted the frame to
6 bitplanes with a locked palette, and saved to an anim file with their new
Anim8 saver module.

The mask and the cockpit were drawn by an outside contractor.

Thanks must go to both Virtual Realities Limited and ASDG for their help, and
to Mr.J.S ;-)


Anim8
=====

Anim8 is a small variation on the commonly used Anim5 format.  Anim5 won't be
described here; see the IFF documentation in 'Amiga RKM - Devices' for more
details.  The problem with Anim5 is that all the data is encoded in bytes.  On a
machine with only CHIP RAM, thare is a serious overhead on byte reads and writes
as the CPU executes wait states during the memory accesses.  Even on a machine
with FAST RAM, the writes still have to go to CHIP RAM.  Anim8 (which has
recently been registered with C=) extends Anim5 by encoding data as either Words
or Longs; all DLTA opcodes and data are stored as WORDS or LONGS.  This means we
can now read and write 2 or 4 times as much information to the CHIP RAM, thus
cutting down on CHIP RAM accesses.  One of the drawbacks is that the animation
may not compress as well as Anim5, but nevertheless the playback is about twice
as fast!

The PlayDLTA() code in ilbm.asm is based on Jim Kent's original Anim5 code, but
I have modified it with a few 68020 instructions, optimised it for my animation
by changing the order of the opcode checks, and hard-coded for LONG DLTA
animations.

So Beware - this executable requires a 68020 CPU and AA chips at least!


The file format
===============

To speed up playback, all the IFF header information has been stripped away,
leaving just the raw DLTA data.  This reduces the overhead of IFFParse.  Each
frame is stored separately, and padded out to a whole number of sectors to speed
up the reading.

At the beginning of the raw data file is some information, such as image size,
colours, sounds etc. The format of this Frame1Header is defined in playanim.h as:

/* Frame1 is the format of the 1st frame of the sequence.
 * This cannot be defined in C, because the structure is of a variable length.
 *
 *
 * struct Frame1Head
 * {
 *    ULONG f1_MaxSectorSize;    // max number of sectors in a frame
 *     ULONG f1_ByteSize;    // number of bytes in this block
 *    ULONG f1_Sectors;    // number of sectors in this block
 *    UWORD f1_ImageWidth;    // number of pixels accross the image
 *    UWORD f1_ImageHeight;    // number of rows in the image
 *    UWORD f1_ImageDepth;    // depth of the image
 *    UWORD f1_ScreenWidth;    // number of pixels accross the screen
 *    UWORD f1_ScreenHeight;
 *    UWORD f1_ScreenDepth;
 *    ULONG f1_ScreenModeID;
 *    UWORD f1_Colours;    // number of colours in the CMAP
 *    UBYTE f1_CMAP[];    // full CMAP structure.
 *    UBYTE f1_ILBM;        // ILBM of frame 1
 *    ULONG f1_NextByteSize;    // number of bytes in the next frame
 *    ULONG f1_NextSectors;    // number of sectors in the next frame
 *      VistaScript Data
 *    UBYTE f1_pads[];    // pad to the next whole sector
 *    AudioData
 * };
 */

struct Frame1Head
{
    ULONG f1_MaxSectorSize;
    ULONG f1_ByteSize;
    ULONG f1_Sectors;
    UWORD f1_ImageWidth;    // number of pixels across the image
    UWORD f1_ImageHeight;    // number of rows in the image
    UWORD f1_ImageDepth;    // depth of the image
    UWORD f1_ScreenWidth;    // number of pixels across the screen
    UWORD f1_ScreenHeight;
    UWORD f1_ScreenDepth;
    ULONG f1_ScreenModeID;
    UWORD f1_Colours;
};

f1_MaxSectorSize allows us to allocate a memory buffer before we start playing
the animation that is big enough to hold the DLTA data of the largest frame.

After f1_Colours, comes the colours themselves, followed by the ILBM (with the
IFF headers stripped off) of the first frame in the animation, which is normal
for anim files.

This is followed by the size (in bytes and whole sectors) of the next frame in
the animation. All other frames follow suit; that is, they store the size of the
*next* frame. This allows us to read in each frame with one Read() call, rather
than one read to find it's size, and another read for the data.

f1_NextSectors is followed by some data from the VistaPro script, describing the
position of the 'plane in this frame as:

struct VistaScript
{
    WORD vs_CamX;
    WORD vs_CamY;
    WORD vs_CamZ;
    WORD vs_Bank;
    WORD vs_Heading;
    WORD vs_Pitch;
    WORD vs_Focal;
};

This could be useful for, say, calculating the 'planes position relative to an
enemy aircraft, or a missile.

VistaScript is followed by padding to take the byte count up to a whole
SECTORSIZE. There follows two more "frames" of audio data, both 8SVX files (with
the IFF headers removed), both padded to whole SECTORSIZEs, for the missile
audio and the audio for the plane engines.

All this is then followed by the animation DLTA frames themselves. The final
frame sets it's NextSectors and NextByteSize to NULL.


The raw file is built with the 'makeraw' program. 3300 frames is too large to
fit on a floppy disk, so this example code comes with only a few of the frames.


The Display
===========

The animation is only 6 bitplanes, but we use an 8 bitplane screen to give us
256 colours. The animation is rendered into the lower 6 bitplanes, but a 'mask'
image is rendered in the upper 2 bitplanes. This mask is the image of the glass
window of the cockpit. Colours 64-128 are set to be about 20% brighter than the
natural colours of the animation. The cockpit mask provides the planes of the
window panes, thus we fake out our own Extra-HalfBrite screen.

The animation screen is 320x98x6 Lores.  Attached to this animation screen, is a
screen containing the image of the cockpit interior, which is 640x102x8.  This
is done by using intuition's V39 attached screens.  Thus, if we move one screen,
the other moves with it, giving the appearance of one large multi-coloured
multi-resolution screen.

VistaPro was set to render the sky as a purple background.  We then use
FindColor() to determine which colour number this purple sky is in the
animation, and build a UserCopperlist to gradually change the sky's colour
through a range of skyblues.

Becuase we need to ensure that the screen which is displaying the animation can
handle both sprites and doublebuffering, we check the graphics database to see
that the desired ModeID has the DisplayInfo->PropertyFlags DIPF_IS_SPRITES and
DIPF_IS_DBUFFER set.  If not, then we use the V39 graphics function BestModeID()
to find a ModeID that does support both these features, and provides the best
aspect ratio for the animation's size.

BestModeID() is also used to find the best mode for the cockpit screen to match
the monitor type of the animation screen.

We open the screens behind the workbench, so that all our setups are hidden, and
then bring the screens to the front.


Sprites and input
=================

Input comes from two places; the joystick and the keyboard. The joystick is for
moving the cross-hair cursor around and firing the missiles, the keyboard is for
aborting the animation.

Input from the joystick comes from reading the joy1dat RGA register. Kinda
naughty I know, but that register will always be around. I should really open
the gameport device.

Input from the keyboard comes from intuition, via it's RAWKEY IDCMP message.

The cross-hair sprite is intuition's pointer.  In fact, I keep intuition around,
so it's possible to move the cross-hair with both the joystick and the mouse.  I
use intuition's NewOject() to change the imagery of the pointer to the
cross-hair, and change the pointer's hotspot to the center.

The input from the joystick is translated into input events, and sent to
input.device, so intuition knows about the pointer position, and does the sprite
movements for me.

The missiles are also sprites.  AllocSpriteData() is used to set it up, and
GetExtSprite() to reserve the sprite for our usage.  We use MoveSprite() to move
them.


Audio
=====

All audio is handled through the audio.device. The audio for the missile is
first allocated, and then the two opposite channels for the thruster audio are
allocated to provide stereo. The two thruster chanels use different audio
channels than the missile.


Note that all the sprite and audio updates are done in the time that the code
would be Wait()ing for the signal to double-buffer, thus maximising use of the
CPU.


AsyncIO
=======

During development of this code, I noticed that a large proportion of the time
was spent CopyMem()ing the double-buffers used in Martin Taillefer's AsyncIO()
code. I hacked the AsyncIO code to reduce the amount of time spent copying
memory. Instead, if all the data requested is in the AsyncIO read buffer, I
point a UBYTE *rbuff variable to the contents of this buffer, and read from
there directly.



Feature list
============

A list of the V39 OS and AA features used in this code:

V39 Graphics:
ChangeVPBitMap() et al for double buffering
(an example of how CalcIVG() should be used)
ExtSprite functions.
...RGB32() functions
FindColor()
BestModeID() and database checking

V39 Intuition:
NewObject() POINTERCLASS
Attached screens

Other OS feautures:
IFFParse.library
AsyncIO
audio.device
input.device
UserCopperLists

AA features:
variable sprite width and resolution
changing the colour banks of sprites.
8 bitplane screens.
24bit colours.


File List
=========

playanim.i
playanim.h    ; general header files
sprites.h    ; sprite definitions
stick.i
stick.h        ; joystick and input structures.
asyncio.h    ; asyncio header file

playraw.c    ; the main code
input.c        ; handles input events
audio.c        ; handles audio IO
iff.c        ; reads the IFF files
sprites.c    ; handles sprite allocation and movement
spriteimage.c    ; sprite bitmaps
asyncio.c    ; asynchronous file IO
joystick.asm    ; reads the joystick port
ilbm.asm    ; reads ILBMs and Anim8 LONG form DLTAs

lmkfile        ; a makefile

playraw.o
ilbm.o
asyncio.o
sprites.o
joystick.o
input.o
spriteimage.o
iff.o
audio.o        ; object files

Read.Me        ; this file

playraw        ; the executable

cp.medres    ; the cockpit image
mask1        ; the cockpit window mask for the animation


makeraw/makeraw.c    ; code to convert the ANIM and 8SVX files into
            ; the raw file format
makeraw/audio.c        ; converts the audio files.
makeraw/lmkfile        ; a makefile
makeraw/thrust2        ; 8SVX file for the thruster audio
makeraw/alienfires    ; 8SVX file for the gun-fire
makeraw/vistascript    ; VistaPro script file
makeraw/anim        ; an ANIM file
makeraw/makeraw.o
makeraw/audio.o        ; object files
makeraw/makeraw        ; the executable

Usage
=====

To build the raw animation file, from the CLI type

cd makeraw
makeraw from anim to anim.raw fit m `eval 0x11000` f alienfires t thrust2 x 2


To play the animation, from the CLI, type

cd /
playraw makeraw/anim.raw c cp.medres m mask1

Use the joystick to move the cross-hair.
Fire button to fire missiles.
Any keypress to abort.


Have Fun!!

Spencer Shanson
Amiga Software Engineer.