README
1===============================================================================
2POV-Ray 3.7 for UNIX/Linux - README file
3
4For the generic source distribution for UNIX/Linux
5===============================================================================
6
7This is the README file for the generic UNIX/Linux distribution of the
8POV-Ray 3.7 source code.
9
10
11===================
12Source code package
13===================
14
15+----------------------------------------------------------------------------+
16| NOTE: If this file does not reside in the root directory of your POV-Ray |
17| source package, you have received a platform-neutral package. In that case |
18| make sure to run the following command before you proceed: |
19| |
20| cd unix/ ; ./prebuild.sh ; cd ../ |
21+----------------------------------------------------------------------------+
22
23This package contains the complete source code of POV-Ray for UNIX
24as well as its accompanying HTML documentation and supporting files.
25The package substructure is organized as follows:
26
27 source/ Platform-independent source code (POV-Ray core code).
28 unix/ UNIX-specific source code, including X Window and SVGA support.
29 config/ UNIX-specific configuration and installation scripts.
30 doc/ UNIX-specific and generic HTML documentation, POV-Ray license.
31 icons/ UNIX-specific color icons for the KDE window manager.
32 scripts/ UNIX-specific render scripts (portfolio, stills, animations).
33 include/ Standard POV-Ray include files.
34 ini/ Standard POV-Ray INI files.
35 scenes/ Standard POV-Ray sample scene files.
36
37
38========================
39Compiling and installing
40========================
41
42Basic and detailed instructions to compile and install the generic POV-Ray
43source code on UNIX-based systems are given in the INSTALL file.
44
45In a nutshell: the package installation is based on a configure script
46which detects your environment automatically and adapts the compilation
47and installation process accordingly. Simply run:
48
49% ./configure COMPILED_BY="your name <email@address>" # configure the package
50% make # build the program
51% su # log as root
52$ make install # install program + data
53
54See the INSTALL file for more detailed information.
55
README.bin
1===============================================================================
2POV-Ray 3.7 for PC-Linux, binary version (povlinux.tgz) - README file
3
4For the binary distribution for PC-Linux
5===============================================================================
6
7This is the README file for the compiled version of POV-Ray 3.7 for
8PC-Linux. Platform specific instructions for POV-Ray can be found in
9README.unix and in chapter 1 of the documentation.
10
11This package contains a statically linked version of POV-Ray 3.7
12compiled for the i586 platform. The install script can do both
13system wide installation (requires root privileges) as well as user
14level installation. Installation as root is the recommended method.
15
16======================
17Installation procedure
18======================
19
20 a) Install as root
21
22 From the directory where this file resides, run:
23
24 $ su
25 # ./install
26
27 and follow the instructions.
28
29 b) Install as non-privileged user
30
31 From the directory where this file resides, run:
32
33 $ ./install
34
35 and select 'U' to start a user level install. Afterwards
36 follow the instructions of the install script.
37
38
39Additional command line options that can be used are:
40
41 --no-arch-check : skip the architecture compatibility test
42 kde : only install kde panel icons and file types for current
43 user. In a single user installation this is done
44 automatically after installation.
45 user : only update the user povray.ini/povray.conf file when
46 required.
47 uninstall : uninstall POV-Ray. This will remove all installed
48 files. Any changes made to sample scenes or include
49 files will get lost. This has to be called by the
50 same user who installed POV-Ray. Uninstall of older
51 versions of POV-Ray is not supported (and is not
52 required to install POV-Ray 3.6).
53 test : run a short test render to check if installation was
54 successful. This should be run as a normal user and
55 not as root.
56
57
README.md
1Building POV-Ray 3.7 for GNU/Linux and similar systems
2======================================================
3
4This distribution contains the complete source code of POV-Ray for UNIX
5as well as its accompanying HTML documentation and supporting files. In
6order to build the distribution supplied in the POV-Ray github repo, you
7will need to run a pre-build step. This generates the configure script
8and does a few other things usually performed by our developers prior to
9releasing a source package.
10
11Should you run into problems, please consult `unix/install.txt` for more
12in-depth installation mojo.
13
14NB if you have improvements to the below instructions, please add a comment
15to issue #1, or (if you are working in a branch) send us a pull request.
16
17Dependencies
18============
19
20By default POV-Ray will attempt to build using system-supplied libraries for
21boost, zlib, libpng, libjpeg, libtiff, and openexr. We recommend you have the
22following packages pre-installed:
23
24 libboost-dev
25 libboost-date-time-dev
26 libboost-thread-dev
27 zlib1g-dev
28 libpng12-dev
29 libjpeg8-dev
30 libtiff5-dev
31 libopenexr-dev
32
33Generating configure and building the code
34==========================================
35
36 % cd unix/
37 % ./prebuild.sh
38 % cd ../
39 % ./configure COMPILED_BY="your name <email@address>"
40 % make
41
42Note that the prebuild step will generate a few warnings as it still looks
43for some files no longer included in v3.7. This is harmless.
44
45Installing
46==========
47
48 % make install
49
50This above installs POV-Ray under system-wide directories and needs root privileges.
51Installing as non-privileged user is also possible. By default (i.e. as root), 'make
52install' installs the following components:
53
54 povray binary (executable) in /usr/local/bin
55 data files (e.g. includes, scene files) in /usr/local/share/povray-3.7
56 documentation (text and html) in /usr/local/share/doc/povray-3.7
57 configuration files (e.g. povray.conf) in /usr/local/etc/povray/3.7
58
59The configuration files are also copied under the $HOME/.povray/3.7 directory
60of the user (or root) who is doing the installation.
61
62Please see [unix/install.txt](install.txt) for more details about available
63configuration options etc.
64
README.unix
1 Persistence of Vision Ray Tracer
2 Version 3.6
3 UNIX Specific Documentation
4
5
6 This file contains generic information for running POV-Ray on UNIX
7 systems. It briefly describes the UNIX-specific features of POV-Ray
8 from configuration and command-line perspectives. As such, it is not
9 a replacement for the HTML user documentation located in the doc/html
10 directory (chapter 1 in particular). This document also does not cover
11 the program installation which is described in either the INSTALL file
12 (for the generic UNIX source distribution) or in the README file (for
13 the PC-Linux binary distribution).
14
15
16Executables
17
18 Official executables of POV-Ray for UNIX are only provided for the
19 x86 (and compatible) platform running the GNU/Linux operating system.
20 Due to the very large variety of UNIX platforms, the POV-Team cannot
21 provide official binaries for all of them. However, since POV-Ray
22 is also available as a source package, recompiling the source for
23 your target system shouldn't cause a problem. Note that if you want
24 to distribute an executable created by yourself, you must comply with
25 the POV-Ray License Agreement (povlegal.doc).
26
27 The official GNU/Linux (a free UNIX variant) version is available as
28 povlinux-3.6.tgz (or povlinux-3.6.tar.gz). The generic UNIX source
29 distribution is available as povray-3.6.tgz (or povray-3.6.tar.gz).
30 Both binary and source packages can be found at the following sites:
31
32 - The POV-Ray website, www.povray.org in the Download section.
33 - The POV-Ray FTP site, ftp.povray.org in /pub/povray/Official/Linux.
34 - There are many sites around the world that mirror the povray.org
35 website. These are listed in /pub/povray/README.MIRRORS at
36 ftp.povray.org . You should try to use the closest site for
37 faster downloads.
38
39 povlinux-3.6.tgz contains a very generic povray executable that should
40 run on most GNU/Linux distributions with a 2.2 kernel or above. It is
41 a fully static binary that should not depend on any installed library.
42 The povray executable includes support for X Window and SVGA display
43 (see below). It comes with an install script that installs POV-Ray
44 into the /usr/local prefix or any directory you have write access to.
45 Vendor-specific package formats such as RedHat RPM or Debian DEB are
46 not available at the moment.
47
48
49File locations
50
51 The default location for installing POV-Ray for UNIX is under
52 /usr/local/share/povray-3.6 for all INI, scene, and include files,
53 and /usr/local/bin for the povray binary itself. The POV-Ray man page
54 is by default installed into /usr/local/man/man1 . The system-level
55 povray.ini and povray.conf files, which store default settings for
56 POV-Ray, are installed in the /usr/local/etc/povray/3.6 directory.
57 The default installation location can be changed from /usr/local
58 to another directory when installing the PC-Linux binary or when
59 configuring the source package of POV-Ray. See the relevant install
60 documentation for further details. When installing POV-Ray (binary
61 and source distributions) the povray.ini and povray.conf files are
62 also placed under the $HOME/.povray/3.6 directory. Refer to the
63 user documentation for INI and I/O restriction settings.
64
65
66INI files
67
68 POV-Ray allows the use of INI files to store common configuration
69 settings, such as the output format, image size, and library paths.
70 Upon startup, the UNIX version of POV-Ray will use the environment
71 variable POVINI to determine custom configuration information if
72 that environment variable is set. Otherwise, it will look for the
73 file "povray.ini" in the current directory. If neither of these works,
74 then POV-Ray will try to read the user "povray.ini" file (located under
75 $HOME/.povray/3.6) or, otherwise, the system-level "povray.ini" (by
76 default in /usr/local/etc/povray/3.6). If none of these work, for
77 backward compatibility with version 3.5 and earlier, POV-Ray finally
78 searches for INI files as "$HOME/.povrayrc" or otherwise a "povray.ini"
79 file in PREFIX/etc (where PREFIX is /usr/local by default).
80
81 The other INI files found under the ini/ directory, such as zipfli.ini
82 and tgaflc.ini are of limited use under UNIX but are included as examples
83 of how to automate operations from within POV-Ray. They can be customized
84 to use whatever programs you have installed.
85
86
87CONF files
88
89 POV-Ray 3.5 has introduced the I/O Restriction feature as an attempt
90 to at least partially protect a machine running the program to perform
91 forbidden file operation and/or run external programs. I/O Restriction
92 settings are specified in a "povray.conf" configuration file. There are
93 two configuration levels within POV-Ray for UNIX: a system and a user-
94 level configuration. The system-level povray.conf file (by default in
95 /usr/local/etc/povray/3.6) is intended for system administrators to
96 setup minimal restrictions for the system on which POV-Ray will run.
97 The user $HOME/.povray/3.6/povray.conf file allows further restrictions
98 to be set. For obvious security reasons, the user's settings can only
99 be more (or equally) restrictive than the system-level settings. See
100 chapter 1 of the documentation for details. In POV-Ray 3.6 the format
101 of the configuration file has changed and is not backward compatible
102 with POV-Ray 3.5. Note that I/O Restrictions are still subject to the
103 operating system permissions. Also the feature is not mature enough,
104 especially since it has been completely reworked in the UNIX version
105 of POV-Ray 3.6.
106
107
108Display Formats
109
110 There are two different methods of displaying images as they are
111 rendered with POV-Ray on most UNIX systems, and an additional display
112 method on GNU/Linux systems. The first way is the text format,
113 which can output a crude 75x24 ASCII version of the image, to give
114 an idea of what POV-Ray is doing. This doesn't work very well if you
115 are also using the Verbose (+v) status output. It also isn't very
116 satisfying for the output of a ray tracer, but may be useful in some
117 cases. The second way requires the X Window System to be installed
118 on your machine, which should be the case on most UNIX systems. The
119 X Window System allows full-color display of any image size, and at
120 any screen resolution and color depth. Some limited user interactions
121 with the display are also allowed. The third way is specific to
122 GNU/Linux systems and allows to display the rendered image directly
123 on the console screen using the SVGA library. Both X Window and SVGA
124 displays are discussed in more detail below.
125
126
127X Window Display
128
129 Using the X Window display allows you to preview the image using any
130 kind of visual, at any depth, and even remotely if desired. During
131 rendering, the window will be updated after every scanline has been
132 rendered, or sooner if the rendering is taking a long time. To
133 update it sooner you can click any mouse button in the window or
134 press (almost) any key. Pressing <CTRL-R> or <CTRL-L> during
135 rendering will refresh the whole screen. If you have the Exit_Enable
136 or +X flag set, pressing 'q' or 'Q' at any time during the rendering
137 will stop POV-Ray rendering and exit. The rendering will pause when
138 complete if the Pause_When_Done (or +P) flag is set. To exit at
139 this point, press the 'q' or 'Q' key or click any mouse button in
140 the window.
141
142 Depending on your window manager (e.g. KDE, Gnome, fvwm), POV-Ray may
143 use a color icon for the window (in the title bar) and its corresponding
144 button in the task bar. The use of a color icon also depends on whether
145 the POV-Ray executable has been linked with the Xpm library. The latter
146 is usually shipped with the X Window System. In case the Xpm library
147 cannot be used, a built-in monochrome icon is used instead. Some
148 window managers also need to be configured in order to use the color
149 icon. The "xpovicon.xpm" file can be used in this case, but the exact
150 procedure depends on the window manager. The following shows how to
151 make the fvwm window manager use this icon. First, copy the icon file
152 to one of the directories listed by PixmapPath (or ImagePath) in your
153 $HOME/.fvwmrc configuration file. Second, edit the latter to add the
154 following line:
155
156 Style "Povray" Icon xpovicon.xpm
157
158 Third, restart the X server (e.g. by typing 'startx' on the console).
159 Restarting fvwm alone will not be enough.
160
161 In POV-Ray 3.6 the X Window display comes with a gray/white checkered
162 background by default, instead of the black color implemented in the
163 earlier versions. The new default background is particularly useful
164 when rendering images using the alpha channel (+UA option). In case
165 you don't feel comfortable with this default background, you can make
166 POV-Ray for UNIX use a custom background image instead. The user-
167 supplied background image must be placed under the $HOME/.povray/3.6
168 directory as "background.ext" (where "ext" is either "jpg", "jpeg",
169 "png", "ppm", "tga" or "gif"); for instance "background.png". The
170 filename must be all lowercase. POV-Ray will detect the image format
171 depending on the filename extension (so this is different from the
172 other image-related features in the POV-Ray scene description language).
173 In case you place several background.* files under $HOME/.povray/3.6
174 the first file matching the list of extensions given above will be used.
175 For instance, POV-Ray will use "background.jpg" if both "background.jpg"
176 and "background.tga" are present. Note there is not support for the
177 TIFF format at the moment, since TIFF support is still an experimental
178 feature in POV-Ray 3.6. Also the background image is NOT output to
179 the rendered image file, so you cannot use it as e.g. an image map.
180 IMPORTANT NOTE: the user-supplied background image is an EXPERIMENTAL
181 feature and is specific to the X Window display of POV-Ray for UNIX.
182 No provision is made that this new feature will be available in future
183 releases of POV-Ray.
184
185 When POV-Ray is compiled with support for the X Window display, the
186 program also understands the standard X Window command-line options
187 in addition to those given in the generic POV-Ray documentation. See
188 the X(1) man page for further explanation of these options.
189
190 -display <display name> Preview on the specified display
191 -geometry <WIDTHxHEIGHT+XXX+YYY> Start with the given size/position
192 -visual <visual type> Use specified visual if available
193 -title <title> Use the given title for the window
194 -icon Start iconified
195 -owncmap Force POV-Ray to use a private colormap
196 -borderwidth <width> Use a border of the given width
197 -help Output these X Window specific options
198
199
200SVGAlib display
201
202 For GNU/Linux systems that don't have the X Window System installed,
203 it is possible to use the SVGA library (SVGAlib) to display directly
204 to the screen. The POV-Ray binary using SVGAlib must be installed as
205 a setuid root executable to be able to run properly. If it doesn't
206 work (usually complaining about being unable to get I/O permissions)
207 first try (as root):
208
209 chown root.root povray
210 chmod 4755 povray
211
212 IMPORTANT NOTE: doing this may have serious security implications.
213 Running POV-Ray as root or through 'sudo' might be a better idea.
214
215 If it still doesn't work then make sure SVGAlib is installed on your
216 machine and works properly ('sdoom' is a good way of doing this :-).
217 Anything that can at least use the 320x200x256 mode (ie regular VGA)
218 should be fine, although modes up to 1280x1024x16M are possible. If
219 you do not have root priviledges or can't have your system admin
220 install POV-Ray for you, then you should rather use the X Window or
221 text-only display, which do not require any special system priviledges
222 to run. If you are using a display resolution that is lower than what
223 you are rendering, the display will be scaled to fit as much of the
224 viewing window as possible.
225
226
227Interrupting POV-Ray
228
229 To interrupt a rendering in progress, you can use CTRL-C (SIGINT),
230 which will allow POV-Ray to finish writing out any rendered data
231 before it quits. When using a rendering display, you can also press
232 the 'q' or 'Q' keys in the rendering preview window to interrupt the
233 trace if the Test_Abort (or +X) flag is set.
234
235
236Post-processing Images
237
238 For UNIX systems, the PBM utilities (PBMPLUS, NetPBM) and ImageMagick
239 are an excellent choice for post-processing tools, especially if you
240 only have a command-line interface to UNIX:
241 http://www.acme.com/software/pbmplus
242 http://netpbm.sourceforge.net
243 http://www.imagemagick.org
244
245 POV-Ray can also pipe its output directly into a post-processor.
246 For example:
247
248 povray +iscene.pov -fp +o- | cjpeg > scene.jpg
249
250 will create a JPEG output file, since specifing the '-' output filename
251 (+o option) tells POV-Ray to send the output image data to stdout, which
252 is piped through cjpeg in this example.
253
254
255Questions and problems with POV-Ray for UNIX should be posted on the
256news.povray.org news server under the povray.unix newsgroup. This news
257server also has a web interface at http://news.povray.org/groups/ .
258Please make sure you have consulted with a local UNIX person first if
259you think the problem is likely to be on your end. If you are installing
260POV-Ray in a publicly accessible location, you must read and comply with
261the 'Online or Remote Execution' conditions in povlegal.doc .
262
263Mark Gordon
264Internet: mtgordon@povray.org
265
266Revised for POV-Ray 3.6 by Nicolas Calimet <pov4grasp@free.fr>
267
