Science & Nature: Materials

home *** CD-ROM | disk | FTP | other *** search

/ Science & Nature: Materials / Acorn_YITM_ScienceAndNature2_Materials.iso / _sci2 / _armovie / documents / progif < prev next >

Wrap

Text File | 1994-02-22 | 31KB | 768 lines

The programmer's view of Acorn Replay ===================================== Introduction ------------ The software for replaying movies resides in the directory !ARMovie (think of it like a rather large system directory - currently about 640KBytes). The !Boot file for !ARMovie sets up the computer to play movies: - loads the iconsprites for the AE7 filetype - sets File$Type for AE7 - sets the RunType alias for AE7 to point to the Player program - sets ARMovie$Dir so that the Player program knows where it is (there are dither tables and sound code in the directory) - ensures the computer has ColourTrans loaded (in the RISC OS ROM or from the system directory - any version will do) After this, double clicking on an Acorn Replay Movie will play the movie on the desktop. Just running the program at the cli will play it. A program can do: SYS"Wimp_StartTask","/"+"movie file name" to play the movie. The program !ARPlayer is a desktop viewer for replay files - it can display the helpful sprite and allows desktop control of a few of the capabilities of the Acorn Replay Player program. See the section on ARMovie$Dir below for information on how to treat !ARMovie. Note that the !ARMovie.Player program has to take over the entire machine in order to get its work done. It consists of independent interrupt run processes: - file chunk loader - master time 'conductor' - video decompressor - video frame refresh and dither - sound player - mouse event handler The video sections of this code are custom assembled to suit the particular screen mode etc. The interrupt run processes are communicating using shared memory in the ordinary virtual address space - a wimp task swap would be fatal... A large amount is memory is required: - double buffer for the file I/O (odd and even chunk size given in the AE7 file header) - double buffered queue of decompressed frames - queue of sound chunks The amount of memory required is at least: "odd" chunk size + "even" chunk size + 320K + 48K (or more) if sound is to be played + 128K for dithering tables (the video compressor program gives an accurate value) The Player program can use more memory if it is available! It will (by default) return with a textual error if there isn't enough memory. A major limitation of the video frame refresh and dither section of the program is that it uses word addressing in order to paint on the screen: this results in the displayed section being somewhat to the left or right of the desired position. With 32bpp it is accurate, but with 16bpp it can be 2 pixels out, 8 bpp 4 pixels, 4bpp 8 pixels, 2bpp 16 pixels, 1bpp 8 pixels. The program rounds the pixel address to the word address to minimise the total effect, thus making it 16bpp +/- 1 pixel etc. ADPCM sound is Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands. See notice at the end. Simple Control -------------- The Player program has some default controls in it: Esc The Esc key terminates a display sequence. Menu (Mouse middle button) The Menu button (also) terminates a display sequence. Adjust (Mouse right button) The Adjust button pauses video and sound while it is held down. Other capabilities may be provided as icons by the calling program. Parameters ---------- The Player program also accepts a list of parameters on the command line after the Acorn Replay movie file. These are -At <Number>,<Number> Specifies the position of the bottom left corner of the replayed movie in OS units x,y. Player will move the output display such that it is entirely on screen, and may clip the bottom of the movie if it is still too large. Note the comments above about precision of positioning the output. -Big The Player program will try to make the movie as large as possible. It uses the value in ARMovie$PrefBigMode to find an appropriate mode for playing the movie. If ARMovie$PrefBigMode is not set, then it assumes "13;49;28". Appropriate modes have eigx=eigy, 8 or more bpp OR eigx=2, eigy=1, 8 or more bpp OR eigx=1, eigy=0, 8 or more bpp. An appropriate mode must exist in ARMovie$PrefBigMode. eigx=eigy=1 or 2: magnification 2 eigx=eigy=0: magnification 1 eigx=2, eigy=1: magnification 2x, 4y eigx=1, eigy=0: magnification 1x, 2y Larger magnification factors are more expensive in CPU terms, but may give a better picture (for example, in combination with interpolation). The -nomenu flag is overridden when -big is asserted. -Explode <Dir$> Player decompresses the specified section of the movie (-startat and -playfor) and places the result as a sequence of frames in the directory Dir$ with the following name for each frame: FNZNUM(frame%DIV75DIV77)+"."+FNZNUM(frame%DIV75 MOD77)+"."+FNZNUM(frame%MOD75) DEF FNZNUM(A)=RIGHT$("0"+STR$(A),2) Frames start at zero. An RGB frame is stored as a p15 file (textual header plus 5,5,5 R,G,B data held as uncompressed 16 bit values with R as bits 0-4, G as bits 5-9, B as bits 10-14). A YUV frame is stored as a p13 file (textual header plus 5,5,5 Y,U,V data). This can take quite a while! -Follow <file name> or "<file name>",<Number> Specifies a "trajectory" file and optional trajectory step rate (which overrides the rate specified in the file). The file contains a list of origin positions which move the -at position in real time while the movie is being played. The format of the file is: ARMovie Trajectory 1 Comment line describing the trajectory 10 steps per second M shapes <shape description file names> N instances <instances> M represents the number of shapes referred to in the trajectory. If is non zero, then the following lines contain shape file names. Shapes are referenced by integer numbers in the order they are referred to in the trajectory file. Shape 0 is the default rectangle and does not need to be defined. N provides instances of the selected frame shape at a particular position, for a given number of frame times. It is followed by N lines containing this information: <x>,<y>:<frame shape>;<repeat count> as textual decimal numbers. <x> and <y> are in RISC OS graphics coordinates and represent offsets from the -at position. <repeat count> may be omitted in which case the line is used once only. <frame shape> may be omitted if there is no list of shapes. The movie is played in each shape at each position (positions changing at the step rate) until the end of the list is reached when it restarts at the start of the list. If the "file name" (of the trajectory file or of the shape) is not found, then it will be looked for in the ARMovie directory. Example: :6.armovie.fred -at "circle",50 -Leave By default, Player removes the output from the display. If -Leave is specified it will leave the output on the display when the program is left (either by getting to the end or Escape/Menu). Leave state is forced if the user exits by clicking on the CAPTURE/EXIT button. -Loop Player will loop back to the start of the movie when it gets to the end, thus playing for ever. This overrides -playfor. -Loop <number> Player will loop back to the start of the movie when it gets to the end, for the specified number of times. Note that both forms of loop may have problems on a CD-ROM where access time to move the head from finish to start might cause a break in the sequence. -Mode <number>|<string> Player will change to this screen mode before playing (see also -Big, ARMovie$PrefBigMode and ARMovie$PrefMode). On RISC OS 3.50, the mode may be defined as a string of the following form: -mode X320,Y256,C256,F60,EX2,EY2 X plus resolution, Y plus resolution are always required. C plus number of colours (C2, C4, C16, C256, C32T, C16M) is optional and defaults to C32T (16bpp) if not specified. F plus frame rate: fastest available rate if not specified. EX plus External to Internal Graphics X value (eigx), EY plus External to Internal Graphics Y value (eigy), default to RISC OS supplied values for the mode if not specified. The , delimiter above can be any character other than <space> (even <space> may be used when defining ARMovie$PrefMode or ARMovie$PrefBigMode). No delimiter at all is also allowable. Parameters can be given in any order. -Mouse <file>|<decimal address> Player will call a supplied routine after a mouse initiated change. The value supplied is checked to see if it is a valid decimal number (VALx$>0) or it is treated as a position independent file which is loaded into memory by Player at some quad word aligned address (determined at run time). The routine is called immediately after a frame has been painted; the CPU is in interrupt mode and the routine is entered with a BL. The registers contain: r0: address of state bits word: bit 0: true if paused bit 1: true if sound muted bit 2: true if exiting bit 3: true if single frame advance (which doesn't last long!) bit 4: true if capture class exit (bit 2 true too) bit 5: true if playing invisible frames (i.e. don't change screen) bit 6: true if end of loop r1: mouse x r2: mouse y r3: mouse buttons r4: mouse button which changed (bit set for each button which changed) r5: points to: nx ny number of colours screen base address rowbytes number of rows vertical expansion ratio movie x movie y frames per second*100 r6: points to button data structure: 4 words per button being: left x, bottom y, right x, top y buttons ordered: pause, exit, capture, single frame advance, ffwd, half speed, quiet, loud, mute r7..r12: nothing r13: RISC OS Irq stack r14: return address If interrupts are to be reenabled, the routine *must* worry about being called recursively. Returning as soon as possible is advised - playing a movie can be quite short of processor time... -Mute Player starts up with sound initially turned off. -NoAdjust Suppresses the use of Adjust for pause. -NoError Suppresses all possible textual errors from the Player program. The variable ARMovie$ReturnCode will contain the error. -NoMenu Suppresses the use of Menu for exit. -Paint <file>|<decimal address> Player will call a supplied routine after painting each frame. The value supplied is checked to see if it is a valid decimal number (VALx$>0) or it is treated as a position independent file which is loaded into memory by Player at some quad word aligned address (determined at run time). The routine is called immediately after a frame has been painted; the CPU is in interrupt mode and the routine is entered with a BL. The registers contain: r0: points to: nx ny number of colours screen base address rowbytes number of rows vertical expansion ratio movie x movie y frames per second*100 r1: movie base address on screen r2: frame number of just painted frame r3..r12: nothing r13: RISC OS Irq stack r14: return address If interrupts are to be reenabled, the routine need not worry about being called recursively - Player is in a semaphored area which will not be reentered until this thread terminates. Returning as soon as possible is advised - playing a movie can be quite short of processor time... Note that the routine is only called when a frame is actually painted and this does not happen if processor time is running short. -Paused Player starts up in paused state. It paints the first available frame in order to show what's going on, but this isn't the frame indicated by -startat (its actually the first frame of the same video chunk). If -startat has been used there may be a short pause between the first press of the pause button (or left mouse button) and anything actually happening. -PlayFor <Number> <Number> represents a time in centiseconds: this amount of the movie is played and the program exits. Note that Pause, fast forward, half speed etc. do not affect this time limit - it represents a duration in frames (or feet of the original film) rather than a time in the future. If the number is zero, then just the initial frame is displayed, no sound is played and double buffer reads are disabled. -Quiet Disables the sound permanently. (Unlike -Mute it cannot be turned back on with the controls if they are provided) -Relative Changes button definitions such that the origin is relative to the -at value rather than absolute. -Shape <filename> Describes a shape other than a rectangle for the output to appear in. The format of the file is: ARMovie Shape 1 A comment line to describe the shape 800 640 OS unit size of the shape (0,0,x,y) Followed immediately by the entries, each of the form: entry header: byte 0: low 8 bits of dest X OS coord byte 1: bottom 4 bits: high 4 bits of dest X OS coord top 4 bits: low 4 bits of dest Y OS coord byte 2: high 8 bits of dest Y OS coord *Must* resolve to a mode 13 pixel (i.e. multiples of 4) bottom left of dest = 0 byte 3: N: number of replay pixels to copy 0-255 followed by N entries of the form: byte 0: low byte source X replay pixel byte 1: high byte source X replay pixel byte 2: low byte source Y replay pixel byte 3: high byte source Y replay pixel top left of source image = 0 There should be no surplus junk at the end of the file... Replay source pixel (X,Y)s are black if the pixel doesn't exist in the movie (e.g. because the movie is smaller than the shape). If Y=-1, then X=-1 will be black and X=-2 will be white. Replay always paints a mode 13 size pixel, so the destination OS coordinates should be multiples of 4. The image position will be controlled by -at, so, if you want a circle in the centre of the screen, the shape file should have a circle whose minimum x and y is 0 and maximum the diameter. -Silent Starts playing with sound initially disabled. -Small If eigx=eigy=1, and there are 8 or more bits per pixel, -small plays the movie without the normal 2:1 scale up. -Speed <Number> <Number> represents a speed up ratio: the movie is played faster or slower than normal. For example -speed 2 or -speed 0.5 for twice speed or half speed play. It is recommended that -mute is used at the same time as -speed... No attempt is made to enforce speed ratios that the computer can actually decompress, so use with care! -Startat <Number> <Number> represents a time in centiseconds: the movie is played from this point. It can be very time consuming to reach a random point in a none key frame movie, but Player can do it if necessary. Key frame movies should only take a few seconds to start playing at any point. -Track <Number> <Number> selects which of the multiple sound tracks in the ARMovie file is played. The track must exist. In addition to those parameters, the calling program can specify the positions of control buttons on screen. The Player program caters for buttons with the following functions: exit capture exit (exactly like exit, but leaves pixel map on screen) pause single frame advance when in pause mode fast forward half speed quiet (no sound) loud (sound back on) mute (toggle sound) By default no button definitions exist except for pause, defined as the whole screen: so by default a left click will pause the movie and another will restart it. Buttons are defined with the initial character followed by the bottom left corner i.e. E10,40 - this gives a default sized button of 32 OS units. E10,40,50 gives a square button of 50 OS units. E10,40,50,25 gives a rectangular button 50 OS units wide, 25 tall. (-relative makes button definitions relative to the -at position). Defining any button position will remove the effect of the default pause button; use -NoMenu and -NoAdjust if you need to prevent the other mouse buttons. A typical command line might be: <movie name> -loop -leave -startat 2000 -playfor 2000 -quiet E640,512 P0,0 case is irrelevant. System Variables ---------------- There are several system variables which affect the Acorn Replay player program: ARMovie$ColourMethod Normally the Player program finds the number of colours by reading the OS Mode Variable 3 (NColour): values acceptable are 1, 3, 15, 63, 255, 65535, -1 signifying 1, 2, 4, 8 (fixed palette), 8 (variable palette), 16 and 32 bit per pixel modes. All is well for modes up to 8 bits per pixel, however a RISC OS 3.1x (or earlier) with an externally upgraded graphics system (such as the Computer Concepts ColourCard or State Machine G8) is incapable of returning 65535 from this call: the programmers of the 16 bit screen modes of these cards have adopted a variety of approaches to the problem(!). If NColour is less than 256, then Player checks Mode Variable 9 (Log2BPP) and if this is greater than 3, uses it to compute the 'correct' value of NColour. This method doesn't work for the Computer Concepts ColourCard (it returns 3, i.e. 8 bit), so the !Boot file of !ARMovie alters the check to Mode Variable 10 (Log2BPC). This area is extremely nasty, but other checks may be possible by arrangement with Acorn. ARMovie$Dir This is set by the !ARMovie application so that Player can get at its resources - Player won't work without this variable! Applications should only set this variable if it is not already set: for example, suppose you wish to play a movie on filer_boot of your application and therefore need to have Player work and have therefore included a copy of !ARMovie on your disc. You should do: IF "<ARMovie$Dir>"="" THEN Run <My$Dir>.!ARMovie.!Boot This allows for new versions of the !ARMovie application to replace the one on your disc by being seen first. IT WILL BE NECESSARY FOR THIS TO HAPPEN: FOR EXAMPLE, NEW VIDEO HARDWARE WILL NEED NEW VERSIONS OF !ARMovie AND Player. ARMovie$ExtraArgs Command strings to the Player program can exceed the 256 character limit, so an additional set of arguments of up to 256 characters can be placed in this system variable. After the Player program has read the value and used it, it sets it to a null string. ARMovie$Interpolate This variable controls the Player interpolating missing pixels in 8, 16 and 32 bit per pixel screen modes. There are three possible forms for setting the variable: (a) set to a string containing limit numbers: a,b. The number a is the maximum number of pixels per second which can be bilinearly interpolated on the machine; the number b is the maximum number of pixels per second which can be horizontally only linear interpolated on the machine. For example 'Set ARMovie$Interpolate 256000,512000' This allows the interpolation setting to depend on the movie being played. All interpolation can be turned off by setting 0,0. (b) set to a single character. This is equivalent to setting the value to '1024000,2048000' (if the bpp is 16 or 32) or '256000,512000' (for 8bpp). In 16 or 32 bpp, for most movies bilinear interpolation will be used (up to 320x256x12.5fps) and then horizontal only will be used (up to 320x256x25fps). For 8bpp only small/slow movies will get bilinear interpolation. For example 'Set ARMovie$Interpolate .' (c) unset (i.e. the default for the machine) or set to no characters. This is equivalent to setting the value to '128000,512000'. For very small or slow movies bilinear interpolation will be used, but for most movies (up to 160x128x25fps) horizontal only will be used. The following interpolation routines are available: In 8 bit modes, if xeig=yeig=1 or -big is used (i.e. mode 28 or -big) when playing YUV movies (of any compression format), then bilinear interpolation of the Y channel can be done. This uses a lot of cpu power, so this feature should only be used on more powerful machines playing slower movies. In 16 bit modes, if xeig=yeig=1 *or* xeig=yeig=2 with -big *or* xeig=2,yeig=1 with -big *or* xeig=1 and yeig=2, horizontal only interpolation can be done (and is on by default), whatever the colour space of the movie and whatever compression method is used (it costs a small amount [5 F cycles per interpolated pixel] to do it at 16bpp). Bilinear interpolation can be done whatever colour space and compression method the movie has. In 24 bit modes, if xeig=yeig=1 *or* xeig=yeig=2 with -big *or* xeig=2,yeig=1 with -big *or* xeig=1 and yeig=2, horizontal only interpolation can be done (and is on by default), whatever the colour space of the movie and whatever compression method is used (it costs very little [1 F cycle per interpolated pixel] to do it at 24bpp). Bilinear interpolation can be done whatever colour space and compression method the movie has. Interpolation is not available for -shape definitions (and thus for some -follow trajectories). ARMovie$Place Contains the position on screen where the player will put the movie as <leftx> <bottomy> - for example *set ARMovie$Place 640 512 Controlling programs must set this immediately before running the movie. Value is only used if -At parameter is not given. Use of this method is deprecated in favour of using -at. ARMovie$PrefMode Used by the machine's owner to get the movie to display in a different mode to the current one. For example, a user may like working in a very high resolution mode with a low number of colours. Player can display movies in such modes but they don't look good, so the user can set ARMovie$PrefMode to an alternative mode. Note that the user won't be able to see the buttons. See -mode for a description of the after RISC OS 3.50 syntax. ARMovie$PrefBigMode Used by the machine's owner to set a list of modes to use the -big display. The modes must be in order of ascending magnified size in the X direction - the first mode whose magnified number of X pixels is >= to the number required by the movie will be used, or the last mode of all. Each mode has to have square pixels: eigx=eigy; or have eigx=2, eigy=1, or eigx=1, eigy=0 (see -big for list of magnification factors for particular eig values). It can be 8, 16 or 32 bpp and can be any size. The list is separated by ';' characters. The best setting for ARMovie$PrefBigMode depends on your machine. See 'PrefBig' for a more detailed (but by no means exhaustive) list. The default setting is "13;49;28". See -mode for a description of the after RISC OS 3.50 syntax. Before RISC OS 3.50 example setting: *set ARMovie$PrefBigMode 49;28 After RISC OS 3.50 example settings: (TV standard monitor) *set ARMovie$PrefBigMode x320,y256,c32t,ex2,ey2;x384,y288,c32t (VGA monitor) *set ARMovie$PrefBigMode x320,y480,c16m,ex2,ey1;x480,y352,c16m;x640,y480,c32k ARMovie$Suffix Used by the machine's owner to preselect different versions of the movie if they are available. For example, if one knows that one's machine can only manage 12.5fps movies, *set ARMovie$Suffix to 2 and Player will preferentially play the 12.5fps movies. See the file on AE7 file naming conventions. ARMovie$4Colour If this variable is defined, then square pixel hi-resolution (e.g. mode 27) displays will be done in colour, provided a lookup table has been defined. The quality of this is not wonderful, particularly in the red/magenta area of the colour space, because these colours are missing from the default RISC OS colour palette. The program 'Make4col11', in the !ARMovie.MovingLine directory, will make the appropriate lookup tables for the current palette: this does take some time... The !ARMovie directory needs to be on a writeable file system in order for the extra files to be written to it. The program 'Make8Col11', in the !ARMovie.MovingLine directory, will make the appropriate lookup tables for the current palette of a 256 colour mode and takes even longer... If the Player cannot find the palette information for an unknown set of 256 colours, it will play in monochrome. Some system variables are used by Player to return information to the calling programs: ARMovie$Pause Player sets this to 0 if the movie was playing when it exited, 1 if it is paused on exit. This, plus the use of -paused, allows pause state to be preserved between the applications and the Player program. ARMovie$Return Player sets this to the actual position on screen of the video information. If -leave has been set or use user has exitted Player using the CAPTURE/EXIT button, this is the section that has been 'dirtied' and should be repainted by the window manager. It is set to <leftx> <bottomy> <rightx> <topy> <C> where the <C> is present only if the user has pressed CAPTURE/EXIT. ARMovie$ReturnCode If -NoError has been set, this will contain the textual error message. It will not exist if there was no error. ARMovie$Sound Player sets this to 0 if the sound has been disabled by clicking on one of the icons, 1 if it is enabled. This, plus the use of -mute, allows sound on/off state to be preserved between the applications and the Player program. ARMovie$Time Player sets this to the number of centiseconds of movie which have been played. Note that (like -playfor) this refers strictly to the amount of the movie, not the total elapsed time: playing a movie and playing the movie pausing every frame for an hour will end up with the same value for ARMovie$Time. ARMovie$Version Player sets this to its version number and date string. Acorn Replay Icons ------------------ The !ARMovie application has already *iconsprite'd the icons for the AE7 filetype into the window manager's icon pool - you should not include them (or any other system icons...) in your application's own !Sprite files. A standard set of icons is made available for the buttons used to control the player. They are in <ARMovie$Dir>.Sprites (plus Sprites22 and Sprites23 using the RISC OS 3.00 discipline for alternative resolutions). This gives all eight buttons with names 'exit' 'pause' 'single' 'fast' 'half' 'quiet' 'loud' and 'mute'. In addition, there are 'play', 'pplay' (pushed play) and 'playbig' buttons to complete a control panel. Applications wishing to use the button set should load (check for failure) the sprite file into their own sprite area (rather than *iconsprite'ing it - the definitions use up quite a bit of memory). If you wish to use your own icons for control buttons (for example, you want the buttons to be a different size) then please ensure that the buttons appearance (especially the shape of the glyph design) is close to the standard ones. The sprite file <ARMovie$Dir>.Default contains the default sprite used by the !ARMovie program to indicate that an ARMovie file can be dragged there. Not done yet ------------ The player does not, in fact, respond to double speed and half speed play buttons (h and f). File IO Access Resource file ---------------------------- The method by which the Player program accesses the ARMovie file can be altered. The file "<ARMovie$Dir>.Access" contains a list of the file root pathnames and an associated access method. For example: ADFS::HardDisc4 32 CDFS: 0 SCSI: 1 SCSI::Fred 64 The text, up to the first space, is matched against the left of the filename - if it is identical (including case) then the access method specified is used. Note that this allows the different access methods for different discs on the same filing system and for different sections of the same disc. 0 is used by default. There can be any number of spaces between the string and the access method. The access methods defined so far are: 0: double chunks if possible, single chunks if not enough RAM 1: single chunks 2-256: n K sub blocks of single chunks 257-512: ditto, but rounded up to 2K values 513-1024: ditto, but rounded up to 4K values 1025: next different method Note that access methods 1-1024 produce faster start up times (since only a single chunk is read) and use less memory (note that 2-1024 use the same amount of memory as 1 since the whole chunk must still be read). But they do require much faster access times - access=2 especially - compared with 0. The supplied default file is: SCSI: 1 ADFS: 128 ADPCM sound copyright notice ---------------------------- ADPCM sound code was implemented by Mark Taunton of Acorn Computers using original code supplied with the following notice: Copyright 1992 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands. All Rights Reserved Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Stichting Mathematisch Centrum or CWI not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.