home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 7 / AU_CD7.iso / _movies / _armovie / documents / fetchers < prev    next >
Text File  |  1997-12-01  |  10KB  |  207 lines
  1. Introduction
  2. ------------
  3.  
  4. Fetchers are a section of the Replay architecture which allows the rest of the
  5. system to ignore the details of the way the data is stored in the file.
  6. Different formats of file can be accomodated by writing appropriate fetchers.
  7. There must always be an ARMovie header in order to start the system up - for
  8. formats where this is not natural, the ARMovie header is put into an image file
  9. view of the original file. (see RISC OS PRM for details of Image files -
  10. briefly, the original file is made to masquerade as a directory which holds
  11. another view of the file some of which is created on the spot when accessed)
  12.  
  13. Jargon
  14.  
  15. Because there is so much overloading of words like Codec and file, let alone
  16. names like Replay, QuickTime and Video for Windows, the following new jargon
  17. word is introduced:
  18.  
  19. Container: a file structure for holding multimedia data. The ARMovie format
  20. definition (minus any specific details of video and audio codecs) is an example
  21. of a container: a QuickTime "MOV" and a Video for Windows "AVI" file format are
  22. two other examples which are similar to ARMovie files; an MPEG transport stream
  23. is another container of a very different type.
  24.  
  25. General
  26. -------
  27.  
  28. To rephrase the opening paragraph: Fetchers are a section of the Replay
  29. architecture dealing with specific containers. In order to play a particular
  30. file, Replay needs to have:
  31.  
  32. * a program to generate the ARMovie header (usually as an Image file)
  33. * a fetcher suitable for that container
  34. * a video decompressor suitable for decompressing the video data
  35. * an audio decompressor suitable for playing the sound data
  36.  
  37. For the specific case of ARMovie files, the first two sections are very easy
  38. (no header needs to be generated and the standard ARMovie release understands
  39. that container). A fetcher may be needed if the ARMovie file has to be played
  40. from some abnormal medium (the standard code draws the file from the file
  41. system) - for example from a streaming video server - and this can be done by
  42. setting the ARMovie$Fetcher variable to describe a fetcher for ARMovie files.
  43.  
  44. Important header data
  45. ---------------------
  46.  
  47. The ARMovie header is used by many programs to handle ARMovie files. All the
  48. details in the header must be present with the exception of the pointer to the
  49. catalogue - a pointer must exist, but it becomes a parameter to the fetcher
  50. rather than anything which is inspected by Replay programs. See the document
  51. "AE7doc".
  52.  
  53. A fetcher is signalled by including the text "Fetcher [<name of fetcher>]" on
  54. the catalogue line. Fetchers are stored within the directory
  55. <ARMovie$Dir>.MovingLine.Fetchers.
  56.  
  57. Fetcher interface
  58. -----------------
  59.  
  60. Fetchers have considerably more freedom in data structure than the chunk format
  61. of ARMovie files. Video data and audio data may be in any order within the data
  62. returned on fetching a chunk - the fetcher also returns indexes to the video
  63. and audio for interesting values.
  64.  
  65. A fetcher is represented as a self-contained, position independant piece of
  66. code which is dynamically loaded to a quad word aligned address. The first four
  67. words contain the entry points Open, Close, Fetch, ReleaseBuffer - in that
  68. order.
  69.  
  70. Open:
  71. On Entry:       R0=file handle
  72.                 R1=catalogue offset
  73.                 R2=access parameter (see document ProgIf)
  74.                 R3=track number for audio OR -1 for no sound required
  75.  
  76. On Exit:        R0=sound buffer size
  77.                 R1-R13 preserved
  78.  
  79. Returns via MOV PC, R14
  80.  
  81. Does what ever it needs to in readiness for calls to Fetch. Free to allocate
  82. memory; may load a module; may open more files etc. The sound buffer size
  83. parameter gives the number of bytes which are needed to hold the total
  84. compressed sound data for any particular chunk (in the ARMovie format, sound
  85. data is held in one contiguous chunk, but other containers do not do this): a
  86. value of zero may be returned to indicate that the sound data will be in one
  87. contiguous chunk and does not need to be copied. A fetcher may be reinitialised
  88. for a different file without being reloaded. Note that when r2=0, the file is
  89. in memory (see ProgIf) and that it no longer needs to be copied around.
  90.  
  91. Close:
  92. On Entry:       ---
  93. On Exit:        R0-R13 preserved
  94.  
  95. Returns via MOV PC, R14
  96.  
  97. Release all memory which may have been allocated. This call does not close
  98. the file containing the header, but does close all other used resources.
  99.  
  100. Fetch:
  101. On Entry:       R0=chunk number
  102.                 R1=address of buffer
  103.           OR    R1=base address in memory of file (when access=0)
  104.                 R2=access
  105.                 R3=NOT(useable status bits)
  106.  
  107. On Exit:        R0=Pointer to Video Frame Index
  108.                 R1=Pointer to Sound Index
  109.                 R2=????
  110.                 R3=status:
  111.                    bit 0: fetch did not happen, try again
  112.                    bit 1: fetch returns an error: error pointer in R0
  113.                    bit 2: fetch needs to set the play status to
  114.                           (status AND r0 OR r1)
  115.                    bits 3-31: reserved - set to zero
  116.                 R4-R13 preserved
  117.  
  118. Returns via MOV PC, R14
  119.  
  120. Fills the buffer (when access<>0) and returns a description of the information
  121. it has loaded (positions of frames and chunks of sound) and a status. Info may
  122. not be valid until ReleaseBuffer has also been called. A chunk number is
  123. defined as if the file were in ARMovie format and divided into equal temporal
  124. periods containing identical numbers of frames. Chunks are numbered 0 upwards
  125. to the maximum chunk number (in the header). Chunks will be read by the ARMovie
  126. system in any order (potentially) but real time performance is only required
  127. for a sequential reading order. The start position may not be chunk 0 (it
  128. depends on the -startat value, for example). When access=0 there is no buffer
  129. in the Player program and the pointers to video frame and sound indexes must be
  130. held in memory allocated by the fetcher: this is to make playing from in RAM
  131. more efficient. The input value of r3 is the NOT of the status bits that the
  132. caller can handle at the moment - a set bit means that that status bit will not
  133. be processed by the caller, a clear bit means that that status bit can be
  134. processed by the caller. Status bit 1 works on all calls, other status bits at
  135. the discretion of the caller (e.g. the standard player will not allow bit 2 for
  136. its first call on Fetch). The input status is designed so that if the register
  137. is preserved nothing happens and designed so that newer fetchers will work with
  138. older players and vice versa.
  139.  
  140. The frame index has the form:
  141.  
  142. Offset:         0       Frame 1 start (absolute addresses, not offsets)
  143.                 4       Frame 2 start
  144.                 ...
  145.  
  146. Any value in the frame address is valid - illegal or unlikely addresses may
  147. well be being used to give the video codec additional instructions. If the
  148. strictly sequential ordering of ARMovie files is required, then the Video Frame
  149. Index Pointer should be returned as zero from Fetch. A frame start address of
  150. -1 is recognised by Player as meaning that the data has not arrived for this
  151. frame - Player sets the frame index list entry to -2 and does not proceed with
  152. video decompression until this frame start address has become valid: this
  153. allows the system to have less latency (the fetcher returns a valid list as
  154. soon as it can, but fills in the data later on).
  155.  
  156. The sound index has the form:
  157.  
  158. Offset:         0       Number of sound blocks
  159.                 4       Start of sound block 1 (absolute address)
  160.                 8       Size of sound block 1
  161.                 12      Start of sound block 2
  162.                 16      Size of sound block 2
  163.                 ...
  164.  
  165. Playing programs may well collate the sound information into one buffer - the
  166. size of the necessary buffer is given by the Open call. As noted above,
  167. containers other than ARMovie often have non-sequential buffers for sound. A
  168. single sound block would correspond to the ARMovie file's version of sound, and
  169. is efficiently processed even if sound buffer size (from Open) was not zero. If
  170. the sound buffer size is zero, then only one sound block will be processed.
  171.  
  172. CopyFromAndReleasePreviousBuffer: (aka ReleaseBuffer)
  173. On Entry:       R0=chunk number
  174.                 R1=address of buffer (destination buffer)
  175.            OR   R1=base address in memory of file
  176.  
  177. On Exit:        R0-R12 preserved
  178.  
  179. Returns via MOV PC, R14
  180.  
  181. Copies across any needed data from the previously loaded buffer (or previously
  182. referenced section of an in-memory file) and may fill in some of the values
  183. referred to by the pointers returned by Fetch. ReleaseBuffer must be called for
  184. every call to Fetch, even the first (when there is no last buffer). It can be
  185. called just before Fetch, just after, or under interrupt at any time during.
  186.  
  187. A fetcher author may use both Fetch and ReleaseBuffer as possible methods to
  188. fill a chunk buffer: to fill the buffer b with chunk n, both calls Fetch(n, b)
  189. and ReleaseBuffer(n, b) are made. Fetch could get what is needed from disc;
  190. ReleaseBuffer will get what is needed from buffer n-1 (thus releasing Player
  191. from the obligation of keeping buffer n-1 around). ReleaseBuffer needs to know
  192. which buffer was filled last. It and Fetch must also recognise when chunk n is
  193. being loaded out of order: in that situation Fetch should load the entire chunk
  194. and ReleaseBuffer will do nothing. ReleaseBuffer must be called when loading
  195. chunk 0, even though it would seem that it can't be doing anything useful.
  196. Since ReleaseBuffer may be called from interrupt routines, it should never do
  197. any IO: if it needs to do any substantial work it should reenable interrupts if
  198. called in interrupt mode.
  199.  
  200. The fetcher must be written so that the calls to Fetch and ReleaseBuffer can be
  201. performed in either order, or concurrently; concurrently is recommended for the
  202. sake of disc latency. Users of the fetcher interface (such as Player) should
  203. not call ReleaseBuffer(n) so early that it is concurrent with Fetch(n-1) or so
  204. late that it is concurrent with Fetch(n+1); they must avoid using the info
  205. returned by Fetch(n) until ReleaseBuffer(n) has completed.
  206.  
  207.