contrib: add AppStream metadata
[libam7xxx.git] / contrib / howto-picopix.asciidoc
1 HOW-TO use a PicoPix on GNU/Linux
2 =================================
3
4 Philips/SagemCom pico projectors, like for instance the PicoPix 2055, usually
5 have a WVGA (854 x 480 pixels) native resolution, however they can be used to
6 project other resolutions if the software rescales the image.
7
8 First, update your system and download the free libam7xxx library and the
9 related programs.
10
11 On Debian and Ubuntu systems this can be done with the following commands:
12
13   sudo apt-get update
14   sudo apt-get install libam7xxx0.1-bin
15
16 Plug your PicoPix into one or two USB slots of your personal computer
17 (sometimes the second USB port is needed to ensure that the PicoPix has enough
18 power).
19
20 Wait for Philips logo to appear.
21
22 After the logo has disappeared, execute the following command in a terminal:
23
24   am7xxx-play -f x11grab -i :0.0
25
26 The video projection is on.
27
28 You can have two simple scripts to execute and terminate the program from
29 a graphical interface.
30
31 PicoPix-START.sh:
32
33   #!/bin/sh
34   am7xxx-play -f x11grab -i :0.0 -p 1 -z 0
35
36
37 PicoPix-STOP.sh:
38
39   #!/bin/sh
40   killall am7xxx-play
41   am7xxx-play -f x11grab -i :0.0 -p 0 -z 1 &
42   sleep 1
43   killall am7xxx-play
44
45
46 Save the shell scripts from above in files, and give the execute permissions
47 to the owner (or user group) via the command line  or via the graphical
48 interface
49 (http://sourcedigit.com/20111-how-to-run-a-shell-file-in-ubuntu-run-sh-file-in-ubuntu/).
50 You will then be able to execute the file by double-clicking on it.
51
52 If you want to specify a particular resolution you can pass it as a command
53 line option:
54
55   am7xxx-play -f x11grab -i :0.0 -o video_size=1280x768
56
57 When doing so you may notice that your PicoPix does not fully displays the
58 content of your desktop screen, which can be truncated at the bottom and at
59 the right. This is because of the WXGA (1280 x 768 pixels) resolution may be
60 different from your personal computer screen resolution. It is therefore
61 necessary to modify —temporarily— your personal computer screen resolution to
62 wanted resolution.
63
64 Take the following script:
65
66   #!/bin/sh
67
68   WIDTH=1280
69   HEIGHT=768
70
71   OUTPUT="LVDS-1" # See 'xrandr --listmonitors'
72
73   xrandr --newmode $(gtf ${WIDTH} ${HEIGHT} 60 | sed -ne 's/"//g;s/ Modeline //p')
74   xrandr --addmode ${OUTPUT} ${WIDTH}x${HEIGHT}_60.00
75   xrandr --output ${OUTPUT} --mode ${WIDTH}x${HEIGHT}_60.00
76   sleep 1
77   am7xxx-play -f x11grab -i :0.0 -p 1 -z 0 -o video_size=${WIDTH}x${HEIGHT}
78
79 Note:
80
81 In the example above, the personal computer screen is identified as "LVDS-1".
82 Maybe your computer screen has a different identifier. In this case, you will
83 have to replace "LVDS-1" with the correct identifier: open your terminal,
84 type "xrandr" and the terminal will list and describe your different screen
85 devices (more about xrandr utility here:
86 http://pkg-xorg.alioth.debian.org/howto/use-xrandr.html).
87
88 Also, in order to give back your computer screen its original resolution, you
89 should create a PicoPix-STOP.sh script like the following:
90
91   #!/bin/sh
92
93   ORIGINAL_WIDTH=1600
94   ORIGINAL_HEIGHT=900
95
96   OUTPUT="LVDS-1" # See 'xrandr --listmonitors'
97
98   killall am7xxx-play
99   am7xxx-play -f x11grab -i :0.0 -p 0 -z 1 &
100   sleep 1
101   killall am7xxx-play
102   xrandr --output ${OUTPUT} --mode ${ORIGINAL_WIDTH}x${ORIGINAL_HEIGHT}
103
104 Note:
105
106 In the example above, the original screen resolution is 1600x900 pixels. You
107 have to change this value and put your screen resolution value which you can
108 know via xrandr. Same for LVDS-1.
109
110 Once your video projection is over, you can execute the PicoPix-STOP.sh script
111 so that your computer screen returns to its original state.
112
113 You can then unplug the projector.
114
115 That's all folks!
116
117 This text is licensed under WTFPL. See http://www.wtfpl.net/ for more informations.