home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 16 / 16.iso / w / w023 / 3.ddi / FLI.001 / FLITAPE.DOC < prev    next >
Encoding:
Text File  |  1991-03-27  |  16.9 KB  |  451 lines
  1.  
  2. FLITAPE.EXE Version 1.02 2/24/91
  3. --------------------------------
  4.  
  5. Functional Specification for FLITAPE.EXE a 'FLI' file output program for
  6. single frame video recording devices.
  7.  
  8. Modification :
  9.     2/24/91 - cmc - first iteration
  10.     3/8/91    - cmc - "-?" prompting mode switch added
  11.     3/27/91 - cmc - addition of "go to timecode" in prompting
  12.     
  13. Usage : FLITAPE.EXE <file name> [options]
  14. Options are :
  15.      -h #    record a head of # frames
  16.      -t #    record a tail of # frames
  17.      -l #    record looping # times
  18.      -d #    record forcing duration of # frames
  19.      -[ #    beginning gap to recording
  20.      -] #    end gap after recording
  21.      -f     crop to fit shortest side of image to the display
  22.      -p     print running status
  23.      -s ScriptFile    Read from a script file
  24.      -r RecordFile    Create a record file
  25.      -c     configure drivers
  26.      -?     prompting mode
  27.  
  28.      
  29. Purpose :
  30.  
  31. FLITAPE.EXE is a command line driven program designed to read a ".FLI"
  32. file and output to a display and perform recording on single frame video
  33. recording devices.   This program will be able to read both original
  34. Autodesk Animator files and the new variable resolution "PJ" files.
  35.  
  36.  
  37. Requirements :
  38.  
  39. This program will be implemented as a "protected mode" 80386 application
  40. using ADI 4.1 or greater for its device interface.  The program will be
  41. able to optionally use an 80x87 math coprocessor.  The display portion of
  42. the program relies on an ADI "DEV_RD/DEC_RC" device.  The single frame
  43. recording portion relies on an ADI "VTPADI" device.
  44.  
  45. For a discussion of the environment variables and assumptions made by ADI
  46. device drivers see the appendix to this document.
  47.  
  48. Usage Message:
  49.  
  50. If the program is invoked with no arguments, a "usage banner" briefly
  51. describing the program's arguments will be printed on the screen.
  52.  
  53. The execution of the program can be terminated by the User by pressing any
  54. key on the keyboard.
  55.  
  56. Known Limitations :
  57.  
  58. 3/14/91 - Only NTSC non-drop frame time code is supported.  Both NTSC
  59. drop-frame and PAL should be included.
  60.  
  61. Default Performance :
  62.  
  63. When the program is invoked with no options, (only the FLI file name is
  64. specified), the following default performance will be executed.
  65.  
  66.     Verify that the file specified on the command line exists and can be
  67.     opened for read.  The integrity of the file is not verified at this
  68.     point although it is established later in the process.
  69.     
  70.     Establish communications with and initialize the DEV_RD display device
  71.     driver.
  72.     
  73.     Establish communications with and initialize the VTPADI VTR device driver.
  74.     
  75.     Open and check the integrity, length and speed of the specified FLI
  76.     file.
  77.  
  78.     Calculate the display mapping and initialize the required buffers
  79.     needed to display the frames of the FLI file on the DEV_RD display
  80.     device so that the longest side of the FLI maps entirely into the
  81.     display and so that aspect ratio will be preserved.
  82.     
  83.     Calculate the number of video frames to be recorded based on the length
  84.     and "speed" of the FLI file.  The "speed", sometimes referred to as
  85.     "jiffys" is expressed in term of milliseconds.  The "speed" to frame
  86.     rate is calculated so that values less than a video frame map to one
  87.     video frame, and values greater than one video frame round to the
  88.     nearest whole frame.
  89.     
  90.     Establish the current position (time code) of the VTR's tape and set
  91.     the edit "in-point" at default number of frames further along
  92.     (specified below) in order to allow for a reasonable preroll.
  93.     
  94.     Display the first frame of the FLI to the DEV_RD device.
  95.     
  96.     Perform an "insert edit" of the appropriate number of frames base on
  97.     the calculation above.
  98.     
  99.     Repeat the above two steps for each successive frame of the FLI file
  100.     until all FLI frames have been displayed and edited to tape.
  101.     
  102.     Advance the VTR media a default number of frames (specified below), in
  103.     order to provide a blank gap at the end of the recorded sequence.
  104.     
  105.     Release the VTR resource and driver.
  106.     
  107.     Release the display resource and driver.
  108.     
  109.     Close the FLI file.
  110.     
  111. Argument Description:
  112.     
  113.     In general, command line options are preceded by a '-' option switch,
  114.     they are not case sensitive, either upper or lower case works, and
  115.     they do not require a leading space character before their arguments.
  116.     
  117.     For example :
  118.         FLITAPE fli_name -D 30   
  119.             and
  120.         FLITAPE fli_name -d30
  121.             are equivalent
  122.     
  123. file name
  124.  
  125.     Mandatory file name whose the file name extension
  126.     determines the type of input file.  The available
  127.     input extensions are the following:
  128.  
  129.         *.fli   Animator/3D Studio image file
  130.  
  131.     Default:  The filename is mandatory, but if the
  132.           extension is missing, '.fli' is the assumed
  133.           extension.
  134.  
  135.     The exception to the mandatory need for a file name specified on the 
  136.     command line is when a "-?" switch (below) is used.
  137.     
  138.  -h #    record a head of # frames
  139.  
  140.      Record a "head" on the tape consisting of the first FLI frame appearing
  141.      on the tape for "#" frames.  As an example, if a 30 frame still image of
  142.      the first frame is desired at the beginning of the animation an option
  143.      of "-h 30" would be appropriate.
  144.      
  145.  -t #    record a tail of # frames
  146.  
  147.      Record a "tail" on the tape consisting of the last FLI frame appearing
  148.      on the tape for "#" frames.  As an example, if a 30 frame still image
  149.      of the last frame is desired at the end of the animation an option of
  150.      "-t 30" would be appropriate.
  151.      
  152.  -l #    record looping # times
  153.  
  154.      Record the FLI animation as a series of "film loop" segments.  This
  155.      option is useful for recording a short FLI file over and over on a
  156.      segment of tape.  If a recording of a FLI animation looping 9 times is
  157.      desired an option of "-l 9" would be appropriate.
  158.  
  159. -d #    record forcing duration of # frames
  160.  
  161.     Record the FLI animation using the specified duration instead of the
  162.     mapping of "jiffys" to frames described above.  This option is useful
  163.     for adjusting the absolute speed at which a FLI file "plays" on the
  164.     finished tape.  The duration is specified in terms of frames. 
  165.     
  166.     If the number of frames specified is less than the number calculated 
  167.     above, frames from the FLI will be discarded and the remaining frames 
  168.     will be recorded at one video frame each.  If the specified number is
  169.     greater than would calculated, every frame of the FLI will be recorded
  170.     for one or (typically) more video frames in order to achieve the desired
  171.     duration.  This later case has the effect of slowing the FLI down.
  172.     
  173.     The achieved duration applies to the number of frames a FLI file will
  174.     record irrespective of the "head", "tail", or "loop" specification. 
  175.     The total duration of the recorded sequence can be expressed as :
  176.     
  177.         Head Duration + (FLI Duration * Number of Loops) + Tail Duration
  178.         
  179. -[ #    beginning gap to recording
  180.  
  181.      This option over-rides the default "pre-roll gap".  This option is
  182.      useful when several FLI animations are being put on tape and no gaps
  183.      are desired between the various sequences.  In that case on option of
  184.      "-[ 0" is appropriate.  Conversely, a longer gap might be desired to
  185.      allow room for subsequent edits, e.g, "-[ 200" for a 200 frame gap.
  186.      
  187. -] #    end gap after recording
  188.      
  189.      This option over-rides the default "post-roll gap".  This option is
  190.      useful when several FLI animations are being put on tape and no gaps
  191.      are desired between the various sequences. In that case on option of
  192.      "-[ 0" is appropriate.  Conversely, a longer gap might be desired to
  193.      allow room for subsequent edits, e.g, "-[ 200" for a 200 frame gap.
  194.      
  195. -f     crop to fit shortest side of image to the display
  196.  
  197.     This option changes the mapping of the FLI image into the DEV_RD
  198.     display.  This option is useful when differences in image aspect ratio
  199.     between the FLI and the screen would cause a black space to be
  200.     displayed at the top and bottom of the screen, (sometimes called letter
  201.     box format).  When the "-f" option is specified, the shorter side of the
  202.     FLI image, usually the vertical, is mapped to cover entirely the
  203.     display screen.  This mapping often causes parts of the image on either
  204.     side to be cropped in order to preserve the pixel aspect ratio,
  205.     (keeping circles circular).
  206.  
  207. -p     print running status
  208.  
  209.      This option causes the program to print to the monitor (stdout), a
  210.      running status of the execution.  This option is useful if the DEV_RD
  211.      display is NOT the normal system monitor, (e.g., when a Targa is being
  212.      used).  The information provided by the "-p" option is helpful during
  213.      long recording sessions as a way to monitor progress.
  214.      
  215.      The information issued by the option includes :
  216.      
  217.          The command line as invoked.
  218.          The name of the FLI file being recorded.
  219.          The option in effect ( only those aspect which vary from the
  220.              default behavior ).
  221.          The position on tape where the animation starts.
  222.          A running commentary on progress, which frame of how many is being
  223.              recorded.
  224.          
  225.          See below for an example.
  226.          
  227. -s ScriptFile    Read from a script file
  228.  
  229.     This option causes the program to read a specified "script" file to be
  230.     used as a list of FLI files with options to record.  This feature is
  231.     useful for recording several FLI files at once.  The script file's
  232.     format is the same as the command line invocation.  The only difference
  233.     is that the name of the program is not included on lines of the script
  234.     file.
  235.     
  236.     The options specified in a given line of the script file are applied and
  237.     remain in effect only during the processing of that line of the file. 
  238.     Options specified on the command line apply to all lines executed from
  239.     the script file.
  240.     
  241.     As an example, give an invocation :
  242.         FLITAPE -s script.scp -[0 -]0
  243.         
  244.     And a file SCRIPT.SCP containing the following :
  245.         FLIONE.FLI -D 30 -h60
  246.         FLITWO.FLI -D 90 -L3 -t60
  247.         
  248.     The program will record FLIONE with 0 length beginning and end gaps, a
  249.     duration of 30, and a head recording of 60 frames.  It will then record
  250.     FLITWO with 0 length beginning and end gaps, (abuts to FLIONE), a
  251.     duration of 90 frames, over 3 loops, with a tail of 60 frames.
  252.     
  253.     When a script file is specified on the command line, the otherwise
  254.     mandatory FLI file name is not required.
  255.     
  256.     The following options are NOT honored in a script file.  If desired
  257.     they must be specified on the command line. If encountered in a script 
  258.     they will be ignored.
  259.     
  260.         -p print running status
  261.         -r RecordFile (below)
  262.         -s ScriptFile (this option)
  263.         -c configure drivers (below)
  264.  
  265.     Before the first line of the script file is executed and recording
  266.     begins, every line of the script file is checked for consistency and
  267.     the FLI files are checked.
  268.     
  269. -r RecordFile    Create a record file
  270.  
  271.     This option is similar to the Print running status option above except
  272.     that the output is sent to the specified file.
  273.     
  274.     In addition to the information from the "-p" option, the log file
  275.     contains the start time and completion time.  This information is
  276.     useful for billing or other future reference.
  277.     
  278. -c     configure drivers
  279.  
  280.     This option causes the program to "configure" first the ADI VTPADI VTR
  281.     driver, and then the DEV_RD display driver.  The configuration is done
  282.     in order to change the characteristics of an ADI driver.  The content of
  283.     the configuration dialogue is device driver specific.
  284.     
  285. -?        prompting mode
  286.     
  287.     This option causes the program to be invoked in an interactive
  288.     mode of operation.  When the "-?" switch is used, the User is take 
  289.     sequentially through two interactive sections, the first for tape control 
  290.     and positioning and the second for specification and correction of
  291.     the usual command line parameters.  If this switch is being used
  292.     a file name need not be specified on the command line although
  293.     neither the "-s Script" or "-c Configure" switches are honored.
  294.     All other parameters specified on the command line are taken as the
  295.     current values shown in the entry/modification section below.
  296.     
  297.     The tape positioning section provides for the direct control of the
  298.     VTR from the number keypad section of the keyboard.  The left and
  299.     right arrow keys provide "shuttle" operation forward and backward.
  300.     These two keys also have shifted use.  When just the arrow keys are
  301.     pressed the VTR will shuttle at a rate slower than regular play speed.
  302.     This is sometimes called a creep.  If the shift key is held down while
  303.     the arrow key is depressed, the VTR will shuttle at the fastest 
  304.     available speed.
  305.  
  306. -------------------------------
  307. |   Home    |     |    PgUp    |
  308. | (FastRev) |     |  (FastFwd) |
  309. -------------------------------
  310. |   <-      |     |     ->     |
  311. | (ShutRev) |     |  (ShutFwd) |
  312. -------------------------------
  313. |   End     |     |    PgDn    |
  314. | (StepRev) |     |  (StepFwd) |
  315. -------------------------------
  316. |      Ins        |    Del     |
  317. |     (PLAY)      |   (STOP)   |
  318. -------------------------------
  319.     ENTER     to exit
  320.     ?    Current time code position
  321.     G    Go to a time code position
  322.     +    Menu
  323. Current position is 00:02:50:19
  324.  
  325.             
  326.     The parameter entry section prompts for the normally setable parameters
  327.     that control the operation of the program.  If a valid FLIC file name 
  328.     is not specified the User is given the option of exiting the program.
  329.     Once the parameters have been entered the User is given an opportunity
  330.     to modify them.  Once the parameters have been set the User is given one
  331.     final opportunity to exit the program before the recording session 
  332.     begins.
  333.     
  334.     For all parameters shown in this section, the current value is
  335.     presented as part of the prompt for a new value.  Pressing the enter
  336.     key accepts the parameter.
  337.     
  338. Example -
  339.  
  340.     command line : FLITAPE -?
  341.     
  342. FLIC file name  ? 
  343. Number of blank frames before recording :  [150] ? 
  344. Number of frames in HEAD :  [0] ? 
  345. Animation duration in frames :  [32] ? 
  346. Number of frames in TAIL :  [0] ? 
  347. Number of loops to record :  [0] ? 
  348. Number of blank frames after recording :  [30] ? 
  349. Fit image within screen area [Yes]/No ? 
  350. Display running status  Yes/[No] ? 
  351. Do you want to change any value Yes/[No] ? 
  352.  
  353. Start Recording [Yes]/No ? 
  354.  
  355.  
  356. Appendix -
  357. ==========
  358.  
  359. ADI Drivers :
  360.  
  361. Protected mode '386 drivers as used in this program are delivered in the
  362. form of ".EXP" files, essentially programs, which provide device
  363. interfaces in a device independent way.
  364.  
  365. In order for the application program to find and bind at runtime with the
  366. appropriate drivers of the required classes, e.g., Display, VTR
  367. controller, a three file search is instituted.
  368.  
  369. The first level of search is for a file in the current directory of a
  370. specific name.  In the case of display drivers the name is ADISDP.EXP and
  371. in the case of VTR controllers the name is ADIVTR.EXP.
  372.  
  373. If this search is not satisfied, the current environment is searched for a
  374. "SET" variable equating an environment string to a file name.  This is
  375. the preferred method of naming an ADI driver.  In the case of a display
  376. driver the environment variable is RDPADI and for VTR controllers it is
  377. VTPADI.  This name mapping can be accomplished by including 
  378. "SET <name>=<drivername>" statements in you AUTOEXEC.BAT or by issuing
  379. the SET command from the DOS command line.
  380.  
  381. The SET variable mapping is as follows.
  382.  
  383. In the case of the display driver :
  384.     SET RDPADI=<drivername>
  385. In the case of the VTR controller :
  386.     SET VTPADI=<drivername>
  387.         where driver name is a full path name to the appropriate device
  388.         driver.
  389.  
  390. The final stage of the search is to query the User directly from the
  391. program.  An appropriate error advisory is issued and the User is asked to
  392. name the full path and name to indicate the required driver.
  393.  
  394. Sample "print running status" output :
  395.  
  396. invocation -> flitape short -p -d 30 -h10 -t10 -l3
  397.  
  398. Recording SHORT.FLI
  399. Record Head of 10 frames
  400. Record Tail of 10 frames
  401. Record 3 loops
  402. User specified duration of 30 frames
  403.     sequence starts at 01:02:08:04
  404.  
  405.     head of 10 frames
  406.     FLI frame #1 of 3 on 10's
  407.     FLI frame #2 of 3 on 10's
  408.     FLI frame #3 of 3 on 10's
  409.     tail of 10 frames
  410.     
  411. Sample "record output file" output :
  412.  
  413. invocation -> flitape short -p -d 30 -h10 -t10 -l3 -rlogfile
  414.  
  415. D:\SAMPLE\FLITAPE.EXE short -p -d 30 -h10 -t10 -l3 -rLOGFILE 
  416. Recording SHORT.FLI
  417. Record Head of 10 frames
  418. Record Tail of 10 frames
  419. Record 3 loops
  420. User specified duration of 30 frames
  421. Log to record file LOGFILE
  422. Start time :     08:47:56 PM    02/24/91
  423.     sequence starts at 01:02:08:04
  424. Finished at :     08:50:05 PM
  425.  
  426. Default Values :
  427.  
  428. Beginning Gap  150 frames
  429. End Gap         30 frames
  430. Version        0.01
  431. default FLI extension ".FLI"
  432. Head Length     0 frames
  433. Tail Length     0 frames
  434.  
  435. Error Messages :
  436.  
  437. The following are issued on encountering fatal program errors and
  438. termination conditions.
  439.  
  440.         Cannot open script file <script file name>
  441.         Display initialization fail! (on display initialization failure)
  442.         No Tape init        (on VTR driver initialization failure)
  443.         Tape initialization error (on VTR device initialization failure)
  444.         Error opening <fli file name>
  445.         Memory allocation error (on internal allocation errors)
  446.         VTR error    (generic VTR abort message)
  447.         User Termination    (on User keyboard termination)
  448.         
  449.         
  450.  
  451.