
                              HOW TO RUN EXTRACT
                              ++++++++++++++++++
                              
                           Related Documents: Join (Version 3.06, 1 May,'94)
                           
Author:    CRose
Date:      29 April, 1994.
Version:   2.19
File Name: Extract


WHAT DOES EXTRACT DO?    Extracts one or more components of an Armovie file.
--------------------     The extracted components can then be used by Join
                         (see Join documentation) to build new Armovie files.
                         You can extract the header, sprite, keys, images,
                         and / or any or all of the sound tracks.  Unlike
                         version 2.00, it is now possible to extract
                         sound and images simultaneously and any other 
                         combination of extracts is now possible.
                         
THE SOURCE DATA:    All extract needs is the Armovie to extract from and a
---------------     destination directory in which to place the extracts.

                           
EXTRACTING SOUND DATA:  If you use the -sound parameter with Extract (see 
---------------------   examples below) but you do not specify which sound
                        track/s you want, then by default only the first track 
                        will be extracted.  Extract will use the Armovie's
                        header to determine whether the sound is at four,
                        eight, or sixteen bits per sample and will name 
                        extracted sound data accordingly.  (At 4 bits per 
                        sample - "adpcm", at 8 bits per sample - "sound",
                        and at 16 bits per sample - "samples").  If, for 
                        example you want to extract all the sound tracks 
                        from a 5 track Armovie where the number of bits
                        per sample is:
                        
                        Track 1 : 4 bits per sample (adpcm).
                        Track 2 : 16 bits per sample (samples).
                        Track 3 : 8 bits per sample (sound).
                        Track 4 : 8 bits per sample ((sound).
                        Track 5 : 4 bits per sample (adpcm).
                        
                        ... then the resulting extracts will be:
                        
                        Track 1 : "Adpcm"
                        Track 2 : "Samples"
                        Track 3 : "Sound"
                        Track 4 : "Sound2"
                        Track 5 : "Adpcm2"
 

PARAMETERS:  The parameters for running Extract are as follows.
----------  
    
  -source    (necessary) The name of the Armovie from which to extract data.
  -dest      (necessary) The name of an existing destination directory in 
                         which to put the extracted data.
  -header    (optional)  Extract the header.
  -sprite    (optional)  Extract the sprite.
  -keys      (optional)  Extract keys.
  -images    (optional)  Extract images.
  -sound     (optional)  Extract sound. Specific sound track/s can be specified
                         (see examples below).
  -help      (optional)                         
                         
                     
  By default, Extract will pull out all of the above if you only specify a
  source and destination (this includes ALL of the sound tracks).  If particular 
  components of the Armovie do not exist (e.g. if the Armovie has no keys), then 
  Extract will simply generate warning messages and ignore the parameter concerned.
  
  For on-line help just type the name of the program followed by -help.  
  
  
EXAMPLES:
--------

Example 1:  extract -help
---------       
            This will give help information (although obviously it won't 
            be as detailed as this document).
       
Example 2:  extract -source $.my_armovie -dest $.extracts -images
---------
            This will extract all the image data from $.my_armovie and 
            place it in the extracts directory.  The data is split up
            into separate files within one or more image directories
            ready to be used by Join at some later stage.  If my_armovie
            is a sound only Armovie then Extract will warn you of this
            and ignore the extraction request.
            
Example 3:  extract -source $.my_armovie -dest $.extracts -keys
---------   
            This will extract all the keys data from $.my_armovie and
            place it in the extracts directory.  The data is split up
            into separate files within one or more keys directories
            ready to be used by Join at some later stage.  If my_armovie
            does not contain any keys information then Extract will 
            notify you of this and nothing will be extracted.
            
Example 4:  extract -source $.my_armovie -dest $.extracts -images -keys
---------
            This combines examples 2 and 3 above.  Again, if images
            or keys do not exist in the Armovie file, Extract will
            issue appropriate warning message/s and will ignore the
            parameter/s concerned.
            
Example 5:  extract -source $.my_armovie -dest $.extracts -images -sound 3 5
---------
            This will extract all the images, along with the third and
            fifth sound tracks (if they exist).
            
Example 6:  extract -source $.my_armovie -dest $.extracts
---------   
            In this case Extract tries to extract all the components of the
            ARMovie, i.e. header, sprite, keys, images, and all the sound
            tracks.  If there are no keys then Extract will generate a warning 
            message and will carry on with the remainder of the extracts. 
            Similarly, if there is no image data or no sound data then
            Extract will tell you this before proceeding with the remainder
            of the extracts.           
            
            
            
OTHER POINTS WORTH MENTIONING:
-----------------------------

If you ask Extract to extract data which does not exist in the source Armovie
file, it will notify you of this and will carry on doing any other extracts
that you have asked for (if the data exists).  The only exception to this is
if you ask for a sound track which does not exist.  In this case, Extract will
tell you that the sound track does not exist and will end at that point.           
  
If Extract is terminated prematurely (e.g. user presses escape), an exception
handler will ensure that any open files are closed.  For obvious reasons this
only applies to files opened by Extract.            

There are two classes of error message.  Warnings may be ignored depending
upon context and requirements (e.g. extraction of images when there are no
images in the source file).  Fatal errors will actually stop the program at 
that point.  As mentioned above, an exception handler will ensure that any 
files opened by Extract are closed.

As well as taking in parameters from the command line, Extract will also look for
parameters held in the environment variable extract$ExtraArgs.  The split can 
occur anywhere.  e.g. extract -source $.MyArmovie -de may be entered on the command
line, while st $.Extracts may be held in extract$ExtraArgs.  Extract will simply 
join the two together to produce extract -source $.MyArmovie -dest $.Extracts .                   
           
When extracting image data you should make a note of the number of frames
per chunk that are in the ARMovie which you're extracting from.  This 
information is on line 14.  This is so that when it comes to using Join
to build another ARMovie you are able to provide the correct number of
frames per chunk in your own header when using these images (the correct
number being exactly what it was in the first place).  A good indication
that you have the wrong number of frames per chunk in your header is that
when you play the ARMovie, the picture will start off o.k. and will then
become fuzzy and will then be o.k. and then become fuzzy, and so on.  

If you use Extract followed by Join and come to the conclusion that either
Extract or Join is not working as it should, you should first check that
your header is correct as this is usually the most likely source of error.



DIFFERENCES BETWEEN CURRENT VERSION (2.19) &  PREVIOUS VERSION:
--------------------------------------------------------------------

Wasn't checking to see if the last track was stereo or mono in multi-
track ARMovies.


OUTSTANDING:
-----------

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      
  
  