home *** CD-ROM | disk | FTP | other *** search
/ Science & Nature: Materials / Acorn_YITM_ScienceAndNature2_Materials.iso / _sci2 / _armovie / documents / decompif < prev    next >
Text File  |  1994-01-20  |  9KB  |  209 lines
  1.                  The interface between the Player and the
  2.             Acorn Replay Decompressors in the !ARMovie resource
  3.             ===================================================
  4.  
  5. The Replay "ARMovie" format allows for different sound and video compression
  6. formats. An interface inside the ARMovie Player program ("!ARMovie.Player")
  7. allows easier introduction of new video decompression code and allows other
  8. programs to use the ARMovie video decompressors. Sound format 2 provides
  9. similar independence for sound compression methods: the format directly
  10. names the sound decompression code which will be used - provided this is
  11. located in <ARMovie$SoundDir> (see ToUseSound for more details).
  12.  
  13. There are therefore two ways to introduce new video compression formats: total
  14. replacement of the Player program (provide a !ARMovie.Decomp<N>.!RunImage for a
  15. new compression type <N> which implements the entire ProgIf command interface)
  16. or provide a decompressor which uses the Player interface (provide a
  17. !ARMovie.Decomp<N>.Decompress file). This document describes the
  18. Player/Decompressor interface.
  19.  
  20. Using the interface to provide a new Decompress
  21. -----------------------------------------------
  22.  
  23. Using the interface means keeping most of the architecture of the Player
  24. system:
  25.  
  26. - interleaved video+sound chunk format
  27. - format of sound code and interface to it
  28. - key frame system (but it can be ignored completely, also)
  29. - decompressor called in IRQ mode; should run with interrupts (mostly)
  30.   enabled
  31. - flags between disc loader and decompressor
  32. - flags between decompressor and screen painter
  33. - decompressor provides the colour looked up output
  34.  
  35. Details of using the sound system are in 'ToUseSound': either the current
  36. Acorn Replay MovingLines sound code can be used or new sound formats added
  37. by sound code implementing the current interface (described from the point
  38. of view of the client in ToUseSound) can be added using format 2 to name
  39. the sound code. No changes to Player programs is required.
  40.  
  41. In order to start some of the decompressors (MovingLines, for example) at
  42. any position, the use of key frames is possible. The compressor stores the
  43. state of the stream every chunk uncompressed in the key frame data
  44. structure. The Player program will load the uncompressed file from the data
  45. structure in order to start decompression at an arbitary point, providing
  46. the 'previous frame' state (see below). Decompressors which can start
  47. anywhere use an ARMovie file without the key frame data structure (by giving
  48. a -1 offset to the keys in the header).
  49.  
  50. The decompressor is called in IRQ mode with interrupts enabled in order to
  51. decompress the next frame. Code in the Player handles semaphores between
  52. decompression and painting frames and between loading the video chunks and
  53. decompressing frames. Other code in the Player takes data from the
  54. decompressed frames buffer and paints it onto the screen (in IRQ mode also)
  55. and code waits for compressed data buffers to be empty and refills them from
  56. the filing system (in User mode as the foreground task). To allow these
  57. other tasks to run, the IRQ code must leave interrupts enabled for as much
  58. time as possible (the MovingLines decompressor leaves interrupts enabled for
  59. all of its work). In any case IRQ must not be disabled for longer than 1
  60. full sound buffer: about 2mS.
  61.  
  62. The disc loader works in a double buffered manner: two buffers each
  63. containing either one or two chunks of data (2 or 4 seconds per buffer
  64. conventionally). The addresses of the two buffers and one or two chunks per
  65. buffer are all chosen dynamically and the Player program knows from the
  66. ARMovie header how many times to call the decompression code. The two
  67. buffers will always start on word addresses.
  68.  
  69. Using the interface play with existing Decompress code
  70. ------------------------------------------------------
  71.  
  72. As well as being able to provide new compression formats by using the
  73. Player/ Decompress interface, other programs can also use the Decompress
  74. code, in effect pretending to be the Player program as far as the Decompress
  75. code is concerned. This greatly extends the capability of the Replay system:
  76. programs could be written to play ARMovie files in the desktop while
  77. multitasking (obviously non-real time). Or sections of an ARMovie file could
  78. be decompressed to memory and editted. Or whatever. The ability to patch the
  79. Decompress code allows player programs to load two copies of a Decompress
  80. code: patch one to generate data for one format and patch the other to
  81. generate data for a different format (e.g. non-dithered for the screen).
  82.  
  83. Such a playing program has to do all the tasks normally done by the
  84. !ARMovie.Player program:
  85.  
  86. - read the file header to discover the data
  87. - establish the dither for the screen if needed
  88. - load the right decompress code, patch and initialise it
  89. - load the key frame if required
  90. - load the chunks from the file
  91. - call the decompress entry point for each frame in the block
  92.  
  93. but it need do no more than this. It can structure its data structures as it
  94. wishes (excepting that Decompress codes write pixels as words).
  95.  
  96. Decompress "Info" file
  97. ----------------------
  98.  
  99. In order that Decompress code providers can incorporate their own names for
  100. formats, provide format origination text, provide compress and edit routines
  101. with hints on various formats, an Info file called Decomp<N>.Info can be
  102. provided (the !ARMovie.Player does not need this file). It contains the
  103. following information:
  104.  
  105. Name of format
  106. Originator
  107. exact number of bits per pixel (or empty if this is variable)
  108. desired x multiple; minimum x size; maximum x size
  109. desired y multiple; minimum y size; maximum y size
  110. temporal (or empty if temporal information is not required)
  111. list of colour spaces which can be held in the format
  112.  
  113. For example:
  114.  
  115. Moving Lines
  116. ⌐ Acorn Computers 1993
  117.  
  118. 1;1;1280
  119. 1;1;1024
  120. Temporal
  121. YUV 5,5,5; RGB 5,5,5
  122.  
  123. Formal interface: "Decompress" file (any filetype can be used)
  124. --------------------------------------------------------------
  125.  
  126. The Player program loads the decompress code at a quad word aligned address
  127. in memory. It then processes the patch table and then calls the init point.
  128. Later on the player calls the decompressor in USR mode to decompress the
  129. first chunk's worth of frames (or to do -explode). For a full play, the
  130. player will call the decompressor in IRQ mode.
  131.  
  132. First word: patch table offset
  133.  
  134.  Purpose: to allow the player to insert pixel colour lookup in the
  135.           decompressor. May in future allow other values to patched.
  136.           Note that an unpatched decompressor should still work!!
  137.  
  138.  The offset table consists of words. Each word has the bottom 16 bits
  139.  as the offset of a word (usually an instruction) from the start of the
  140.  decompressor. The top 4 bits are an opcode number. The remaining 12
  141.  bits may have a meaning for that opcode. The list is terminated by a
  142.  word of -1.
  143.  
  144.  Opcode 0: patch in colour lookup
  145.   bits 27..24: destination register
  146.   bits 23..20: source register
  147.   bits 19..17: pixel lookup table register
  148.  The Player alters the word to lookup the pixel colour. The value of
  149.  the source register and the size of the result in the destination
  150.  register may change for different decompressors. For MovingLines the
  151.  source register value is either RGB or YUV 15 bits and the destination
  152.  value is always a word value. An unpatched MovingLines decompressor
  153.  produces RGB or YUV output.
  154.  
  155. Second word: init entry point
  156.  
  157.  Purpose: to allow the decompressor to initialise any tables that are
  158.           needed
  159.  
  160.  On entry:
  161.    r0 - source x size of movie
  162.    r1 - source y size of movie
  163.    r2..r12 - scratch
  164.    r13 - stack
  165.    r14 - return address
  166.    processor mode: USR
  167.    flags - V set signals error, otherwise irrelevant
  168.  
  169. Third word: decompress entry point
  170.  
  171.  Purpose: decompress precisely one frame
  172.  
  173.  On entry:
  174.    r0 to r5 are set up by Player as follows:
  175.    r0 - source byte pointer
  176.    r1 - output pointer - save output pixels here (word aligned)
  177.    r2 - previous output pointer (allows copying from previous frame)
  178.    r3 - pixel dither lookup table
  179.    r4 - return address (can't be r14...)
  180.    r5..r12 - scratch
  181.    r13 - small stack (RISC OS irq stack)
  182.    r14 - unuseable
  183.    processor mode: IRQ, interrupts ENABLED (usually)
  184.    flags - irrelevant
  185.  On exit
  186.    r0 - next value of source byte pointer
  187.    r1..r12 - irrelevant
  188.    r13 - must be same value as on entry
  189.    r14 - irrelevant
  190.    processor mode: IRQ, interrupts ENABLED
  191.    flags - irrelevant
  192.  
  193.  Decompressed pixels are stored as Words!!! For the MovingLines decompressor
  194.  to work, the source pointer must be half word aligned.
  195.  
  196. The 'DecompresH' file
  197. ---------------------
  198.  
  199. A decompression provider can additionally provide a DecompresH program. This
  200. has exactly the same interface as the Decompress file, but stores output
  201. pixels as half words. This allows the Player program to use less store (and
  202. run slightly faster) in some screen modes (in particular, mode 15).
  203.  
  204. Programs which use the decompression programs must not assume the existence
  205. of 'DecompresH' forms of decompressors and must be capable of using the
  206. 'Decompress' file instead. For some compression formats, the gain in the
  207. Player of using the half word output may be completely lost by inefficiency
  208. in the decompressor.
  209.