              Osmo4 Two-Dimensional MPEG-4 Player

                        Version 1.2
                     March 25, 2003

                          ENST
	
	http://perso.enst.fr/~dufourd/mpeg-4/


1 INTRODUCTION

Osmo4 is a nearly complete2D MPEG-4 compositor running on top of the MPEG-4 Systems framework 
("core") as developped by MPEG Systems Group.

This file gives an overview of the different options presented at the GUI level, optimization tips 
and development rule


2 Osmo4 Options

2.1 Menu File
	* Open File, Open URL: opens a local or remote presentation. If no DMIF filter is found to 
handle the URL the file can't be played.
	
	* Close, Restart: closes, restarts presentation
	
	* Export -> Screenshot: Exports the current screen to a file.
	* Export -> Start/Stop Capture: Starts/stop writing the screen content to files. This will generate a 
sequence of files in the target directory/format. Note that this will not be an accurate dump in the case of 
a complex scene, resulting in frame dropping at export and display level.


2.2 Menu View
	* Viewports: a list of author-defined viewports for the current presentation, none if no viewports
are present. The player only allows interaction with the top-level viewport stack, layer2D and CompositeTexture2D
viewports can not be modified by the user.

	* View WorldInfo: displays world info node if any

	* Original Size: reset display to original BIFS size converted to pixels

	* Full Screen: switches full screen mode on (accel: alt+CR). To exit fullscreen, press alt+CR or ESC

	* Special Modes:
		to zoom in in the presentation, click with the control key ("Ctrl") down
		to zoom out in the presentation, click with both the control key ("Ctrl") and the shift key down
		to move around (pan) in the presentation, drag the screen with the shift key down

2.3 Menu Options
	* BIFS frame rate: sets the refrsh rate of BIFS, eg the frequency at which time sensors are evaluated 
(scene is not always rendered at this rate). The higher the framerate, the smoother the presentation but the 
higher the CPU usage

	* BIFS Rendering Mode: see section 3

	* Clear Screen at end: displays MPEG/Osmo4 logo when closing the presentation

	* Use Custom Cursors: specifies whether the mouse cursor should be changed when pointing to an 
interactive part of the presentation. Each 2D sensor has a different aspect (except Anchor and TouchSensor)

	* Fast Rendering: lowers quality of color blending, image stretching and text bliting. Also lowers 
the bezier curves resolution.

	* Antialiasing: turns on anti aliasing (better look, higher CPU usage)

	* Text Always Antialiased: always draws text with best quality possible

	* YUV Hardware Support:
		- enable acceleration/...: whenever possible, YUV hardware is used. If the results are ugly (some 
graphics card don't support YUV hardware other than through overlays) turn it off. This also gives the current 
hardware support status:
	"enable acceleration": the YUV HW is currently disabled 
	"enabled": the YUV HW is currently enabled and active (a video is displayed through bitmap)
	"enable (not active)": the YUV HW is enabled but no bitmap node is present in the scene
	"No YUV hardware available": no supported YUV formats found on the hardware

		- list of YUV modes: change if the current hardware YUV is slow, ugly or ... This is needed for most 
graphics card where all the YUV modes don't always behave properly. The hardware YUV formats supported by the player 
are YV12, I420, IYUV, UYVY, Y422, UYNV, YUY2, YUNV, V422, YVYU. More info on YUV formats at 
			http://www.fourcc.org/fccyuv.htm. 


	* Scalable Zoom: enables scalable zooming of the scene by applying the appropriated top-level scaling. 
If not enabled zooming only stretches the scene to the desired size

	* Keep ratio: keeps aspect ratio or always fills the display area
NOTE on aspect ratio:
	The original aspect ratio may not be specified in BIFS presentation. In this case 
the player takes the enclosing square of the current display area as the original size (which makes an aspect ratio of 1:1)


3 Rendering Modes in Osmo4 

The scene state is being tracked from the different modification possible (natural textures/sounds updates, BIFS Commands
and field modification) in order to perform the minimal amount of scene graph traversal and scene redrawn. 

The player has several rendering modes that can be selected dynamically:

	* direct rendering: 
		this is the simplest mode, each time the scene is modified, all nodes are rendered from lowest to top 

	* Partial Redraw:
		In this mode the player performs an emulation of the draw, then computes the difference between the previous frame
and the current frame in terms of object bounds, and only redraws the part of the screen that has changed. This mode can run 
at a fixed frame rate in which case the emulation is computed each step, or at a free frame rate in which case the emulation is 
performed whenever the scene is invalidated

	* Split Tracking
		Split tracking is an option of partial redrawing which keeps track of screen changes as a set of rectangular areas
rather than one area. Ex: a background and two circles in the opposite corners of the screen would make the full scene 
to be redrawn whenever needed, whereas split tracking would only redraw the enclosing rectangles of the circles



4 Tips and Tricks

	Gdiplus doesn't handle YUV texturing. There is unfortunately no way to know whether a video is used as a texture
for a complex shape or as a flat video bitmap. The support for YUV is made through a simple YUV to RGB conversion at the 
renderer level in the case of texture mapping, but this conversion could be optimized a lot. This means that videos 
with fairly large resolution should be avoided as textures for complex shapes (but are allowed for bitmaps of course)

	Gdiplus cannot handle native textures that don't have a stride (width*Bpp) of 4. In this case the Osmo4 renderer
will have to copy all pixels one by one in a dedicated object which can be quite time consuming. It is thus recommended
to use natural textures that have a stride multiple of 4

	It may happen that a message "Fatal Error: DirectX : bad bounding rect" pops up at start-up of the player
This is actually not fatal, just press OK and go on

	When displaying images/video through the Bitmap node, the Osmo4 renderer attempts to use the graphics card hardware 
for YUV to RGB conversion and stretching, whenever possible (cf "menu options"). if you feel your machine 
should be able to display a large video better than what it does, here are some tips and tricks:
	* YUV->RGB conversion needs a lot of space on the graphic card. if you don't have a lot of memory on the board, upgrade..
	* a way to reduce memory needed by the board is to switch your resolution to 16 bpp rather than 24 or 32. By default
when switching  to fullscreen the player will try to use 16 bpp (faster, lighter in mem on board)
	* hardware conversion is done only for most common planar and packed YUV formats. Some cards may not support a given YUV 
mode in blitting, thus the YUV format used is configurable. If none of the supported YUV format is found on the graphics card, 
hardware will be disabled
	*by default (at each startup) the player selects the YUV format with the fastest bliting support
	

	Audio rendering may need tweaking depending on the sound card latency. If audio doesn't play correctly on your machine you 
can modify the player registry through two keys, both located in HKEY_CURRENT_USER\Software\MPEG-4\Im1\Osmo4
	* "AudioFPS" key: indicates the theoretical audio "frame rate", eg how the duration of a single hardware buffer. 
For example, AudioFPS=15 (default) means that each audio buffer lasts 1000/15 = 66.667 milli seconds. This should be fine for most 
audio boards, you can increase this value to decrease the audio latency if the sounds is OK, or decrease this value to have larger 
buffering in case the audio doesn't play correctly. Note that some cards will just not work properly with too small audio buffers
	* "AudioBuffers" key: indicates the number of buffers used for rendering. If the audio seems to have looping chunks while 
playing increase this value. The total amount of audio buffering by the player is "AudioBuffers*1000/AudioFPS" milli seconds, 
the default configuration giving 8*1000/15 = 533.334 ms buffer



5 ACKNOWLEDGEMENT and extra software

5.1 Osmo4 Software

	Most of the code object architecture (proxies, class names, ...) is taken from the original MPEG-4 systems reference 
software IM1-2D and was developped by TiLab (formerly CSELT S.pA.)
A big thanks to the original developers Matthew Leditschke and Gianluca Di Cagno

5.2 MPEG4 Systems reference software
	This player is built on top of IM1, the MPEG4 Systems reference software available in ISO/IEC 14496-5
The following companies have taken part in this software's develoment:

Triton R&D, ltd.
Optibase Ltd
Tilab (formerly CSELT)
France Telecom R&D
Apple Computer Inc
Thomson multimedia
IBM

5.3 JavaScript Engine

	The JavaScript interpreter used in Osmo4 has been developed by the Mozilla Organization
available at http://www.mozilla.org/js/spidermonkey/. The JavaScript engine is distributed under the terms
of the Mozilla Public License and cross licensing under MPL/GPL/LGPL should be soon (is?) available

5.4 PNG Support
	The player supports PNG through the official PNG software, available at 
http://www.libpng.org/pub/png/libpng.html and distributed under the zlib license


5.5 MP3 Support
	The player supports MP3 audio through the LGPL fixed-point library MAD available at 
http://mad.sourceforge.net/. The MAD decoder is not included in the source tree for copyrights/patent reasons

5.6 AAC Support
	The player supports AAC audio through the GPL AAC library FAAD2 available at 
http://www.audiocoding.com/. The FAAD2 decoder is not included in the source tree for copyrights/patent reasons

5.7 MPEG4 Video support
	The player supports MPEG4 Visual Simple Profile through the XviD GPL library available at
http://www.xvid.org/. The XviD decoder is not included in the source tree for copyrights/patent reasons.
The decoder has to be patched to compile in IM1, the patch is in /IM1Decoders/dec_xvid


