Documentation:Windows Section 1

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.

Introduction

This section provides information on how to use the Microsoft Windows™ version of the Persistence of Vision Raytracer™ (also known as POVWIN).

Before we start, we'll have a brief discussion of just what this program is, and what it does.

What is POV-Ray for Windows?

POV-Ray™ is short for the Persistence of Vision Raytracer™, a tool for producing high-quality computer graphics. POV-Ray is Free Software (as per the definition of the Free Software Foundation) as its source code is licensed under the Affero General Public License (AGPL).

POV-Ray for Windows (also known as POVWIN) is POV-Ray, ported to the Microsoft Windows™ operating system. It contains all the features of POV-Ray itself, plus some others specific to Windows. The additional features do not affect the core rendering code; they all relate to making the program easier to use under Windows.

An extensive discussion of the POV-Ray Scene Description Language can be found elsewhere in this help file. For a quick demonstration of POV-Ray for Windows, start up the program by selecting 'Run Demo' from the Render menu.

... And What Is It Not?

POV-Ray for Windows is not a modeler. It will not let you design scenes graphically on-screen. The POV-Ray project does have a freeware 3D modeler for Windows called 'Moray'. Moray is currently under re-development to make it compatible with modern versions of Windows. There are also several other shareware and freeware programs available for this purpose.

With POV-Ray itself, to write or modify POV-Ray scenes you just edit the actual text file containing the commands. New users might be surprised to learn that, although this sounds primitive, it is in fact one of the things that gives POV-Ray so much power and flexibility. There are many other rendering programs that give you a point-and-click interface, but when it comes down to absolute control of your scene, it's hard to beat a text-based scene description language (even though it's harder for some to learn).

Who Can Use POV-Ray for Windows?

Almost anyone can use POV-Ray for Windows. If you have never seen a ray tracing program before, you can have great fun just rendering the sample scenes and animations installed together with POV-Ray for Windows. Once you have studied some scene files and spent a little bit of time reading this documentation, you can start putting basic scene files together.

Remember, though, that you do need to invest some time getting to know the program. For instance, you do not have to worry about most of the POV-Ray settings at first, but some of them are important. Ignore them and POV-Ray may not do what you expect. The default settings have been selected so as to be satisfactory in the large majority of cases, but sometimes they will not give you what you want. Don't give up. The solution is bound to be a simple one, as long as you take the time to read the documentation. Investing a little bit of time getting to know the program will pay off - guaranteed!

As for experienced POV-Ray users, you will find POV-Ray for Windows makes life much easier. Working under Windows means you can edit one scene while rendering another and modifying the INI file of a third. This feature, combined with the File Queue option lets you speed up the scene generation cycle considerably while leaving you the option of doing some 'serious' work at the same time.

System Requirements

POV-Ray for Windows requires Windows XP or later, and has been tested on versions up to and including Windows 7 (32 and 64-bit). We recommend having at least 100mb or so of free disk space (for temporary file storage during renders) and at least 1GB of available memory (though less is OK if you are not doing complicated scenes).

System Specific Features

What's new in POV-Ray for Windows

New as of version 3.7 the following section covers changes and features that apply to POV-Ray for Windows. See the section Changes and New Features Summary for information about non-platform specific changes.

1. An experimental Real-Time Raytracing feature was added.
2. Added 'alternate render file' feature to povwin IDE. Look here for more details.
3. New Render Window behavior.
4. The Render Priority menu supports a new option.
5. Added extensions .MCR and .MAC to the list of files povwin considers include files (i.e. which are filtered as such in the various file dialogs and assigned the POV file type for the editor syntax highlighting).
6. Added .INI file type to povwin editor syntax highlighting.
7. Added window menu to povwin IDE. Entries are MRU-sorted.
8. Added these POVWIN features:
• file modified indicator to filename shown in POVWIN main window caption.
• notification for when auto-reload results in files being auto-saved.
9. Added ability to close edit tab in windows version by middle-clicking on it. (NB this means on the tab itself, not the contents of the tab). Also, Ctrl-W now defaults to closing the current editor file.
10. Added /EDITDLLPATH command-line parameter, which overrides the default edit DLL locations for the windows version.
11. Added a crash upload utility.
12. Added ability to specify thread count from Windows version render menu (unsaved setting).
13. Windows console version now sends stream output to stderr by default.
14. Added Control-A support in windows version commandline input box (select all).
15. Changed windows version render window keypress code to hand focus to main window for any key, not just escape.
16. Expanded number of available insert menu ID's to about 9000.
17. Added support for loading of PNG and JPG files as insert menu hints. (search order PNG, JPG then BMP)
18. Windows editor tab/indent settings are no longer per-file+global default; changing one affects all files.
19. Added display of filename when hovering over an editor tab.
20. Added a right-click menu to editor tabs allowing the following:
• opening of folder in explorer.
• copy of filename to clipboard.
• save the file.
• close it, close all but it.
• move the tab left and move the tab right.
21. Additionally the previous new entries have also been added to the window menu.
22. Added a new file ~ini\user-keywords.txt that allows users to add their own keywords for syntax highlighting and auto-completion in the editor.
23. Added new option to prevent the system from sleeping whilst a render is in progress (by default this is selected).
24. Added the /BENCHMARK command-line parameter to automatically run the standard benchmark, write the result to a file, and exit.

SYS File Type

The SYS file type has been deprecated, and the cross-platform output file type is now PNG, or type n. See the section Output File Type for more information.

System Specific Charset

The section titled Charset refers to a system specific charset. There is no system specific charset support specially implemented within POV-Ray for Windows.

Spelling

Some US Residents have commented on the spelling of some words such as colour, initialisation, and minimised (they expect color, initialization, or minimized). POV-Ray is an international effort and as such our spelling sometimes conforms to British, European, or Australian, rather than American, English. You'll find examples of this both in this document and in POV-Ray itself (for example, POV accepts both 'color' and 'colour' as valid keywords).

Reporting Bugs

There is a section in this help file for bug reports. Make sure that you read it before sending us a complaint/bug report !

Trademarks

The terms 'POV-Ray', 'Persistence of Vision Ray Tracer', 'POV-Team' and 'POVWIN' are trademarks of Persistence of Vision Raytracer Pty. Ltd. All other trademarks are acknowledged as being the property of their respective owners.

Real-Time Raytracing

The version 3.7 release of POV-Ray contains a provisional implementation of a real-time raytracing feature. In addition to this, there are two related features that also are provided for testing purposes: clockless animation and video capture.

The real-time raytracing feature is activated via the Real_Time_Raytracing INI option or the +rtr command-line option. Internally, this causes POV to turn off file output and render the selected scene multiple times. Once all threads in the render have completed a single frame, the frame is sent to the frontend for display as a single message, and the threads then start rendering the same frame again, optionally changing the camera first, if clockless animation is enabled.

It is important to note that while the display preview window is only updated once per frame, the backend still uses render blocks as has been the case since the first beta of 3.7. This is important to remember since the size of the render block can affect the frame rate in a real-time render. Setting it too small can reduce performance. However setting it too large can cause idle CPU's (assuming you have an SMP system), since all threads have to wait until the last block is completed before starting on a new frame. This could impact performance if the last block(s) to be rendered (lower-right) are quite slow, and a large block size is being used.

When used with clockless animation and video capture, the RTR feature can lend itself to some interesting renders, provided a sufficiently powerful computer is used (two cores is recommended; four cores is of course better). However if you are willing to confine yourself to simple scenes and/or use low resolution (e.g. 160x120), it is still possible to use it on single CPU computers.

Note: Currently, it is not possible to save the rendered RTR output to disk. We will provide this as an option if we keep RTR in POV-Ray. Also, the current implementation does not provide any means of synchronising the camera selection with time; that is, if the frame rate changes (as it will tend to do if camera motion reveals or hides items that can slow down the render), the relative rate of camera motion will also change. If RTR turns out to be popular enough, we might investigate the possibility of the camera selection being keyed by elapsed time rather than frame count. This would allow a more consistent rate of motion at the expense of possibly having 'jerky' output if the render slows down.

Clockless Animation

Clockless Animation is a very specific form of POV-Ray's animation feature set which allows a series of images to be rendered without re-parsing the scene file. Traditionally the clock variable is used to control animation scene content. For this to work as expected, it is necessary to re-parse the scene file. As the aim of clockless animation is to avoid such re-parsing, the clock is not able to be used in its normal manner; it is from this fact that the feature name derives. Note also that, in addition to not re-parsing the scene file, neither is the scene re-bounded. This implies that no finite objects may move between frames of the render. Clockless Animation enforces this by not providing any means to do so.

As things stand, a clockless animation CA scene has exactly one thing that may change from frame to frame: the camera. Each frame of a CA has an associated camera, which is declared in the SDL in the normal manner. In fact, SDL has not been changed at all to permit this feature to work. Provided that CA has been activated by using either the Clockless_Animation INI entry, or the +kla command-line option, POV's parser switches from complaining when an additional camera definition is encountered to instead storing a list of all cameras declared.

Put simply, each camera definition in the SDL represents exactly one frame of the animation, in the order that they are parsed. The number of frames thus is the number of cameras, and the normal first and last frame INI parameters are ignored. (The subset start and end still work as expected, though they do not apply during real-time raytracing).

Currently, the use of clockless animation is limited to the real-time-raytracing feature. However it is intended to expand its scope to normal rendering as well.

Video Capture

Note: Video Capture under Windows is currently disabled due to stability issues. Since this is a windows only feature, this means that no current official POV-Ray release has video capture. However the infrastructure is still in place and the below documentation will remain as it will eventually be re-enabled.

Video capture is an experimental feature that will certainly change prior to it being considered stable (if indeed it is kept at all). Currently it is only implemented on the Windows platform. Video Capture (vidcap) allows a video source (e.g. webcam) to be fed into a rendering just as if it were a still image. Currently, this is done by overloading the 'sys' filetype in image maps (this will change in the future once a dedicated keyword is added for it).

Here is a simplistic example of an image map that will obtain an image from a video capture device:

pigment { image_map {sys ":vidcap:" map_type 0} }

and a more complex one:

pigment {
  image_map {
    sys ":vidcap:width=640:height=480:double-buffer=0:skip-initial=0:gamma=1.0" map_type 0
    }
  }

The requirements are that the image type is sys and that the image filename starts with the text :vidcap:. The text following the :vidcap: (if any) is considered to be additional options which are then provided to the platform-specific video capture support code.

Options

At this point of time the following options are supported:

width=nnn
height=nnn
double-buffer=yes|true|1|no|false|0
skip-initial=nnn
gamma=fff

If omitted, defaults are:

width and height - the default for the video capture device.
double-buffer    - turned on
skip-initial     - 0 frames (i.e. turned off)
gamma            - 1.0

It is possible to specify just the width or height, in which case the code will default to using the first supported resolution with that size in that dimension (it won't care what the other dimension is). Specifying -1 as a width or height is also a way of saying it is a don't-care. If the requested size is not available, the render will fail.

skip-initial is the number of frames to skip before returning from the video device initialization. This is needed on some webcams that need a number of frames to perform their setup (such as auto exposure and auto white-balance). This matters mostly if the vidcap input is being used for something other than real-time rendering.

double-buffer is a means of telling the video capture system to store the incoming video data in a separate buffer, which is then copied to the main buffer at the end of each rendered frame. Typically this is what you would want. However it has a time penalty on SMP systems due to the use of a mutex and thus is by default turned off. This means that it is possible to see 'tearing' and similar artifacts in RTR.

gamma allows an input device to have a specific gamma correction applied to the delivered pixels prior to their being applied to the image map. Generally this is best left at 1.0.

Video Source

The video source for this windows only feature is chosen via a new sub-menu.

Introduction

Getting Started

This document is protected, so submissions, corrections and discussions should be held on this documents talk page.