@database RetinaANIM.guide

@wordwrap

@node Main "RetinaANIM Documentation"
@{b}RetinaANIM Version 39.2:@{ub}

    @{b}RetinaANIM - Animation utility for the Macrosystems Retina Z3.@{ub}

    @{" Introduction " link Introduction }
    @{" Installation " link Installation }
    @{" About Author " link Author }
    @{" Usage        " link Usage }
    @{" Future       " link ToDo }
    @{" Known Bugs   " link KnownBugs }
    @{" Warnings     " link Warnings }
    @{" History      " link History }
    @{" Legal        " link Copyright }
@endnode

@node Introduction "Introduction to RetinaANIM"
@{b}Introduction:@{ub}

    This is a program that will display animations on the Retina Z3 graphics card. It will not work on the Retina Z2.
    When completed it will play AVIs, QuickTime's and IFF ANIMs. It may even play MPEG 1 (maybe MPEG 2) if I get really enthusiastic. Currently however it supports the following:
    *   AVI files
        Video Codecs:
        *   Microsoft CRAM.
        *   Radius Cinepak.
        Audio Codecs:
        *   WAV PCM.
        *   WAV ADPCM.

    @{b}RetinaANIM@{ub} requires:
    *   AmigaDOS 3.0 (version 39) or greater.
    *   68030 minimum.
    *   Retina Z3 graphics card. It will not work with the RetinaZ2 (yet).

    If @{b}RetinaANIM@{ub} does not support and AVI you have, or you have any really obscure AVIs, please e-mail me at this @{"address" link Author} so I can arrange for it to be sent to me for testing/development etc.
@endnode

@node Installation "How to Install RetinaANIM"
@{b}Installation:@{ub}

    Installation is easy!!

    Just copy RetinaANIM anywhere, and use it. If you have a 68040, then use RetinaANIM040 as it is optimised for the '040, and uses 68881 instead of standard math - for the few places it is used. Because of the '040 instruction scheduling it should be faster. This speed difference may be more noticeable with a superscalar processor like the 68060.

    Then you should place the RetinaANIM.guide file somewhere (if you keep ALL documentation).

    @{b}RetinaANIM@{ub} is so easy to use, this file is probably not very important.
@endnode

@node Author "About the Author"
@{b}About Author:@{ub}

    @{b}RetinaANIM@{ub} was written over a period of four (4) months by myself, Stuart MacKinnon.
    If anyone has an idea for a program and they don't know how to do it themselves (as they may not be a programmer), I would be glad to help.
    I can be contacted via Internet (e-mail):
        stuartm@zip.com.au
    Or by snail-mail:
        6/5 Abbey Street
        Randwick NSW
        Australia 2031

@endnode

@node Usage "How to use RetinaANIM"
@{b}Usage:@{ub}

    Firstly @{"install" link Installation } @{b}RetinaANIM@{ub}. Technically you don't have to install it just to test it out. You could just enter its name from the Shell.

    @{b}RetinaANIM@{ub} can only be started from CLI/Shell. If you run it from the Workbench it will inform you of this.
    The option template is:

    FILE/A,BUFSIZE/N,VOL/N,STARTDELAY/N,ENDDELAY/N,FRAMETIME/N,PRI/N,AUDPRI/N,
    NOAUDIO/S,NOVIDEO/S,NODBUF/S,SKIP/S,VERBOSE/S

    FILE/A:       File name of the animation to play.

    BUFSIZE/N:    Size of the disk I/O buffer. Disk I/O is double buffered,
                  so two (2) buffers of this size will be allocated. This
                  option is in bytes. Default is 1048576 (1 Mbyte). If you
                  find that the animation slows down a lot during disk I/O,
                  then it may be better to have a smaller value here so
                  that disk I/O is spread more evenly across the whole
                  animation giving much more consistent playback.

    VOL/N:        The volume of the audio (0 to 64). Default is 64.

    STARTDELAY/N: Number of seconds to wait after opening the screen before
                  the animation should be started. This is so that if you
                  have a monitor that takes a second or two to re-sync to
                  the new screen mode, you will be able to see the whole
                  animation. Default is 0.

    ENDDELAY/N:   Number of seconds to wait on the last frame before closing
                  the screen. Default is 0.

    FRAMETIME/N:  Time between each frame. This can be used to slightly
                  adjust the frame time if audio seems to be slightly out of
                  sync with video. The VERBOSE option will tell you what the
                  frame time is normally. If you set the frame time too large
                  the animation will play slowly and you will probably hear
                  gaps in the audio. If the frame time is too small, then the
                  audio will continue to play at normal speed, and it will
                  therefore be out of sync with video.

    PRI/N:        This gives the priority of the video/audio decoding task.
                  Default is 15. This may seem high, but for smooth playback
                  it should be higher than the filesystem task.

    AUDPRI/N:     This gives the priority of the audio playback task. Default
                  is one higher than the video/audio decoding task.

    NOAUDIO/S:    This disables audio playback/decoding, so you can just see
                  video.

    NOVIDEO/S:    This disables video playback/decoding, so you can just hear
                  audio. If you want to hear the audio, but the video
                  decoding takes too long (and the audio then skips), use
                  this option.

    NODBUF/S:     This disables double buffering of the display. In some
                  cases it may speed up the AVI by a small amount. You will
                  probably see the screen refresh however, and that looks
                  ugly.

    SKIP/S:       Normally if a couple of frames of video take a bit long to
                  decode, then the following frames will be played as fast as
                  possible to attempt to catch up. Once video has caught up,
                  video is decoded and the appropriate frame time is put back
                  in. This option will cause frames to be completely skipped
                  to catch up. It will only skip frames if it gets 2 frames
                  or more behind. There are problems with this option. Some
                  video codecs use delta information for each frame. That
                  means that if a frame is skipped, then the frame buffer is
                  not in the correct state for the next delta frame. What
                  happens is that the display looks corrupted until the next
                  key frame (or frame that contains a full screen of data) is
                  displayed. A codec that repaints the whole screen every
                  frame will not have this problem.

    VERBOSE/S:    This option will give information about the animation
                  headers such as what video codec is used, what audio format
                  was found, frame time, width and height of screen, sample
                  rate of audio and number of channels, etc.

    @{b}RetinaANIM@{ub} will open an 8, 16 or 24 bit screen depending on what the animation requires. It will use the defaults configured in RetinaScreenMode.
@endnode

@node ToDo "What might RetinaANIM do in the future?"
@{b}Things to do:@{ub}

    There are quite a few things to do to @{b}RetinaANIM@{ub}. Those features are:
    *   Fix audio sync'ing problem. See @{"bugs" link KnownBugs} for more information.

    *   Make the FILE/A option a FILE/A/M option, and also do wildcard support on this option.

    *   Looping of AVIs (eventually all animations).

    *   Do QuickTime support.
    *   Do IFF ANIM support.
    *   Do MPEG 1 (maybe even MPEG 2) support.

    *   Allow for an environment variable that gives defaults for options such as VOL, QuickTime resource and data fork extensions (the options don't actually exist yet), VERBOSE, NODBUF, STARTDELAY, ENDDELAY, PRI, AUDPRI, SKIP and BUFSIZE.

    *   Make codecs separate executables/libraries.

    Graphics Cards:
    *   Standard Amiga.
    *   EGS.
    *   Retina-Z2.
    *   Piccolo and SD64.
    *   CyberVision 64.
    *   Picasso II.
    *   Merlin.

    Video Codecs:
    *   00DC.
    *   CRAM16 (Microsoft CRAM 16 bit).
    *   RGB.
    *   RGB32.
    *   RLE8.
    *   RLE4.
    *   ULTI (IBM Ultimotion).
    *   RT21 (Intel Indeo V2.1).
    *   IV31 (Intel Indeo V3.1).
    *   IV32 (Intel Indeo V3.2).

    Audio Formats:
    *   WAVALAW.
    *   WAVMULAW.
    *   WAVOKIADPCM.
    *   WAVDIGISTD.
    *   WAVDIGIFIX.
    *   IBMMULAW.
    *   IBMALAW.
    *   IBMADPCM.

    The problem with providing support for the codecs is actually having some AVIs that contain data in these formats so I can test the codecs and optimise their performance. The other problem is that (in the case of Intel Indeo stuff) some codecs are proprietary and the companies who designed them don't like giving up data formats without lots of money for license fees, or NDAs etc.
@endnode

@node KnownBugs "Known problems with RetinaANIM"
@{b}Known Bugs:@{ub}

    Sometimes the audio gets out of sync with video. If for some reason your machine is too slow, and the video cannot be decoded fast enough, then the audio buffer will be played and the audio will stop until it gets more audio data. Most AVIs have a few frames worth of audio before any video data. That means that in most cases two adjacent parts of audio and video are not meant to be played at the same time, the audio is a few frame ahead of the video in the file, and is buffered. However if the video is too slow and the audio stops, when new audio is available it will not be sync'd with the video any more. I cannot think of an easy and clean way to get around this - well I can I am just saying this as an excuse for not doing it.
@endnode

@node Warnings "Things to watch out for with RetinaANIM"
@{b}Warnings:@{ub}

    This will only work with the Retina Z3!!! It directly accesses Retina Z3 memory. For speed (it makes a huge difference), the code does not deal with the segmented architecture of the Retina Z2. Perhaps at a later time I will have two sets of code, one for the Z3, and the other for the Z2 - which will be slower. I have no idea what it would do if you did attempt to use it on a Retina Z2.

    With big sized frames, it chews up a lot of CPU time, but I guess you knew that already!
@endnode

@node History "RetinaANIM release history"
@{b}History:@{ub}

    RetinaANIM 39.2 (21.1.96)
        Second AMINET release.
        - Fixed a bug where sound would overwrite the end of its audio buffer
          causing lots of enforcer hits or in most circumstances a nasty
          crash (even with enforcer running). This would only happen with some
          ADPCM AVIs. All fixed now.

    RetinaANIM 39.1 (6.1.96)
        Initial AMINET release.
@endnode

@node Copyright "Copyright notices for various companies"
@{b}Copyright notices:@{ub}
    @{b}RetinaANIM@{ub}, its documentation, and support material is © Copyright 1996 Stuart MacKinnon. All rights reserved.

    This product is giftware. If you like it you could send me money, programs, books, CDs, AVI files, or anything else you care to send me. Here is my @{"address" link Author }.

    There are no warranties expressed or implied as to the performance of this product or the suitability of this product for a particular purpose. No responsibility is taken for any damage, lost revenue or time caused by the use of this product.

    Cinepak is a trademark of Radius Inc.
    Indeo is a trademark of Intel Corp.
    Ultimotion is a trademark of International Business Machines Corp.
    QuickTime is a trademark of Apple Computer Inc.
    68030, 68040, 68060, 68881 are trademarks of Motorola Inc.

    All other trademarks or registered trademarks are of their respective companies.

@endnode