home *** CD-ROM | disk | FTP | other *** search
/ Directions 2000 / ILP_Directions2000.iso / _french / _armovie / replaydoc < prev   
Text File  |  1993-08-16  |  8KB  |  226 lines
  1.  
  2.                       The programmer's view of Acorn Replay
  3.                       =====================================
  4.  
  5. Introduction
  6. ------------
  7.  
  8. The software for replaying movies resides in the directory !ARMovie (think of
  9. it like a rather large system directory - currently about 640KBytes). The !Boot
  10. file for !ARMovie sets up the computer to play movies:
  11.  
  12. - loads the iconsprites for the AE7 filetype
  13. - sets File$Type for AE7
  14. - sets the RunType alias for AE7 to point to the Player program
  15.  
  16. - sets ARMovie$Dir so that the Player program knows where it is
  17.   (there are dither tables and sound code in the directory)
  18.  
  19. - ensures the computer has ColourTrans loaded (from the system directory -
  20.   any version will do)
  21.  
  22. After this, double clicking on an Acorn Replay Movie will play the movie on the
  23. desktop. Just running the program at the cli will play it. A program can do:
  24.  
  25. SYS"Wimp_StartTask","movie file name"
  26.  
  27. to play the movie.
  28.  
  29. The program attached to !ARMovie is a minimal desktop viewer for
  30. replay files - it can display the helpful sprite and allows desktop control of
  31. a few of the capabilities of the Acorn Replay Player program.
  32.  
  33. Note that the Player program has to take over the entire machine in order to
  34. get its work done. It consists of 4 independant interrupt run processes:
  35.  
  36. - file chunk loader
  37. - video decompressor
  38. - video frame refresh and dither
  39. - sound player
  40.  
  41. The video sections of this code are custom assembled to suit the particular
  42. screen mode etc.
  43.  
  44. The interrupt run processes are communicating using shared memory in the
  45. ordinary virtual address space - a wimp task swap would be fatal... A large
  46. amount is memory is required:
  47.  
  48. - double buffer for the file I/O (odd and even chunk size given in the
  49.   AE7 file header)
  50. - double buffered queue of decompressed frames
  51. - queue of sound chunks
  52.  
  53. The amount of memory required is at least:
  54.  
  55.   "odd" chunk size + "even" chunk size + 320K 
  56.   + 120K if sound is to be played
  57.   + 32K to 128K for dithering tables
  58.  
  59. The Player program can use more memory if it is available! It will (by default)
  60. return with a textual error if there isn't enough memory.
  61.  
  62. A major limitation of the video frame refresh and dither section of the
  63. program is that it uses word addressing in order to paint on the screen:
  64. this results in the displayed section be somewhat to the left of the desired
  65. position. With 16bpp it can be 1 pixel out, 8 bpp 4 pixels, 4bpp 8 pixels,
  66. 2bpp 16 pixels, 1bpp 8 pixels.
  67.  
  68. Simple Control
  69. --------------
  70.  
  71. The Player program has some controls hard wired into it:
  72.  
  73. Esc
  74.    
  75.    The Esc key terminates a display sequence.
  76.  
  77. Menu (Mouse middle button)
  78.  
  79.    The Menu button (also) terminates a display sequence.
  80.  
  81. Adjust (Mouse right button)
  82.  
  83.    The Adjust button pauses video and sound while it is held down.
  84.  
  85. Other capabilities may be provided as icons by the calling program.
  86.  
  87. Parameters
  88. ----------
  89.  
  90. The Player program also accepts a list of parameters on the command line after
  91. the Acorn Replay movie file. These are
  92.  
  93. -At <Number>,<Number>
  94.  
  95.    Specifies the position of the bottom left corner of the replayed movie in
  96.    OS units x,y. Player will move the output display such that it is entirely
  97.    on screen. Note the comments above about precision of positionning the
  98.    output.
  99.  
  100. -Big
  101.  
  102.    If the movie is <=160 X, <=128 Y, then Player will play it on a Mode 13
  103.    320 by 256 pixel screen filling the screen.
  104.  
  105. -Leave
  106.  
  107.    By default, Player removes the output from the display. If -Leave is
  108.    specified it will leave the output on the display when the program is
  109.    left (either by getting to the end or Escape/Menu).
  110.  
  111. -Loop
  112.  
  113.    Player will loop back to the start of the movie when it gets to the end,
  114.    thus playing for ever.
  115.  
  116. -NoError
  117.  
  118.    Suppresses all possible textual errors from the Player program. The
  119.    variable ARMovie$ReturnCode will contain the error.
  120.  
  121. -PlayFor <Number>
  122.  
  123.    <Number> represents a time in centiseconds: this amount of the movie is
  124.    played and the program exits. Note that Pause, fast forward, half speed
  125.    etc. do not affect this time limit - it represents a duration in frames
  126.    (or feet of the original film) rather than a time in the future.
  127.  
  128. -Quiet
  129.  
  130.    Disables the sound.
  131.  
  132. -Startat <Number>
  133.  
  134.    <Number> represents a time in centiseconds: the movie is played from this
  135.    point. It can be very time consuming to reach a random point in a none
  136.    key frame movie, but Player can do it if necessary. Key frame movies
  137.    should only take a few seconds to start playing at any point.
  138.  
  139. In addition to those parameters, the calling program can specify the positions
  140. of control buttons on screen. The Player program caters for buttons with the
  141. following functions:
  142.  
  143.    exit
  144.    pause
  145.    single frame advance when in pause mode
  146.    fast forward
  147.    half speed
  148.    quiet (no sound)
  149.    loud (sound back on)
  150.  
  151. By default no button definitions exist except for pause, defined as the
  152. whole screen: so by default a left click will pause the movie and another
  153. will restart it. Buttons are defined with the initial character followed by
  154. the bottom left corner i.e. E10,40 - this gives a default sized button of 32
  155. OS units. E10,40;50 gives a square button of 50 OS units. E10,40;50,25 gives
  156. a rectangular button 50 OS units wide, 25 tall.
  157.  
  158. A typical command line might be:
  159.  
  160. <movie name> -loop -leave -startat 2000 -playfor 2000 -quiet H640,512 P0,0:0
  161.  
  162. case is irrelevant.
  163.  
  164. System Variables
  165. ----------------
  166.  
  167. There are several system variables which affect the Acorn Replay player program:
  168.  
  169. ARMovie$Place
  170.  
  171.    Contains the position on screen where the player will put the movie as
  172.    <leftx> <bottomy> - for example *set ARMovie$Place 640 512
  173.  
  174.    Controlling programs must set this immediately before running the movie.
  175.  
  176.    Value is only used if -At parameter is not given.
  177.  
  178. ARMovie$PrefMode
  179.  
  180.    Used by the machine's owner to get the movie to display in a different
  181.    mode to the current one. For example, a user may like working in a very
  182.    high resolution mode with a low number of colours. Player can display
  183.    movies in such modes but they don't look good, so the user can set
  184.    ARMovie$PrefMode to an alternative mode. Note that the user won't be able
  185.    to see the buttons. (Currently ARMovie$PrefMode is the only way to get
  186.    playback in 16 bit per pixel modes, since the desktop doesn't operate
  187.    in those modes).
  188.  
  189.    If ARMovie$PrefMode is 13, then -Big is assumed.
  190.  
  191. [Aside: minimal mode if 0]
  192.  
  193. ARMovie$Suffix
  194.  
  195.    Used by the machine's owner to preselect different versions of the
  196.    movie if they are available. For example, if one knows that one's machine
  197.    can only manage 12.5fps movies, *set ARMovie$Suffix to 2 and Player will
  198.    preferentially play the 12.5fps movies. See the file on AE7 file naming
  199.    conventions.
  200.  
  201. Some system variables are used by Player to return information to the calling
  202. programs:
  203.  
  204. ARMovie$Return
  205.  
  206.    Player sets this to the actual position on screen of the video information.
  207.    If -leave has been set, this is the section that has been 'dirtied' and
  208.    should be repainted by the window manager. It is set to
  209.  
  210.    <leftx> <bottomy> <rightx> <topy>
  211.  
  212. ARMovie$ReturnCode
  213.  
  214.    If -NoError has been set, this will contain the textual error message.
  215.    It will be null if there was no error.
  216.  
  217. ARMovie$Time
  218.  
  219.    Player sets this to the number of centiseconds of movie which have been
  220.    played. Note that (like -playfor) this refers strictly to the amount of
  221.    the movie, not the total elapsed time: playing a movie and playing the
  222.    movie pausing every frame for an hour will end up with the same value
  223.    for ARMovie$Time.
  224.  
  225.  
  226.