This is ../../sources/bino/doc/bino.info, produced by makeinfo version
4.13 from ../../sources/bino/doc/bino.texi.

This manual was last updated 24 April 2011 for version 0.9.4 of Bino.

   Copyright (C) 2011 Martin Lambers (<marlam@marlam.de>), Stefan
Eilemann (<eile@eyescale.ch>), Frédéric Devernay
(<Frederic.Devernay@inrialpes.fr>)

     Copying and distribution of this file and the referenced image
     files, with or without modification, are permitted in any medium
     without royalty provided the copyright notice and this notice are
     preserved. These files are offered as-is, without any warranty.

INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* bino: (bino).         A 3D video player with multi-display support.
END-INFO-DIR-ENTRY


File: bino.info,  Node: Top,  Next: Overview,  Up: (dir)

Bino
****

This manual was last updated 24 April 2011 for version 0.9.4 of Bino.

   Copyright (C) 2011 Martin Lambers (<marlam@marlam.de>), Stefan
Eilemann (<eile@eyescale.ch>), Frédéric Devernay
(<Frederic.Devernay@inrialpes.fr>)

     Copying and distribution of this file and the referenced image
     files, with or without modification, are permitted in any medium
     without royalty provided the copyright notice and this notice are
     preserved. These files are offered as-is, without any warranty.

* Menu:

* Overview::
* Invocation::
* Input Layouts::
* Output Techniques::
* File Name Conventions::
* Interactive Control::
* Crosstalk Ghostbusting::
* Multi Display Support::


File: bino.info,  Node: Overview,  Next: Invocation,  Prev: Top,  Up: Top

1 Overview
**********

Bino is a 3D video player with multi-display support.

   3D videos are more accurately called stereoscopic videos. Such
videos have separate views for the left and right eye and thus allow
depth perception through stereopsis.

   All input files are combined into one media source, so you can have
video, audio, and subtitle streams in separate files. The files are
decoded with the FFmpeg (http://ffmpeg.org/)  libraries, so URLs and
other special constructs are supported.

   Bino supports a wide variety of stereoscopic input layouts and
display techniques.


File: bino.info,  Node: Invocation,  Next: Input Layouts,  Prev: Overview,  Up: Top

2 Invocation
************

Synopsis: `bino [OPTION...] [FILE...]'

`--help'
     Print help.

`--version'
     Print version.

`-n'
`--no-gui'
     Do not use the GUI, just play the given input in a plain window
     using the parameters given on the command line.

`-l'
`--log-level=LEVEL'
     Select log level: DEBUG, INFO, WARNING, ERROR, or QUIET.

`-v'
`--video=STREAM'
     Select video stream (1-n, depending on the input).

`-a'
`--audio=STREAM'
     Select audio stream (1-n, depending on the input).

`-s'
`--subtitle=STREAM'
     Select subtitle stream (1-n, depending on the input).

`-i'
`--input=TYPE'
     Select input type. *Note Input Layouts::.

`-o'
`--output=TYPE'
     Select output type. *Note Output Techniques::.

`-S'
`--swap-eyes'
     Swap left/right view.

`-f'
`--fullscreen'
     Fullscreen.

`-c'
`--center'
     Center window on screen.

`--subtitle-encoding=ENC'
     Set subtitle encoding.

`--subtitle-font=FONT'
     Set subtitle font name.

`--subtitle-size=N'
     Set subtitle font size.

`--subtitle-scale=S'
     Set subtitle scale factor.

`--subtitle-color=COLOR'
     Set subtitle color, in [AA]RRGGBB format.

`--subtitle-parallax=VAL'
     Subtitle parallax adjustment (-1 to +1).

`-P'
`--parallax=VAL'
     Parallax adjustment (-1 to +1).

`-C'
`--crosstalk=VAL'
     Crosstalk leak level (0 to 1). Comma-separated values for the
     R,G,B channels.

`-G'
`--ghostbust=VAL'
     Amount of crosstalk ghostbusting to apply (0 to 1).

`-b'
`--benchmark'
     Benchmark mode: no audio, no time synchronization, output of
     frames-per-second measurements.


File: bino.info,  Node: Input Layouts,  Next: Output Techniques,  Prev: Invocation,  Up: Top

3 Input Layouts
***************

Bino supports the following stereoscopic input layouts:
MONO
     Single view (2D).

SEPARATE-LEFT-RIGHT
     Left/right view in separate streams, left first.

SEPARATE-RIGHT-LEFT
     Left/right view in separate streams, right first.

TOP-BOTTOM
     Left view top, right view bottom.

TOP-BOTTOM-HALF
     Left view top, right view bottom, half height.

BOTTOM-TOP
     Left view bottom, right view top.

BOTTOM-TOP-HALF
     Left view bottom, right view top, half height.

LEFT-RIGHT
     Left view left, right view right.

LEFT-RIGHT-HALF
     Left view left, right view right, half width.

RIGHT-LEFT
     Left view right, right view left.

RIGHT-LEFT-HALF
     Left view right, right view left, half width.

EVEN-ODD-ROWS
     Left view even rows, right view odd rows.

ODD-EVEN-ROWS
     Left view odd rows, right view even rows.

   The default is to autodetect the input type from meta data stored in
the file.  If this fails, Bino tries to autodetect the input type based
on the file name.  *Note File Name Conventions::.  If that fails, too,
Bino guesses based on the resolution of the input.


File: bino.info,  Node: Output Techniques,  Next: File Name Conventions,  Prev: Input Layouts,  Up: Top

4 Output Techniques
*******************

Bino supports the following stereoscopic display techniques:
MONO-LEFT
     Left view only.

MONO-RIGHT
     Right view only.

TOP-BOTTOM
     Left view top, right view bottom.

TOP-BOTTOM-HALF
     Left view top, right view bottom, half height.

LEFT-RIGHT
     Left view left, right view right.

LEFT-RIGHT-HALF
     Left view left, right view right, half width.

EVEN-ODD-ROWS
     Left view even rows, right view odd rows.

EVEN-ODD-COLUMNS
     Left view even columns, right view odd columns.

CHECKERBOARD
     Left and right view in checkerboard pattern.

HDMI-FRAME-PACK
     HDMI frame packing mode (left top, right bottom, plus extra blank
     lines separating the two views). This mode is only necessary if
     you are forcing your display into the corresponding HDMI 3D mode.
     A description how to do this on GNU/Linux can be found in this
     post to the Bino mailing list
     (http://lists.nongnu.org/archive/html/bino-list/2011-03/msg00033.html).

RED-CYAN-MONOCHROME
     Red/cyan anaglyph, monochrome method.

RED-CYAN-HALF-COLOR
     Red/cyan anaglyph, half color method.

RED-CYAN-FULL-COLOR
     Red/cyan anaglyph, full color method.

RED-CYAN-DUBOIS
     Red/cyan anaglyph, high-quality Dubois method.

GREEN-MAGENTA-MONOCHROME
     Green/magenta anaglyph, monochrome method.

GREEN-MAGENTA-HALF-COLOR
     Green/magenta anaglyph, half color method.

GREEN-MAGENTA-FULL-COLOR
     Green/magenta anaglyph, full color method.

GREEN-MAGENTA-DUBOIS
     Green/magenta anaglyph, high-quality Dubois method.

AMBER-BLUE-MONOCHROME
     Amber/blue anaglyph, monochrome method.

AMBER-BLUE-HALF-COLOR
     Amber/blue anaglyph, half color method.

AMBER-BLUE-FULL-COLOR
     Amber/blue anaglyph, full color method.

AMBER-BLUE-DUBOIS
     Amber/blue anaglyph, high-quality Dubois method.

RED-GREEN-MONOCHROME
     Red/green anaglyph, monochrome method.

RED-BLUE-MONOCHROME
     Red/blue anaglyph, monochrome method.

STEREO
     OpenGL quad-buffer stereo.

EQUALIZER
     Multi-display OpenGL via Equalizer with a 2D canvas setup.

EQUALIZER-3D
     Multi-display OpenGL via Equalizer with a 3D screen setup.

   For stereo input, the default is STEREO if the display supports it,
otherwise RED-CYAN-DUBOIS. The default for mono input is MONO-LEFT.


File: bino.info,  Node: File Name Conventions,  Next: Interactive Control,  Prev: Output Techniques,  Up: Top

5 File Name Conventions
***********************

If the meta data stored in a file does not indicate its stereoscopic
layout, Bino tries to guess it by looking at the last part of the file
name before the file name extension (`.ext').

   The following file name forms are recognized:
`*-lr.ext'
     LEFT-RIGHT

`*-lrh.ext'
`*-lrq.ext'
     LEFT-RIGHT-HALF

`*-rl.ext'
     RIGHT-LEFT

`*-rlh.ext'
`*-rlq.ext'
     RIGHT-LEFT-HALF

`*-tb.ext'
`*-ab.ext'
     TOP-BOTTOM

`*-tbh.ext'
`*-abq.ext'
     TOP-BOTTOM-HALF

`*-bt.ext'
`*-ba.ext'
     BOTTOM-TOP

`*-bth.ext'
`*-baq.ext'
     BOTTOM-TOP-HALF

`*-eo.ext'
`*-eoq.ext'
`*-3dir.ext'
     EVEN-ODD-ROWS

`*-oe.ext'
`*-oeq.ext'
`*-3di.ext'
     ODD-EVEN-ROWS

`*-2d.ext'
     MONO


File: bino.info,  Node: Interactive Control,  Next: Crosstalk Ghostbusting,  Prev: File Name Conventions,  Up: Top

6 Interactive Control
*********************

Bino reacts on a number of keyboard shortcuts during playback.

   Make sure that the video area has the keyboard focus before using
these shortcuts, e.g. by clicking into it.

   The following shortcuts are recognized:
`ESC'
     Leave fullscreen mode, or quit when in window mode.

`q'
     Quit.

`p'

`SPACE'
     Pause / unpause.

`f'
     Toggle fullscreen.

`c'
     Center window.

`e'
     Swap left/right eye.

`v'
     Cycle through available video streams.

`a'
     Cycle through available audio streams.

`a'
     Cycle through available subtitle streams.

`1'

`2'
     Adjust contrast.

`3'

`4'
     Adjust brightness.

`5'

`6'
     Adjust hue.

`7'

`8'
     Adjust saturation.

`<'

`>'
     Adjust parallax.

`('

`)'
     Adjust ghostbusting.

`LEFT'

`RIGHT'
     Seek 10 seconds backward / forward.

`UP'

`DOWN'
     Seek 1 minute backward / forward.

`PAGE UP'

`PAGE DOWN'
     Seek 10 minutes backward / forward.

`Mouse click'
     Seek according to the horizontal click position.


File: bino.info,  Node: Crosstalk Ghostbusting,  Next: Multi Display Support,  Prev: Interactive Control,  Up: Top

7 Crosstalk Ghostbusting
************************

Many stereoscopic display devices suffer from crosstalk between the
left and right view. This results in ghosting artifacts that can
degrade the viewing quality, depending on the video content.

   Bino can optionally reduce the ghosting artifacts. For this, it
needs two know
  1. the amount of crosstalk of your display device and

  2. the amount of ghostbusting that is adequate for the video you want
     to watch.

   Please note that ghostbusting does not work with anaglyph glasses.

   To measure the display crosstalk, do the following:

  1. Display the `gamma-pattern-tb.png' (gamma-pattern-tb.png) image
     and correct the display gamma settings according to the included
     instructions.  You need to have correct gamma settings before
     measuring crosstalk.

  2. Display the `crosstalk-pattern-tb.png' (crosstalk-pattern-tb.png)
     image and determine the crosstalk levels using the included
     instructions.

   You now have three crosstalk values for the red, green, and blue
channels. You can now tell Bino about this using the `--crosstalk'
option. For example, if you have measured 8% of crosstalk for red, 12%
for green, and 10% for blue, use
     $ bino --crosstalk 0.08,0.12,0.10

   Once you know the crosstalk levels of your display device, you can
set the amount of ghostbusting that Bino should apply using the
`--ghostbust' option. This will vary depending on the content you want
to watch. Movies with very dark scenes should be viewed with at least
50% ghostbusting (`--ghostbust 0.5'), whereas overall bright movies,
where crosstalk is less disturbing, could be viewed with a lower level
(e.g.  `--ghostbust 0.1').

   To check if you crosstalk calibration is correct, display the
crosstalk patterns with full ghostbusting, like this:
     $ bino --crosstalk 0.08,0.12,0.10 --ghostbust 1.0 crosstalk-pattern-tb.png
   The remaining crosstalk should optimally be 0%.


File: bino.info,  Node: Multi Display Support,  Prev: Crosstalk Ghostbusting,  Up: Top

8 Multi Display Support
***********************

Bino supports multi-display output via the Equalizer framework.

   This is how it works:

8.1 Building Bino with Equalizer Support
========================================

First, install Equalizer 0.9.3 (also known as 1.0-beta) or later. See
`http://www.equalizergraphics.com/'.  Verify that it works by running
the included eqHello example.

   Then, build Bino with Equalizer support by using the
`--with-equalizer' configure option.
     $ ./configure --with-equalizer

   Now you need an Equalizer configuration file for your display setup.

8.2 Configuring Equalizer and Starting Bino
===========================================

Bino needs a two-dimensional Equalizer canvas (= combined screen area),
subdivided into segments (= single display areas). For example, if you
have two projectors that project onto a 2m x 1m screen side-by-side,
then your canvas is 2m x 1m large, and you have two segments: the first
segment fills the left half of the canvas, and the second segment fills
the right half.

   Next, Equalizer needs to know how to render into each segment. For
this purpose, you define several hierarchical objects: nodes (=
processes, possibly on different systems), pipes (= graphics cards),
windows (= output windows with OpenGL contexts), and channels (= parts
of windows). The video output happens at the channel level: each
channel is assigned to one segment of the canvas. Most probably you
just have one fullscreen window per pipe, and a single output channel
per window.

   Note that one node is special: the application node, which is the
node that you initially start (the other nodes are started
automatically by Equalizer).  The application node is called 'appNode'
in the Equalizer configuration, and Bino will play audio only on the
application node. All video output is then synchronized to this audio
output.

   Once you have your configuration file (examples are given below),
you can check if it works correctly using the `eqHello' example:
     $ eqHello --eq-config configuration.eqc

   Once you made sure that this works, you can start Bino using this
command:
     $ bino -o equalizer --eq-config configuration.eqc video.mp4

   Note that all your nodes need access to the video file using the
same name, so a shared filesystem is helpful if you use multiple
systems.

   To play live video from a webcam or TV card, you can set up a
streaming server using ffserver (part of FFmpeg) or vlc, and then give
the appropriate URL to Bino. You can use multicast to stream the video
to multiple systems efficiently.

   The output mode `-o equalizer-3d' allows to configure non-planar
projections.  Bino projects the video onto a virtual screen in 3D
space. The screen is located in the distance of the biggest
front-facing segment, and sized to fill the wall optimally. By
configuring the output segments accordingly, various advanced display
configurations can be used, e.g. displays rotated around the Z axis by
an arbitrary angle or non-planar screens.

8.3 Example Configurations
==========================

8.3.1 Simple 2D video output
----------------------------

In this example, you have a 2m x 1m screen and two projectors: one for
the left half of the screen, and one for the right half. The two
projectors are connected to two graphics cards on the same system.

   In this situation, you have one node with two pipes, and each pipe
has a fullscreen window with a single output channel. The first output
channel is assigned to the left segment, and the second output channel
is assigned to the right channel. The resulting configuration looks
like this:

     server
     {
         config
         {
             appNode
             {
                 pipe { device 0 window { attributes { hint_fullscreen ON } channel { name "left" }}}
                 pipe { device 1 window { attributes { hint_fullscreen ON } channel { name "right" }}}
             }
             observer {}
             layout { view { observer 0 }}
             canvas
             {
                 layout 0
                 wall
                 {
                     bottom_left  [ 0.0  0.0 -1 ]
                     bottom_right [ 2.0  0.0 -1 ]
                     top_left     [ 0.0  1.0 -1 ]
                 }
                 segment { channel "left" viewport [ 0.0 0.0 0.5 1.0 ] }
                 segment { channel "right" viewport [ 0.5 0.0 0.5 1.0 ] }
             }
             compound
             {
                 compound { channel ( view 0 segment 0 ) swapbarrier {} }
                 compound { channel ( view 0 segment 1 ) swapbarrier {} }
             }
         }
     }

8.3.2 3D video output across multiple systems
---------------------------------------------

In the following example, you have a 4m x 3m screen for 3D projection
via passive stereo (e.g. polarization). You have two systems, "render1"
and "render2", each equipped with two graphics cards. The two cards on
"render1" generate two images for the left half of the screen: one for
the left eye view and one for the right eye view. The two cards on
"render2" generate left and right view for the right half of the
screen. Additionally, you have a system called "master" which has a
sound card and should display a small control window.

   This setup is very similar to the situation shown in
`multi-display-vrlab.jpg' (multi-display-vrlab.jpg).

   The configuration looks like this:

     server
     {
         connection { hostname "master" }
         config
         {
             appNode
             {
                 connection { hostname "master" }
                 pipe { window { viewport [ 100 100 400 300 ] channel { name "control" }}}
             }
             node
             {
                 connection { hostname "render1" }
                 pipe { device 0 window { attributes { hint_fullscreen ON } channel { name "render1left" }}}
                 pipe { device 1 window { attributes { hint_fullscreen ON } channel { name "render1right" }}}
             }
             node
             {
                 connection { hostname "render2" }
                 pipe { device 0 window { attributes { hint_fullscreen ON } channel { name "render2left" }}}
                 pipe { device 1 window { attributes { hint_fullscreen ON } channel { name "render2right" }}}
             }
             observer {}
             layout { view { observer 0 }}
             canvas
             {
                 layout 0
                 wall
                 {
                     bottom_left  [ 0.0 0.0 -1 ]
                     bottom_right [ 4.0 0.0 -1 ]
                     top_left     [ 0.0 3.0 -1 ]
                 }
                 segment { channel "render1left"  viewport [ 0.0 0.0 0.5 1.0 ] }
                 segment { channel "render1right" viewport [ 0.0 0.0 0.5 1.0 ] }
                 segment { channel "render2left"  viewport [ 0.5 0.0 0.5 1.0 ] }
                 segment { channel "render2right" viewport [ 0.5 0.0 0.5 1.0 ] }
                 segment { channel "control"      viewport [ 0.0 0.0 1.0 1.0 ] }
             }
             compound
             {
                 compound { eye [ LEFT  ] channel ( view 0 segment 0 ) swapbarrier {} }
                 compound { eye [ RIGHT ] channel ( view 0 segment 1 ) swapbarrier {} }
                 compound { eye [ LEFT  ] channel ( view 0 segment 2 ) swapbarrier {} }
                 compound { eye [ RIGHT ] channel ( view 0 segment 3 ) swapbarrier {} }
                 compound {               channel ( view 0 segment 4 ) swapbarrier {} }
             }
         }
     }

8.3.3 Non-planar Displays
-------------------------

The `-o equalizer-3d' mode allows to set up arbitrary-oriented screens
using either the wall-based or projection-based 3D frustum descriptions.

   In this example we set up two 16:10 displays side-by-side which have
been rotated around their Z axis by 1.3 degrees radians (~74 degrees).
The image `multi-display-rotated.jpg' (multi-display-rotated.jpg)
illustrates this setup. Other setups include distortion-correct
projection for curved screens, or arbitrarily-placed screens in a 3D
space.

   First, we rotate a normally-aligned screen by 1.3 degrees and output
the result:

     eq::Matrix4f matrix(eq::Matrix4f::IDENTITY);
     matrix.rotate(1.3f, eq::Vector3f::FORWARD);
     wall.bottomLeft = matrix * wall.bottomLeft;
     wall.bottomRight = matrix * wall.bottomRight;
     wall.topLeft = matrix * wall.topLeft;
     std::cout << wall << std::endl;

   yields a rotated screen centered on the origin:

     bottom_left  [   -0.69578     0.6371         -1 ]
     bottom_right [   -0.26778    -0.9046         -1 ]
     top_left     [    0.26778     0.9046         -1 ]

   This screen has to be moved along the X-axis for the left and right
screen by 0.5195m, which places the edges of the screen on the origin.
The resulting wall descriptions are used for the left and right
segment, as shown in the configuration below.

   The configuration references two GPUs full-screen output. By
changing the node resource section, the outputs may be mapped to two
computers. When disabling the fullscreen mode and setting 'device 0'
for the second pipe, two windows simulate this setup on a single
machine.

     global
     {
         EQ_WINDOW_IATTR_HINT_FULLSCREEN ON
     }

     server
     {
         config
         {
             appNode
             {
                 pipe
                 {
                     device 0
                     window
                     {
                         viewport [ .215 .5 .4 .4 ]
                         channel { name "channel1" }
                     }
                 }
                 pipe
                 {
                     device 1
                     window
                     {
                         viewport [ .285 .1 .4 .4 ]
                         attributes{ hint_drawable window }
                         channel { name "channel2" }
                     }
                 }
             }

             layout { view{ }}
             canvas
             {
                 layout   0

                 segment
                 {
                     channel  "channel1"
                     wall
                     {
                         bottom_left  [   -1.21528     0.6371         -1 ]
                         bottom_right [   -0.78728    -0.9046         -1 ]
                         top_left     [   -0.25172     0.9046         -1 ]
                     }
                 }
                 segment
                 {
                     channel  "channel2"
                     wall
                     {
                         bottom_left  [   -0.17628     0.6371         -1 ]
                         bottom_right [    0.25172    -0.9046         -1 ]
                         top_left     [    0.78728     0.9046         -1 ]
                     }
                 }
             }

             compound
             {
                 compound
                 {
                     channel ( segment 0 )
                     swapbarrier{}
                 }
                 compound
                 {
                     channel ( segment 1 )
                     swapbarrier{}
                 }
             }
         }
     }



Tag Table:
Node: Top768
Node: Overview1523
Node: Invocation2187
Node: Input Layouts3879
Node: Output Techniques5113
Node: File Name Conventions7534
Node: Interactive Control8383
Node: Crosstalk Ghostbusting9557
Node: Multi Display Support11637

End Tag Table


Local Variables:
coding: utf-8
End:
