home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 29 Fixes_o / 29-Fixes_o.zip / avc0493.zip / README.DVI < prev    next >
Text File  |  1992-07-23  |  37KB  |  768 lines
  1.  **************************** File: README.DVI *******************************
  2.  
  3.  AVC Release 1.05  April 1992
  4.  ----------------------------
  5.  
  6.  This information describes how an Audio Visual Connection* (AVC) story can
  7.  display Digital Video Interactive** (DVI**) files.  DVI is supported in the
  8.  OS/2* environment only.
  9.  
  10.  This documentation is organized into these parts:
  11.  
  12.    1. DVI overview
  13.    2. Requirements (hardware and software)
  14.    3. Installation
  15.    4. AVC stories to help you get started
  16.    5. AVA DVI Instructions
  17.    6. Error Codes
  18.  
  19.  ------------------------------------------------------------------------------
  20.  1. DVI OVERVIEW ==============================================================
  21.  
  22.  You can now create stories in AVC that, with DVI support, will display video,
  23.  play audio, and display still image files created with DVI technology.  DVI
  24.  digital files are decompressed and played back via the ActionMedia** II
  25.  Display Adapter under control of an AVC story.  AVC-DVI support is provided
  26.  for the OS/2 environment only.
  27.  
  28.  You can display your story output in three different ways:
  29.  
  30.    o Combine DVI images and AVC images on one PS/2 monitor
  31.    o Display DVI images on one PS/2 monitor and AVC images on another
  32.    o Display DVI images on a television monitor (NTSC or PAL output) and
  33.      AVC images on a PS/2 monitor
  34.  
  35.  AVC can play DVI still images and video clips, but there is no edit or
  36.  capture capability within AVC.  Video file types supported by the ActionMedia
  37.  II Adapter include any 9-bit PLV (Production-Level Video) or RTV (Real Time
  38.  Video) with ADPCM or PCM audio components of various sampling rates.
  39.  
  40.  If you want to capture an RTV video clip file you could, for example, use the
  41.  OS/2 program CAPTURE from the ActionMedia Toolkit.  To get a PLV video clip
  42.  file, you must contact a company, licensed by the Intel Corporation, that can
  43.  produce PLV files.
  44.  
  45.  DVI still file images supported by the ActionMedia II Adapter include:
  46.  
  47.    o 9-bit compressed (includes JPEG format) and uncompressed stills
  48.    o 16-bit compressed and uncompressed stills
  49.  
  50.  Note: JPEG=Joint Photographic Experts Group standard (ISO document CD10918-1)
  51.  
  52.  If you want to capture DVI still image files, one possibility is to use the
  53.  OS/2 program SNAPSHOT from the ActionMedia Toolkit.
  54.  
  55.  You can display multiple DVI still images at the same time, but you can only
  56.  play one video clip at a time on the screen.  See Section 4 of this file
  57.  for a description of the AVA instructions that play DVI files in your story
  58.  and that manipulate visual and audio effects.
  59.  
  60.  When DVI images are displayed on a monitor that already has an AVC image, the
  61.  DVI image behaves as if it is on another plane behind the AVC image.  The DVI
  62.  image will "show through" the transparent area of the AVC image currently on
  63.  the screen.  (The transparent area is where the color is black, or the RGB
  64.  color values are equal to 0.)  The DVI images can show through (be overlaid
  65.  on) the following AVC image types:
  66.  
  67.    o 8514/A (XGA)   (640x480x256 colors)
  68.    o VGA            (640x480x16 colors)
  69.    o VGA8           (360x480x256 colors)
  70.  
  71.  Note:  AVC MCGA images (320x200x256 colors) can be used in your AVC story
  72.  but cannot be displayed simultaneously with DVI video or still images.
  73.  
  74.  ------------------------------------------------------------------------------
  75.  2. REQUIREMENTS (HARDWARE AND SOFTWARE) ======================================
  76.  
  77.    o Computer with 80386SX (or higher level of processor)
  78.    o OS/2 1.3
  79.    o ActionMedia II Display Adapter
  80.    o ActionMedia II Capture Option (for live video monitoring)
  81.    o ActionMedia II device drivers for OS/2 1.3
  82.    o VGA or XGA adapter
  83.  
  84.  LIMITATIONS:
  85.  
  86.  1. AVC-DVI does not support the 8514/A graphics adapter.  All 8514/A image
  87.  files are supported by AVC via the XGA adapter.
  88.  
  89.  2. The M-Motion Adapter cannot coexist with the ActionMedia II Adapter.
  90.  
  91.  3. DVI audio output is directed to the ActionMedia II audio output connector
  92.  only.  If your story plays sound through both DVI and the Audio Capture
  93.  and Playback Adapter (ACPA), you will need either separate speakers or an
  94.  audio mixer.
  95.  
  96.  4. You can have only one DVI application running on a PS/2.  You must stop
  97.  any DVI application that is running before starting another one.
  98.  
  99.  ------------------------------------------------------------------------------
  100.  3. INSTALLATION ==============================================================
  101.  
  102.  Step 1:  Refer to IBM PS/2* ActionMedia II Display Adapter installation
  103.  instructions for how to install the adapter card and the device drivers.
  104.  Your OS/2 CONFIG.SYS file will be automatically modified with the latest
  105.  device driver information.  The driver file AVD.SYS will normally be defined
  106.  to reside in the following directory in your CONFIG.SYS file:
  107.  
  108.                   C:\AM2\DRIVERS
  109.  
  110.  Step 2:  Be sure to run the OS/2 ActionMedia II Configuration and Confidence
  111.  Test to verify that the monitor(s) and video cables have been installed
  112.  correctly.  There are two ways you can set it up.  (1) Use the ActionMedia II
  113.  Video Cable (Y-shaped) to merge the PS/2 system video and the DVI video for a
  114.  single monitor.  (2) Connect the ActionMedia II's Video Cable Output Connector
  115.  or its Auxiliary Video Output Connector (a TV signal referred to as S-VHS,
  116.  S-Video, or Y/C output -- either NTSC or PAL) to a separate monitor for
  117.  displaying the DVI signal.
  118.  
  119.  Note: NTSC is the television standard of the National Television Standards
  120.  Committee. PAL is the Phase Alternating Line standard.
  121.  
  122.  The DVI initialization file AVK.INI, which is in the same subdirectory as the
  123.  driver file AVD.SYS, is automatically set up with several operating values
  124.  during this step.
  125.  
  126.  Step 3:  Follow the instructions for installing AVC and answer "Yes" to the
  127.  question on AVC/DVI support.  This step installs the file AVCDVI.DLL in the
  128.  AVC directory SYSTEM.!AV; and a new KMVLOL.DLL is copied to the ActionMedia
  129.  DLL subdirectory to override the version 1.0 KMVLOL.DLL that comes with your
  130.  adapter installation, and the file AVK.INI in the ActionMedia DRIVERS
  131.  subdirectory is also modified.  You can use an ASCII editor to edit the file
  132.  AVK.INI to make sure that the [DebugMvl] parameter is changed to the following
  133.  value:
  134.                   Flag4=4
  135.  ------------------------------------------------------------------------------
  136.  4. AVC STORIES THAT HELP YOU GET STARTED =====================================
  137.  
  138.  Once AVC-DVI support is installed, try some of the following basic examples
  139.  of AVC stories.  This example plays a video clip file named AIRPLANE.AVS
  140.  after the image file CLOUD is displayed:
  141.  
  142.      |  AVA Statement                   |Method |Dir |Line |Wait |Size |
  143.  
  144.                                      /* AVC Image in VGA,VGA8, or XGA mode */
  145.       SHOW   "C:\IMAGE\CLOUD"                                  0
  146.       DPLAY  "C:\VIDEO\AIRPLANE.AVS" /* Video sequence */
  147.       WAIT KEY
  148.  
  149.  Note:  The file name must include the drive and directory when playing files
  150.  from various drives and directories.  A file can be played from your hard
  151.  disk, CD-ROM drive, any other magneto-optical media, or LAN drive supported
  152.  by OS/2.  The WAIT KEY statement prevents the story from ending until the
  153.  video play is finished.
  154.  
  155.  Depending on the contents of the image CLOUD, this story will both display and
  156.  block out portions of the DVI video image AIRPLANE "through" the AVC image.
  157.  The DPLAY instruction displays the AIRPLANE.AVS video anywhere in the AVC
  158.  image CLOUD that contains the transparent color (black).  In places where the
  159.  image file CLOUD does not have the transparent color the corresponding part of
  160.  the video image is blocked out.
  161.  
  162.  The following story displays a DVI still-image file FLOWER overlaid by the AVC
  163.  image CLOUD:
  164.  
  165.      |  AVA Statement                   |Method |Dir |Line |Wait |Size |
  166.  
  167.                                      /* AVC Image in VGA,VGA8, or XGA mode */
  168.       SHOW   "C:\IMAGE\CLOUD"                                  0
  169.       DSHOW  "C:\STILLS\FLOWER.AVS"  /* Video still image */
  170.       WAIT KEY
  171.  
  172.  Note:  The DVI FLOWER.AVS still-image file is decompressed and displayed by
  173.  the ActionMedia II Adapter.  Like DVI video, DVI stills can also be displayed
  174.  concurrently with AVC images in your story.  The DVI still-image FLOWER will
  175.  "show through" the transparent (black) color in the AVC image CLOUD.
  176.  
  177.  Reminder:  Your AVC story must be in one of the 3 graphics modes (VGA, VGA8,
  178.  or 8514/A (XGA)) before you can display a DVI video or still.  You cannot, for
  179.  example, start DVI video or still, following a text mode line or an image in
  180.  MCGA mode.
  181.  
  182.  To display 100% of the DVI video (no part blocked by an AVC image) you can
  183.  use any one of these methods:
  184.  
  185.    o An AVA CLEAR BLACK instruction  (your AVC PROFILE must be set to one of
  186.      the three acceptable graphic modes)
  187.    o Use SHOW to display a black image
  188.    o SHOW any image with Method set to none
  189.  
  190.  Examples:
  191.  
  192.      |  AVA Statement                   |Method |Dir |Line |Wait |Size |
  193.       /* Using CLEAR */
  194.       CLEAR BLACK                                              0
  195.       DPLAY  "C:\VIDEO\AIRPLANE.AVS"
  196.       WAIT KEY
  197.  
  198.       /* Setting Method to none */
  199.       SHOW   "C:\IMAGE\CLOUD"            none                  0
  200.       DPLAY  "C:\VIDEO\AIRPLANE.AVS"
  201.       WAIT KEY
  202.  
  203.  Another good way to get started is to look at the sample story SEEDVI, which
  204.  is available in the USEFUL application (in the directory USEFUL.!AP).  The
  205.  SEEDVI story is shipped with AVC and assumes that you have certain sample DVI
  206.  files (shipped with the ActionMedia II drivers).  You can also use this story
  207.  to help you display your own DVI video clips by changing the path and file
  208.  names called in the DPLAY instructions in SEEDVI.
  209.  
  210.  When you start creating more complex stories you should understand that the
  211.  video started by DPLAY runs concurrently with the story instructions that
  212.  follow the DPLAY (such as displaying images, showing text, or playing music
  213.  via the ACPA card).  The computer will switch automatically between the tasks
  214.  of playing the video and story instructions that follow the DPLAY.  As the
  215.  story author, you will need to use instructions, such as WAIT (waits for key
  216.  or for a specific video frame number) and DQUERY (finds out the current
  217.  playing status) to control story synchronization.  This prevents the video
  218.  from getting out of synchronization with the rest of the AVC story.
  219.  Synchronization can be affected by both the speed of the computer running the
  220.  story and the demands made on the computer by your story.
  221.  
  222.  ------------------------------------------------------------------------------
  223.  5. AVA DVI INSTRUCTIONS ======================================================
  224.  
  225.  The AVA instructions for AVC-DVI support are:
  226.  
  227.        o DCONFIG - Controls your DVI profile
  228.        o DLOCATE - Defines source image size and target image size/location
  229.        o DPAUSE  - Pauses a video sequence
  230.        o DPLAY   - Plays a DVI video file or monitors live video
  231.        o DQUERY  - Returns the current frame number and play status
  232.        o DSTATE  - Saves current or restores previous state values
  233.        o DSTEP   - Advances the DVI video one frame
  234.        o DSTOP   - Stops the DVI video or audio
  235.        o DSHOW   - Displays a DVI still image
  236.        o WAIT D  - Waits for a specific video frame number is reached
  237.  
  238.  
  239.  The AVA syntax for each DVI instruction follows:
  240.  ------------------------------------------------------------------------------
  241.  5.1 DCONFIG state_item value
  242.  
  243.  All state items (except MON) set with DCONFIG can be changed at any time
  244.  within an AVA story and will be reflected immediately in the current or
  245.  subsequent play of DVI files.
  246.  
  247.  If you specify an unrecognized state_item, the program will generate a
  248.  non-zero return code.  If you specify an unrecognized value for any of the
  249.  state_item values, the program will use the default value.
  250.  
  251.  Note: All negative values must be enclosed in quotes or parenthesis.
  252.  
  253.    STATE_ITEM      VALUES
  254.    -------------   ------------------------------------------------------------
  255.       RES          value= LOw or HIgh   (DEFAULT: low)
  256.  
  257.                    Low  (The monitor screen is represented by the 256x240
  258.                          resolution DVI plane)
  259.                    High (The monitor screen is represented by the 512x480
  260.                          resolution DVI plane)
  261.  
  262.                    RES defines the resolution of the DVI screen where upon
  263.                    video or stills are displayed.  High resolution has 4 times
  264.                    as many pels as does low resolution, therefore high
  265.                    resolution produces better quality images.
  266.  
  267.                    The video sources are normally sized 256x240.  When this
  268.                    size is played on a low resolution screen (256x240), it
  269.                    covers the entire screen; when it is played on a high
  270.                    resolution screen (512x480), it covers only 1/4 of the
  271.                    entire screen.
  272.  
  273.                    The DVI still images can be various dimensions, but normally
  274.                    the largest dimension used is 512x480.  When a still image
  275.                    (sized 512x480) is shown on either a low resolution screen
  276.                    (256x240) or a high resolution screen (512x480), it can
  277.                    cover the entire screen area.
  278.  
  279.                    Note:  The DVI plane resolution is independent of the
  280.                    resolution of the AVC image that it appears with (either
  281.                    VGA or XGA).
  282.  
  283.                    Example:  DCONFIG RES High
  284.       ----------   ------------------------------------------------------------
  285.       SPD          value= Any percentage from 1 to 100 (DEFAULT: 100)
  286.  
  287.                    SPD determines video play speed.  Specified as a percentage
  288.                    of full speed.  If speed is not 100%, audio is muted.
  289.  
  290.                    Example:  DCONFIG SPD 50
  291.       ----------   ------------------------------------------------------------
  292.       MON          value= ONE, TWO, NTSC, or PAL  (Default: ONE)
  293.  
  294.                    MON sets the number and type of monitor that the AVC
  295.                    story (DVI video or still images) plays on.
  296.  
  297.                    When the value ONE is specified (default), the DVI image
  298.                    plane is displayed through the transparent color (black) of
  299.                    the AVC image plane.  This option requires that you use the
  300.                    ActionMedia II Video Cable to combine the DVI and AVC image
  301.                    signals for one monitor.
  302.  
  303.                    When the value TWO is specified, the AVC Story Tables and
  304.                    images are shown on the monitor connected to your graphics
  305.                    adapter (either VGA or XGA).  The DVI images are displayed
  306.                    on another monitor that is attached to the Video Cable
  307.                    Output Connector (from the ActionMedia II Adapter).
  308.                    However, with this setting, if you use the Video Cable
  309.                    (Y-shaped) to connect to just one monitor, you will see only
  310.                    the DVI images.
  311.  
  312.                    When either NTSC or PAL is specified, two monitors are
  313.                    assumed.  The AVC Story Tables and images are shown on the
  314.                    monitor connected to your graphics adapter (either VGA or
  315.                    XGA).  The DVI images are displayed on the television
  316.                    monitor using the TV input signal (available from the
  317.                    Auxiliary Video Output Connector of the ActionMedia II
  318.                    adapter).  The DVI video output signal is either NTSC or
  319.                    PAL, based on what you specify.
  320.  
  321.                    Notes:
  322.                    1. Be sure to run the ActionMedia II Configuration program
  323.                    and set the displays and cable connection properly before
  324.                    using the MON state_item in an AVC story.
  325.  
  326.                    2. When state_item = NTSC or PAL, the monitor resolution
  327.                    can only be LOW.
  328.  
  329.                    Example:  DCONFIG MON NTSC
  330.  
  331.       ----------   ------------------------------------------------------------
  332.       VOL          value= Any percentage from 0 to 100   (Default 100)
  333.  
  334.                    VOL controls the DVI audio volume.
  335.  
  336.                    Example:  DCONFIG VOL 50
  337.       ----------   ------------------------------------------------------------
  338.       BAL          value= Any number from -100 to 100   (Default: 0)
  339.  
  340.                    BAL controls the audio balance in the left and right
  341.                    speakers.
  342.  
  343.                    The value 0 plays the DVI audio equally from both speakers.
  344.                    The value -100 plays the audio from the left speaker only.
  345.                    The value 100 plays audio from the right speaker only.
  346.  
  347.                    Example:  DCONFIG BAL 50   (Right speaker dominant)
  348.       ----------   ------------------------------------------------------------
  349.       A_V          value= AV, A, V, or None    (Default: AV)
  350.  
  351.                    A_V controls the playing of DVI audio and video.
  352.  
  353.                    AV    plays video and audio
  354.                    A     plays audio only
  355.                    V     plays video only
  356.                    None  suppresses video and audio.
  357.  
  358.                    A_V lets you, for example, suppress the DVI audio component
  359.                    of a video file; letting the user have silence or audio from
  360.                    another source.  The other source might be audio controlled
  361.                    via the ACPA card.  Similarly, you could suppress the DVI
  362.                    video and use the DVI audio to accompany other AVC graphics.
  363.                    Or you could suppress both audio and video, playing the
  364.                    sequence in the background until reaching a specific frame
  365.                    position of the DVI file.
  366.  
  367.                    These options do not affect DVI still-image display.
  368.  
  369.                    Example:  A_V None
  370.       ----------   ------------------------------------------------------------
  371.       ERS          value= Yes or No   (Default: No)
  372.  
  373.                    ERS controls whether the previously displayed DVI file image
  374.                    is erased or not (at the next DLOCATE T instruction).
  375.  
  376.                    ERS NO leaves the previous frame of the video or still image
  377.                    "frozen" on the display.  This lets you overlay DVI images.
  378.  
  379.                    ERS YES removes the previous DVI frame when the next
  380.                    DLOCATE T instruction is issued.  This lets you move the
  381.                    DVI display area.  (It removes the old display from the
  382.                    screen.)
  383.  
  384.       Example:
  385.  
  386.         DCONFIG ERS No            /* Set ERS to No
  387.         DLOCATE T 0 0 50 50       /* Locate image at top 1/4 screen
  388.         DSHOW "C:\STILLIMG.AVS"   /* Show a DVI still image
  389.         WAIT 5                    /* Wait 5 seconds
  390.         DLOCATE T 50 50 50 50     /* Locate video at bottom 1/4 screen
  391.         DPLAY "C:\VIDEO.AVS"      /* Show full motion video
  392.         WAIT 5                    /* Wait for 5 seconds
  393.         SHOW  "C:\IMAGE\OVER1"    /* Show AVC image OVER1 superimposed on video
  394.  
  395.       ----------   ------------------------------------------------------------
  396.       CON          value= Any number from -100 to 100   (Default: 0)
  397.  
  398.                    CON adjusts the monitor contrast for DVI images.
  399.  
  400.                    The value -100 provides minimum contrast.
  401.                    The value 100 provides maximum contrast possible.
  402.  
  403.       Example:
  404.  
  405.         DCONFIG CON (-10)
  406.       ----------   ------------------------------------------------------------
  407.       SAT          value= Any number from -100 to 100   (Default: 0)
  408.  
  409.                    SAT adjusts the monitor color saturation value.
  410.  
  411.                    The value -100 displays a monochrome DVI image.
  412.                    The value 100 creates maximum color saturation of an image.
  413.  
  414.       Example:
  415.  
  416.         DCONFIG CON (-100)        /*  Initial contrast at -100
  417.         DCONFIG SAT (-100)        /*  Initial saturation at -100
  418.         DPLAY "C:\VIDEO.AVS"      /*  Start video
  419.         Do i = -100 to 0
  420.             DCONFIG CON i         /*  Fade in video
  421.             DCONFIG SAT i
  422.             WAIT .1
  423.         END
  424.       ----------   ------------------------------------------------------------
  425.       TIN          value= Any number from -100 to 100   (Default: 0)
  426.  
  427.                    TIN controls the monitor tint adjustment.
  428.  
  429.                    The value -100 is maximum green.
  430.                    The value 100 is maximum red.
  431.       ----------   ------------------------------------------------------------
  432.       BRI          value= Any number from -100 to 100   (Default: 0)
  433.  
  434.                    BRI controls the monitor brightness adjustment.
  435.  
  436.                    The value -100 is the darkest possible.
  437.                    The value 100 is maximum brightness.
  438.  
  439.       Example:
  440.  
  441.         DO i = -80 to 80
  442.             DCONFIG BRI i         /*  Video brightness transition
  443.         END
  444.  
  445.  ------------------------------------------------------------------------------
  446.  5.2 DLOCATE option parameters
  447.  
  448.                    DLOCATE defines what part of the rectangular DVI source
  449.                    image to display, and the size and location of the
  450.                    rectangular area where the target image will be shown on
  451.                    the screen.  Both stills or video clips can be controlled
  452.                    by this instruction.  Options are S or T.
  453.  
  454.      OPTION        PARAMETERS
  455.  ---------- ----------------------------------------------------------------
  456.       S            x [y  [xd   [yd] ] ]   (Defaults: 0  0  100-x 100-y)
  457.  
  458.                    x, y, xd, and yd can be any percentage from 0 to 100
  459.  
  460.                    x and y designate the upper left coordinate of the source
  461.                    (DVI image) rectangle in a percentage relative to the
  462.                    entire source image.
  463.  
  464.                    xd and yd designate the width and height of the source (DVI
  465.                    image) rectangle in a percentage relative to the entire
  466.                    source image.
  467.  
  468.                    Note:  x+xd must not exceed 100; y+yd must not exceed 100.
  469.      Examples:
  470.                DLOCATE S 0 0 100 100     /* Default full size source
  471.                DLOCATE S 25 25 50 50     /* middle quarter of the source
  472.  
  473.  ---------- ----------------------------------------------------------------
  474.       T            x [y [xd [yd] ] ]   (Defaults:  Same as source values)
  475.  
  476.                    x, y, xd, and yd can be any value from 0 - 100.
  477.  
  478.                    x and y designate the upper left coordinate of the target
  479.                    display rectangle as a percentage of the full screen.
  480.  
  481.                    xd and yd designate the width and height of the target
  482.                    display rectangle as a percentage of the full screen.
  483.  
  484.                    Note:  If target xd is provided, but target yd is not,
  485.                    target xd is used as the value for yd.
  486.  
  487.                    Examples:  At Low resolution (256x240), the following
  488.                    DLOCATE instruction displays a 256x240 DVI video or still
  489.                    in full screen.
  490.  
  491.                    DLOCATE T 0 0 100 100
  492.  
  493.                    The following DLOCATE instruction displays a 256x240 DVI
  494.                    video or still image in the center of the screen (covering
  495.                    1/4 of the screen):
  496.  
  497.                    DLOCATE T 25 25 50 50
  498.  
  499.                    Note:  The DLOCATE T instruction can resize (reduce) DVI
  500.                    sources (video or stills) to display them in an small target
  501.                    area, but it cannot enlarge them to fit an over-sized target
  502.                    area.  When a target area is larger then the size of the
  503.                    source, the source is displayed starting at the upper left
  504.                    corner of the defined target area.
  505.  
  506.       Example:
  507.  
  508.                            /* This story displays a shrinking target rectangle
  509.          DCONFIG RES LOW
  510.          DPLAY  "C:\AIRPLANE.AVS"                /* Select image to display
  511.          DO i=0 to 100 by 2
  512.             DLOCATE T i i 100-i-i 100-i-i        /* Resize (shrink) the target
  513.             WAIT .3
  514.          END
  515.  ------------------------------------------------------------------------------
  516.  5.3 DPAUSE
  517.  
  518.      DPAUSE freezes the video input.  Subsequent DPAUSE or DPLAY statements
  519.      will restart the video.  When video play resumes, it uses the parameter
  520.      values defined by the last DLOCATE instruction.
  521.  
  522.      Note:  The user can press the backspace key to pause and restart video
  523.      during the DPLAY.  (The backspace key is used in AVC to pause a story.)
  524.  
  525.  ------------------------------------------------------------------------------
  526.  5.4 DPLAY [source_file | @dMonitor] [S]
  527.  
  528.      The DPLAY instruction plays the specified DVI video or audio file,
  529.      or monitors live video with the ActionMedia II Capture Option.  A
  530.      source_file need not be specified if the DPLAY follows a DPAUSE.  The
  531.      DPLAY, in this case, restarts the paused file.
  532.  
  533.      The name source_file is the DVI video or audio file to be played,
  534.      designated by its fully qualified path name.  For example:
  535.      C:\VIDEO\TREES.AVS.  For a list of file types supported, see section 1
  536.      of this document.
  537.  
  538.      You can issue an AVC SHOW or PASTE instruction either before or during a
  539.      video DPLAY sequence.  In this way you can overlay various AVC images on
  540.      the DVI video.
  541.  
  542.      The DPLAY option for DVI files available is: S (synchronous)
  543.  
  544.      The default mode of DPLAY instruction is asynchronous, or interruptible.
  545.      When video is played asynchronously, the computer system will play the
  546.      video and serve other AVC tasks within the system.  This could, however,
  547.      cause any time-consuming task to interfere with other tasks.  For
  548.      example, a DPLAY instruction could be followed by another story line that
  549.      interferes with the video being played -- including, perhaps, changes to
  550.      the video color, speed, and display location.
  551.  
  552.      DPLAY can be used in "pass-through" mode to monitor the analog video
  553.      input from the ActionMedia II Capture Option directly.  The instruction
  554.      is
  555.  
  556.          DPLAY @dMonitor
  557.  
  558.      Either NTSC or PAL inputs from the ActionMedia II Capture Option can be
  559.      shown on the designated PS/2 monitor.  Like DPLAY with DVI files, DPLAY
  560.      @dMonitor can also have AVC image and text overlaid.  It can also be
  561.      stopped by DSTOP, another DPLAY or DSHOW, or by the Esc key.  Under such
  562.      live video monitoring operation, it is always full screen with high
  563.      resolution, and always asynchronous.  It is not subject to the control of
  564.      DCONFIG or DLOCATE.
  565.  
  566.      The monitored source could be from a camera, a VCR or a laser disk player.
  567.      In case it comes from a RS-232C controlled videodisc player, commands
  568.      such as MPLAY, MSEEK, etc. can also be used even though there is no
  569.      M-Motion Adapter plugged in PS/2.
  570.  
  571.      Notes:
  572.  
  573.      1. During a DPLAY sequence all AVC images must be of the same mode (either
  574.      VGA, VGA8 or XGA (8514/A)).  The AVC image mode can only be switched after
  575.      a DPLAY is finished and prior to the next DPLAY.  Switching the AVC
  576.      image mode during a video play stops the video play sequence.
  577.  
  578.      2. To avoid unpredictable display behavior, do not switch to another OS/2
  579.      Presentation Manager session (pressing the Ctrl+Esc keys) while video is
  580.      displayed on the screen.
  581.  
  582.      OPTION
  583.      ------   ----------------------------------------------------------------
  584.  
  585.       S       You can play a video file without interruption by using the
  586.               synchronous (S) option.  For example:
  587.  
  588.               DPLAY  "C:\AIRPLANE.AVS"  S   /* play video without interruption
  589.               DCONFIG VOL 50                /* volume change request
  590.  
  591.               When you use the synchronous option, the computer system will
  592.               devote all of its time to playing the video (until all the frames
  593.               of the file are finished).  The video will not be interrupted
  594.               unless the user presses the Esc key and then the Ctrl+Break keys.
  595.  
  596.               Because the video cannot be interrupted by other AVC tasks in the
  597.               system, the video will play more efficiently.  This is a useful
  598.               option when you want the video to finish before running any of
  599.               the following instructions in the story, or you are playing video
  600.               on a slow machine, or you are playing video files that are from a
  601.               slow LAN server.  In the above example, the line: DCONFIG VOL 50
  602.               will change the volume percentage only after the video has
  603.               finished playing.
  604.  
  605.               CAUTION:  No other AVC task will start while video is played
  606.               using this option.
  607.  
  608.  --------------------------------------------------------------------------
  609.  5.5 DQUERY
  610.  
  611.      DQUERY returns the current frame number and play status in these AVA
  612.      variables:
  613.  
  614.       @DFRAME:   - @DFRAME contains the current frame number
  615.  
  616.                    Notes:
  617.                    1. @DFRAME may not be updated for as much as one second
  618.                    after a play has started; therefore this value is not
  619.                    reliable during this time.
  620.  
  621.                    2. @DFRAME contains the value -1 when there is no video
  622.                    being played or a video play has ended.
  623.  
  624.       @DSTATUS:  - @DSTATUS contains one of the following:
  625.  
  626.                   STOP   -- if play is stopped normally
  627.                   PAUSE  -- if play is paused
  628.                   PLAY   -- if file is being played
  629.                   ERROR  -- if the DVI story is in error
  630.  
  631.       Example:
  632.  
  633.           DPLAY "C:\AIRPLANE.AVS"
  634.           Do until @DSTATUS=STOP       /* Set loop to check for end-of-play */
  635.              DQUERY                    /* Get status */
  636.              say "Frame no.= "@dFrame  /* Show current video frame number
  637.              WAIT .1                   /* Wait 1/10 of a second */
  638.           End                          /* Continues on when play has stopped */
  639.  
  640.  ------------------------------------------------------------------------------
  641.  5.6 DSTATE request   (no default value)
  642.  
  643.      DSTATE lets you save the current state, restore a previously stored state,
  644.      or restore the start-up defaults.  The request value can be:
  645.  
  646.           S  -- Saves the current state.
  647.           R  -- Restores the previously saved state.
  648.           D  -- Defaults to the start-up default state.
  649.  
  650.      Note:  The state represents all of the parameters specified by DCONFIG
  651.      and DLOCATE instruction.  DSTATE lets you change and restore any of these
  652.      parameters for the next DPLAY or DSHOW instruction.
  653.  
  654.      Example: DSTATE D
  655.  ------------------------------------------------------------------------------
  656.  5.7 DSTEP
  657.  
  658.      DSTEP advances the DVI video/audio play one frame at a time.
  659.  ------------------------------------------------------------------------------
  660.  5.8 DSTOP
  661.  
  662.      DSTOP stops the DVI video/audio play.
  663.  
  664.      Note:  The user can stop a DVI story by pressing the escape key.
  665.  ------------------------------------------------------------------------------
  666.  5.9 DSHOW [source_file]
  667.  
  668.      DSHOW displays a DVI still image file.
  669.  
  670.      Where source_file is the fully qualified file name of the DVI still file
  671.      to be displayed.
  672.  
  673.      DVI still image files supported by the ActionMedia II Adapter are:
  674.  
  675.        o 9-bit compressed (includes JPEG format) and uncompressed stills
  676.        o 16-bit compressed and uncompressed stills
  677.  
  678.      The supported file name extensions are:
  679.  
  680.      FILE EXTENSION            FILE CHARACTERISTICS
  681.  
  682.        .AVS                1 file  9-bit or 16-bit compressed/uncompressed
  683.        .IMY .IMU .IMV      3 files 9-bit uncompressed
  684.        .CMY .CMU .CMV      3 files 9-bit compressed
  685.        .I16                1 file 16-bit uncompressed
  686.        .C16                1 file 16-bit compressed
  687.  
  688.      Note:  When a still image is represented by 3 component files, for
  689.      example, .IMY, .IMU, and .IMV, you can use any one of the three file
  690.      extension names with the DSHOW instruction.  (The three files must reside
  691.      in the same directory.)
  692.  
  693.      Example:  To display the image represented by the three files
  694.      FLOWER.CMY, FLOWER.CMU, and FLOWER.CMV the AVA statement could be:
  695.  
  696.        DLOCATE T 0 100 0 0                 /* start image as a single dot
  697.        DSHOW "C:\STILLS\FLOWER.CMU"
  698.        DO i = 0 to 50
  699.        DLOCATE T i ((i-50)*(i-50))/25 i i  /* curved path of target rectangle
  700.        END
  701.  ------------------------------------------------------------------------------
  702.  5.10 WAIT D frame#
  703.  
  704.      WAIT D makes a story wait until the specified video frame number is
  705.      reached (accuracy is within 10 frames). You can type the frame number with
  706.      the WAIT D instruction in the AVA statement column, or put the D and the
  707.      frame number in the Wait column. For example:
  708.  
  709.      |  AVA Statement                   |Method |Dir |Time |Wait |Size |
  710.  
  711.       WAIT D 245
  712.  
  713.       WAIT                                                  D 245
  714.  ------------------------------------------------------------------------------
  715.  6. ERROR CODES ===============================================================
  716.  
  717.  All AVC-DVI instructions return their execution status with the AVA variable
  718.  "rtn_code".  The story can display this return code via the following AVA
  719.  statement:
  720.                say rtn_code
  721.  
  722.  A rtn_code = 0 means that the instruction ran error free.
  723.  
  724.  In addition, after the DPLAY instruction, AVC-DVI returns the play status in
  725.  the AVA variable "@dLastError".  The story can display this variable with the
  726.  following AVA statement:
  727.  
  728.                say @dLastError
  729.  
  730.  The following lists the non-zero values of rtn_code and @dLastError:
  731.  
  732.  1 - 699:  Internal error of audio visual kernel (AVK). Refer to
  733.            ActionMedia II Technical Reference and contact IBM for support.
  734.      801:  Unsupported parameter in the DVI-AVC instructions.  Change and
  735.            rerun the story.
  736.      802:  DVI file could not be found.  Check the file name for accuracy.
  737.      803:  File name missing.  Provide file name with DVI instruction.
  738.      804:  Unsupported graphics mode active.  The story must be in VGA, VGA8
  739.            or 8514/A (XGA) mode when issuing a DVI DPLAY or DSHOW instruction.
  740.      808:  Internal error in the AVK.  Query @dLastError and contact IBM.
  741.      809:  Time out for starting a DVI programming thread.  Free up any
  742.            other simultaneously running programming thread(s).
  743.      810:  Error in switching OS/2 screen sessions.
  744.      811:  Could not start a DVI programming thread.  Free up any other
  745.            simultaneously running programming thread(s).
  746.      812:  Could not restart from DPAUSE.
  747.      813:  DPAUSE failed.
  748.      814:  Unsupported sampling rate for the audio data file.
  749.      901:  DVI data file version is incorrect.
  750.      902:  DVI data file open access denied.
  751.      903:  DVI data file read access denied.
  752.      904:  DVI data file seek access denied.
  753.      905:  Unable to allocate memory for DVI data file read.
  754.      906:  DVI still file is empty or contains unrecognizable data.
  755.      908:  DVI still-data file has incorrect compression algorithm.
  756.  ------------------------------------------------------------------------------
  757.  ========================== TRADEMARKS ========================================
  758.  *   Audio Visual Connection is a trademark of the IBM Corporation
  759.  *   IBM is a trademark of the International Business Machines Corporation
  760.  *   OS/2 is a trademark of the International Business Machines Corporation
  761.  *   PS/2 is a trademark of the International Business Machines Corporation
  762.  *   XGA is a trademark of the International Business Machines Corporation
  763.  **  ActionMedia is a trademark of the Intel Corporation
  764.  **  Digital Video Interactive is a trademark of the Intel Corporation
  765.  **  DVI is a trademark of the Intel Corporation
  766.  
  767. ================================ End of File ==================================
  768.