= SAGE installation and usage =

== Installation ==

=== Prerequisities ===

These packages are required to compile SAGE on Ubuntu:
* build-essential
* mesa-utils
* python-wxtools
* libmagickwand-dev
* libreadline6-dev 
* libsdl-dev 
* libxmu-dev 
* libxi-dev 
* freeglut3-dev 
* libglew1.5-dev 

Optionally, these packages are helpful in monitoring the system:
* ethtool 
* iftop

Before compiling SAGE make sure that the OpenGL library is linked properly in /usr/lib - some GPU drivers tend to break the links.

=== Compilation ===

To compile SAGE simple ''make'' and ''sudo make install'' is required. 
There is a configure script distributed with SAGE sources, but all it does is echo "DONE", so you don't have to run it.

=== Environment setup ===

After installation SAGE there is some environment setup required.

1. Environmental variables[[BR]]
 You need to setup environmental variables even if you don't start an interactive session but just run a command using ssh. To achieve this you have to:
 * change one of the first lines in .bashrc from:
{{{ 
  [ -z "$PS1" ] && return 
}}}
 to:
{{{
  [ -z "$PS1" ] && . /etc/profile.d/sage.sh && return
}}}
1. Libraries location[[BR]]
 Some applications using SAGE may not find SAGE libraries if you run an amd64 system. All you have to do is:
 * enter SAGE installation directory (/usr/local/sage by default)
 * make a symlink (ln -s) to lib64 folder and name it lib (''sudo ln -s lib64 lib'')
 * check whether file /etc/ld.so.conf.d/sage.conf exists; if not - create it and enter /usr/local/sage/lib
 * run ''sudo ldconfig''
1. Install openssh-server (''sudo apt-get install openssh-server'')
1. Disable SSH strict host key checking (in /etc/ssh/ssh_config line ''!StrictHostKeyChecking no'')
1. Setup static IP addresses for interfaces used to communicate between wall and access machine (using /etc/network/interfaces file)

=== Access machine ===

Previous steps are all required on both tile an access machines. On access machine, however, there is some more action to perform.

1. To operate the wall using Wiimote you need to have a Bluetooth adapter and these libraries installed in the system:
 * wiiuse v.0.12 ([http://downloads.sourceforge.net/project/wiiuse/wiiuse/v0.12/wiiuse_v0.12_src.tar.gz download])
 * wiiusecpp v.0.12 ([http://www.missioncognition.net/downloads/wiiusecpp_v0.12_src.tar.gz download]) [[BR]]
 More information about wiiusecpp can be found at [http://www.missioncognition.net/software/wiiusecpp.html developer site].
1. Setup SSH login to all tile computers using rsa key (without password)
1. Edit SAGE configuration files to suit your needs (fsManager.conf and tile*.conf in ~/.sageConfig or /usr/local/sage/sageConfig); configuration files for wall at PSNC can be found in repo

=== Tile machines ===

Also on tile machines there is one thing that you need to do after finishing the environmet setup, which is Xorg server setup. More information can be found in XorgSetup article.

== Additional software ==

=== VLC ===

VLC is the best movie player for SAGE. Information about it and downloads can be found at [http://www.vislab.uq.edu.au/research/optiputer/software/vlc/ developer site]. To use VLC you have to:
1. Unpack the archive
1. Run ''./configure'' and install any required library
1. Change few lines in modules/video_output/sage.cpp file (according to SAGE forum [http://www.sagecommons.org/index.php?option=com_ccboard&view=postlist&forum=4&topic=134&Itemid=70 topic]) [[BR]]
 {{{
For the colors: you have to swap the bit masks for the RV16 format (WORDS_BIGENDIAN),
line 185 in sage.cpp. After that, it should put the right colors in the right bits. 
(I dont remember using 16-bit colors)
 }}}
1. If you have any problems during compilation, on the bottom of [http://www.vislab.uq.edu.au/research/optiputer/software/vlc/ developer site] there are most common issues and solutions.
1. Create configuration files for SAGE:
 * go to ~/.sageConfig/applications directory
 * make 2 copies of any configuration file you have already used and name it vlc.conf and cvlc.conf
1. Run ''vlc'' (with user interface) or ''cvlc'' (without user interface) with the syntax:
 {{{
{vlc|cvlc} --vout sage [--no-video-title-show] [--loop] filename
 }}}

=== mplayer ===

Mplayer is slightly less effective than VLC when displaying videos on SAGE wall, but is still a very nice player. To use you have to:

1. Download the package from [http://www.sagecommons.org/phocadownload/applications/mplayer-1.0rc3.tar.gz developer site]
1. Unpack the archive
1. Run ''./configure''
1. ''make'' and ''sudo make install''
1. Create configuration files for SAGE:
 * go to ~/.sageConfig/applications directory
 * make a copy of any configuration file you have already used and name it mplayer.conf
1. Run ''mplayer'' with the syntax:
 {{{
mplayer -vo sage [-loop 1] filename
 }}}

=== qshare ===

Qshare is a dedicated application to share your desktop on SAGE wall. It is bundled with SAGE sources, but needs to be compiled seperately. It prooved to be a bit quicker than standard VNC client with SAGE plugin. To use qshare all you have to do is:
1. Enter apps/qshare directory
1. Run ''GO'' script to make and install the application
1. Run ''qshare'' to start sharing your desktop

=== !DecklinkCapture ===

!DecklinkCapture allows to send stream grabbed with Blackmagic Decklink cards to SAGE wall. To use it you have to:
1. Download drivers from [http://www.blackmagic-design.com/support/ Blackmagic page] and install them according to instructions given
1. Enter apps/DecklinkCapture directory
1. ''make'' and ''make install''
1. Run ''decklinkcapture -l'' to see supported cards, video modes and video inputs
1. Run ''decklinkcapture'' with following syntax:
 {{{
decklinkcapture -i [video_mode] [video_input]
 }}}
 where video_mode and video_input are numbers read in previous step

=== OpenGL wrapper ===

OpenGL wrapper lets you send your OpenGL applications to wall without any changes in code. It is simply a library which overrides standard glutSwapBuffer implementation. To use it you have to:
1. Enter app/gl directory
1. Change name (or copy) desired Makefile.* to Makefile (according to architecture)
1. ''make'' and ''sudo make install''
1. To run your application, enter:
 {{{
GO* your_application
 }}}
 where ''GO*'' is one of ''GO'' scripts in gl directory

== Usage ==

=== Start SAGE ===

1. Power on all computers
1. Run Xorg on all tile machines (''runxall'' script on access machine)
1. Run ''sage'' on access machine
1. Click ''start''

=== Movies ===
See [[SageInstallation#VLC|VLC]] or [[SageInstallation#mplayer|mplayer]]

=== Pictures ===
To display pictures you can use ''imageviewer'', which is part of !FileViewer application bundled with SAGE. It is compiled alongside SAGE, so you don't have to do anything to get it working. ''Imageviewer'' can show images "as is", which means sending a lot of data through network, or perform DXT compression to limit it. DXT is done only on first display of specific image - the compressed version is saved in the same place the original image is located. During next displays, first a check is performed whether .dxt file exists, an when it does it is immediately sent to the wall.

=== OpenGL ===
See [[SageInstallation#OpenGLwrapper|OpenGL Wrapper]]

=== Own desktop ===
See [[SageInstallation#qshare|qshare]]

=== Playstation 3 ===
See [[SageInstallation#DecklinkCapture|DecklinkCapture]][[BR]]
Unfortunatelly, Playstation 3 sends an HDCP signal over HDMI port, which Blackmagic cards can not grab due to legal issues. The only possible method to show PS3 screen on the wall is to use Composite or Component adapter. Component adapter is prefered due to better video quality than Composite.

=== Wiimote ===
You can control windows displayed on the wall using Wiimote controller. To do this you have to install proper libraries first (see [[SageInstallation#Accessmachine|Access machine]]). You also need a simple circuit containing IR LEDs. Instructions for building such circuit can be found on the Internet by searching for Wii Sensorbar. If SAGE was compiled with required libraries and you have your circuit in place, you have to set wiimote capture to start with SAGE. To do this you have to:
* Run ''sage''
* Click ''Advanced mode''
* Click ''Settings'' in the SAGE section (first from the top)
* In ''ON SAGE STARTUP'' enter:
 {{{
python ../dim/dim.py
python ../dim/hwcapture/wiimote.py localhost
 }}}
 If any line containing dim.py already exists, delete it.
* Comment line:
 {{{
python ../dim/hwcapture/localPointer.py localhost
}}}
 using #:
 {{{
#python ../dim/hwcapture/localPointer.py localhost
 }}}
* Confirm by clicking ''OK'' in the window
* Turn on Wiimote in discovery mode (1+2 button press)
* Start SAGE with ''START'' button

Now you can control windows on the wall using Wiimote controller. To select a window just point to it. Then you can perform following actions:
* move windows (A button)
* resize window (B button)
* rotate window (Left and Right buttons)
* move window to front or send to back (Up and Down buttons)
* maximize a window (Home button)