Difference between revisions of "Documentation:Windows Section 2"

Revision as of 11:42, 12 June 2011

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

Getting Started

This section will help new users get started with POV-Ray for Windows.

The Demo

If you have never seen POV-Ray at work before, start by running the demo (select Render/Run Demo), then click on Start Rendering. You will see POV-Ray for Windows start up a Render Window and generate a sample scene block by block. By default, these blocks are 32x32 pixels in size. Notice that if you close the Render Window, the rendering job is not interrupted. If you have POV-Ray set up to save the image as a file (this is the default setting), that file will be produced whether or not you display the image on screen as you render. To stop rendering, select Render/Stop Rendering (or use the keyboard short-cut ALT-G).

Even if you minimize the rendering window, POV-Ray for Windows will display the progress of the rendering job by showing the percentage completed. If you close the render window and want it back, click the right mouse button over the main POV-Ray window, and select the appropriate menu item, or just click the toolbar button labelled 'Show'.

Starting a Render Job

Starting POV-Ray rendering any scene file is as simple as selecting the file through the menu (Render/Select File and Render) or dragging and dropping it from Windows Explorer. This will work with either a POV file or an INI file (as long as it has an associated POV file). See Understanding File Types. The scene is rendered with the current POV-Ray 3 options (see Command-Line Options). Note that you can tell POV-Ray for Windows to open a file in the editor instead of rendering it if you drag and drop it into the program (this is in fact the default setting now). See the Options Menu for more information.

N.B. One of the most common errors new users make is turning off the display option. The Display option (+d) is ON by default. If you turn this OFF in the INI file or on the command line, POV-Ray will not display the file as you render, no matter how many times you press the Show Render Window button. However this does not mean the rendered file is not written to disk.

Please also note that POV-Ray for Windows will write the output file to a .PNG by default. There is no way to 'save the render window' after rendering is completed. If you turned file output off before starting the render, and change your mind, you will have to start the rendering all over again. We recommend that you just leave file output on all the time.

Dragging and Dropping Files

Dragging and dropping (a.k.a. Drag'N'Drop) from Windows Explorer (a.k.a. 'My Computer') has the advantage that you can select more than one file at a time. You can drag and drop up to 512 POV and/or INI files. POV-Ray for Windows will start processing the first file in the queue and add the rest to the queue. See File Queue in the Render Menu for more details.

Note: If the dropped files destination is set to Editor (the default), the files will be opened in the internal editor instead. In that case, there is a limit of 32 files that may be opened at any one time.

Tutorials

There is a comprehensive beginner's tutorial included in this help file. It relates to the use of POV-Ray in general (i.e. on all platforms, not only Windows), so we recommend that you read the rest of section 1 first before attempting to go any further, as section 1 tells you how to use the interface of POV-Ray for Windows itself. The more ambitious may like to check out the advanced tutorial section.

Understanding File Types

This section points out the various types of text files that POV-Ray for Windows works with.

POV Files

POV-Ray for Windows works with two types of plain text files. The first is the standard POV-Ray scene description file (also known as 'SDL', for Scene Description Language). Although you may give files of this type any legitimate extension, it is more convenient for you if you name them using the .POV extension. In this Help file, scene description files are referred to as POV files.

The second type, the initialization file, normally have .INI extensions and are referred to in this help file as INI files.

INI Files

An INI file is a text file containing settings that instruct POV-Ray how to render a scene. These settings are different from what is in the POV file, which contains instructions to POV-Ray about what is in a scene.

You can store a default set of options in the file called POVRAY.INI in the INI directory under the POV-Ray for Windows home directory. You can pass any other INI file to POV-Ray for Windows by selecting it (through Render/Select File and Render) or by dragging it from the Windows File Manager and dropping it onto the POV-Ray window.

One of the options you can set in the INI file is the name of an input file. You can specify the name of a POV file here. If you now activate the INI file, the POV file referred to will be processed with the settings specified in the INI file. This way you can customize POV-Ray settings for any individual scene file.

For instance, if you have a file called SCENE.POV, you can create a file SCENE.INI to contain settings specific for SCENE.POV. If you include the option 'Input_File_Name=scene.pov' in SCENE.INI, and then ask POV-Ray to render SCENE.INI, POV-Ray will process SCENE.POV with the options specified in SCENE.INI.

Remember, though, that any options set at the POV-Ray for Windows command line when you activate an INI file override any corresponding options in the INI file (see Command-line Options and Render Menu). Also, any options you do not set in the INI file will be taken as last set by any other INI file or as originally determined in POVRAY.INI.

You can instruct POV-Ray to generate an INI file containing all the options active at the time of rendering. This way, you can pass a POV file and its associated INI file on to another person and be confident that they will be able to generate the scene exactly the same way you did. See the section titled Using INI Files for more information about INI files.

INI File Sections

Sections are not files in themselves; they are portions of INI files. Sections are a means of grouping multiple sets of POV-Ray options together in a single INI file, by introducing them with a section label. Consider the following INI file, taken from the POV-Ray 3 documentation:

; RES.INI
; This sample INI file is used to set resolution.

+W120 +H100 ; This section has no label.
; Select it with "RES"

[Low]
+W80 +H60 ; This section has a label.
; Select it with "RES[Low]"

[Med]
+W320 +H200 ; This section has a label.
; Select it with "RES[Med]"

[High]
+W640 +H480 ; Labels are not case sensitive.
; "RES[high]" works

[Really High]
+W800 +H600 ; Labels may contain blanks

If you select this INI file, the default resolution setting will be 120 x 100. As soon as you select the [High] section, however, the resolution becomes 640 x 480. See Edit Settings/Render in the Render Menu for instructions on selecting sections. The 'quick resolution' combo box in POVWIN is an example of this type of file. For more information on POV-Ray options and INI files consult the section on POV-Ray Options.

Quick resolution combo box

Using the Internal Editor

The POV-Ray internal editor is an advanced programmer's editor, offering syntax highlighting for POV files (as well as C, Java, and a number of other languages), several indent styles, block indent/undent, column selections, OLE drag and drop, amongst other things. Most of the key mappings are configurable, as are the colors and a number of other options.

It consists of two parts - a custom control, and the 'wrapper' code that encapsulates it. It's important that you remember this, as it will explain some of the behavior that it exhibits (for example, not being able to reassign all keystrokes, just most of them). It is not essential for POVWIN's operation to have the editor present - it is quite possible for it to run without it. However, under normal circumstances, the editor is present.

Starting with version 3.7 there been two notable changes to the POVWIN IDE.

Firstly, it now has a Window menu, which is located where the GUIEXT menu used to be (the latter has moved to within the Options menu). While technically a Window menu is not necessary, as all open files are visible in tabs, the addition of this menu provides two advantages:

We can provide the option of showing all tabs on a single line, with a scroller to view non-visible ones. This has not yet been added but will be at a later point.
The MRU (most-recently-used) arrangement of the window menu makes it trivial to toggle between files without taking your eyes off the text or using the mouse. The most recently view window (i.e. the current one) will always be entry 1 in the list. The second most recently viewed (i.e. the last window viewed before switching to the current one) will always be entry 2 in the list, and so forth. Given that entries 1 through 10 in the list are given the menu mnemonics 1 through 0 respectively, it is therefore clear that to toggle between the current and previous files all you need to do is hit Alt-W then 2. To go to the third oldest, Alt-W then 3, and so forth. Currently, the MRU list is not saved on exit.

Secondly, there is now an 'alternate render file' feature. This is intended to make things easier when editing macro or include files. While it is possible to use SDL to detect whether a macro/include file is being rendered directly and to pull in supporting code, that approach is not very flexible. The alternate render file feature allows a render to be started on an include file, and instead of the include file being rendered directly (as would have happened previously), the source file that most recently included that file in a render will be rendered instead. For this feature to work, you need to have rendered a file which includes the target file during the current editing session (the association between include files and source files is not persisted when POVWIN exits). Additionally you need to have requested to render a source file which does not have the .POV or .INI extension. When you request the render, a message box will appear asking you what to do. You can choose to render the alternate file this time only, to render the alternate file each time you render this one, or to render this one each time (i.e. disable the alternate file option). In all cases, the choice you give only persists for the current editing session; it is not restored when you re-launch POVWIN. this is by design.

Note: The terms 'source file' mean either a .POV, .INI, .MAC or .MCR file.

The Editor Feature Set

Here are just a few of the features offered by the editor, as implemented in POV-Ray for Windows:

Color Syntax Highlighting.: Language-specific keywords, comments, and strings are colored differently to set them apart from plain text.
Keyword Completion.: Language-specific keywords can be automatically expanded or cycled through by pressing the TAB key while the caret is at the end of a partial keyword.
CodeList.: A pop-up list of keywords will appear if you press Ctrl + Space anywhere in the editor window. If the edit caret is over a partial keyword, the list will be scrolled appropriately.
User Choice Regarding End-Of-Line Behaviour.: Some users prefer the ability to place the edit caret beyond the end of line, while other users dislike this behaviour. You can choose either.
Customizable Keyboard Mappings.: Keystrokes can be added and removed to emulate popular keyboard mappings. Over 120 individual commands are able to be assigned to the keyboard.
Keystroke Macros.: Users can record a series of keystrokes and assign a keystroke to play back the keystrokes repeatedly. Up to 10 macros may be recorded. These are preserved across editing sessions.
Drag and Drop Text Manipulation.: Highlighted text can be dragged and dropped between any window supporting OLE text Drag and Drop. Text may be copied or moved.
Column Selection and Manipulation.: Columns of text can be selected with the mouse and then manipulated. Empty columns (columns with a width of zero characters) can be selected, causing subsequent typing and deletion to occur over multiple lines at the same time.
Multiple Split Views.: Users can create up to four separate views of the same edit buffer. Each view can be scrolled independently.
Unlimited Undo/Redo.: All edit actions are fully undoable and redoable. A limit can be set on the number of edit actions that may be undone.
Auto Indentation.: Once a language is chosen, as the user enters code, CodeMax will automatically indent lines to following the scoping rules of the language.
Optional Auto-Save.: If turned on, changed files are saved periodically.
Optional Auto-Reload of Changed Files.: The editor will optionally automatically reload an editor file that was changed by an external program while POVWIN didn't have the focus. It can also prompt you as to whether or not you want it reloaded (which is the default behaviour).
Brace Matching: Pressing the Ctrl + ] key while the edit caret is on a '[', '(' or '{' will cause the caret to jump to the matching ']', ')' or '}', and vice-versa.
Block Indent/Undent: Pressing the TAB or Shift + Tab keys will indent or unindent a selected block of text.
Tabify/Untabify: You can convert text that was formatted with hard TAB characters into space-expanded form, and vice-versa.
Customizable Colors.: All editor colors (including the background) are customizable. POVWIN also provides two 'quick set' defaults - white text on a black background and black text on a white background.
Smart Case Preservation in Replace Operations.: During search and replace, you can optionally have the replaced text retain its original case.
Enhanced MRU (Most Recently Used files) List: POVWIN's MRU list not only recalls the filenames of recently opened files, it also remembers the the line, column, and language settings.
Keyword Expansion and CodeList: This feature allows fast insertion of standard POV-Ray keywords either by typing a partial match and hitting TAB, or by using Ctrl + Space to bring up a complete list.

Turning the Internal Editor On or Off

Select the Options|Other Settings|Use Editor menu item. If this is off, POV-Ray for Windows will not attempt to load the editor DLL at startup, and the editors will not be available.

Preventing File Restore

By default, POV-Ray for Windows will attempt to re-load the files you had open in the editor when you last exited the program. If this causes a problem (e.g. maybe one of the files is very large and you don't want it re-loaded), you can add the '/NR' (or '/NORESTORE') option to the POV-Ray for Windows command line. In this case POVWIN will flush the list of files you had opened.

Switching between Editor windows

You can use the Alt+LeftArrow and Alt+RightArrow keys to cycle amongst the editor windows and the message window. Some users are more comfortable with Ctrl-Tab, so this is available as well.

Keyword Expansion and CodeList

This facility is designed to speed up the authoring of POV-Ray scene files by allowing you to quickly insert any of the standard keywords by typing part of the word and pressing TAB (provided you have the 'Overlay Keyword Expansion On Tab Key' option in the Editor Menu turned on).

If this option is enabled, the tab key serves two functions: it firstly will function to invoke keyword expansion, and secondly, if it appears that keyword expansion is not desired at the current edit position, it functions as a normal tab key (inserting tabs or spaces as defined by your configuration of the editor).

A Quick Example

Before getting into the explanation below, we suggest you try it for yourself. Firstly, make sure that 'Overlay Keyword Expansion On Tab Key' is turned on (this is the default so unless you have turned it off it will already be on).

Now, open an editor if you don't already have one open, and position the edit cursor ('caret') on a blank line and type the letters 'am', then press TAB. The word 'ambient' should now appear where you had 'am'. Now press it again and you will see the word 'ambient' become 'ambient_light'. Now press SHIFT+TAB (shift and tab together) and you will see that it goes back to 'ambient', and, if pressed again, back to plain 'am'.

How Keyword Expansion Works

When you press TAB, the editor firstly looks at the characters to the left and right of the current edit caret position. If there is blank space to the left of the caret, or there is no blank space to the right of the caret then keyword expansion does not occur and the TAB key will function normally. Note that for the purposes of this test, the start of the line is not considered blank space, but the end of the line is.

To pass the above test, therefore, the caret must be at the end of a word containing at least one character, followed by a space, tab, or the end of the line. The editor will then get this word from the line and compare it (with case-sensitivity) against the list of known POV-Ray scene file keywords that it holds internally.

If the above comparison yields a perfect match (that is, the word on the left of the caret is exactly the same as a keyword), then keyword expansion does not occur and the tab key functions normally.

If the above test fails (that is, the word is not a perfect match), then a test is made for a partial match. If the word on the left of the caret does not even partially match any word in the keyword list, then expansion does not occur and the tab key functions normally.

If the above test passes, the word on the left of the caret must be a partial keyword (for example, 'pigm' is considered a partial keyword since the editor knows that 'pigment' is a keyword). Given this fact, the editor extracts the list of all keywords that match the partial keyword (in the above example, 'pigment', 'pigment_map', and 'pigment_pattern' all contain the prefix 'pigm' and as such would be included in the list).

The editor stores this list in memory and then completes the partial keyword with the first one (alphabetically) from the list it stored (in the above example, this would be 'pigment'). Once this has occurred, the editor is in 'keyword expansion' mode. The editor remains in this mode until you move the edit position or otherwise make any change to the text other than via TAB and SHIFT-TAB expansion.

Pressing TAB again will cause the next keyword in the stored list of possible matches to appear, replacing the first one, and so forth. If you reach the end of the list, pressing TAB will cause the caption bar of POV-Ray for Windows to flash. This is a visual indication that there are no more keywords in the forward direction.

Pressing SHIFT+TAB causes the previous keyword to appear, and if you are at the first keyword in the list, it will cause the original text you typed to be restored. If you are at the original word and press SHIFT+TAB, the caption bar will flash to indicate that you cannot go back any further.

While all this sounds complex in theory, it is in practice very straightforward and natural to use, and once you get used to it you probably won't want to go back to the old way of doing things.

The advantage of keyword expansion becomes clear if you look at the following example: suppose you wanted to enter the 'smooth_color_triangle' keyword. You could of course type the entire keyword in (a total of twenty-one keystrokes). Or, using keyword expansion, you could enter it using only four keystrokes by typing 'sm' then TAB and TAB again. The first tab expands it to 'smooth' and the second tab expands it all the way to 'smooth_color_triangle'.

Hint: If you use keyword expansion and accidentally expand to a word you don't want, if you haven't yet exited keyword expansion mode, the best way to get back is to use SHIFT+TAB to go backwards. It is very easy to just hit the normal 'Undo' key out of habit. While this will work, it won't always restore the caret position. Using SHIFT+TAB also moves the edit caret back to its starting position as well as restoring the starting word.

CodeList

The CodeList feature is, like Keyword Expansion, designed to make editing POV-Ray scene files more convenient. It is by default assigned to the keystroke CTRL+SPACE (you can change this from the Keyboard Configuration property page).

Unlike keyword expansion (which allows you to cycle through a list of keywords, one at a time), CodeList allows you to see many of them at once, and select one with the cursor keys or mouse.

CodeList keyword expansion

Using CodeList

When you press CTRL+SPACE, the editor will extract the word under or immediately to the left of the edit caret (note that this differs from keyword expansion, which requires that the caret be at the end of a word). If this word is blank (that is, the caret was on blank space), or if the word does not even partially match any keyword, an alphabetically-sorted list of all POV-Ray scene file keywords is displayed slightly to the right of and below the edit position. If the extracted word was blank, the list will be positioned at the first entry, otherwise it will be positioned at the keyword that is closest (alphabetically) to the extracted word.

If, however, the extracted word perfectly matches a keyword, and is not part of any other keyword in the list, then the list box does not appear. Instead, the keyword that it matched is inserted into the line and the edit caret is moved to the end of that keyword.

If the above match does not occur, then the alphabetically-sorted list of keywords is displayed, and the list is positioned such that the keyword that the extracted word most closely matches is highlighted and is as close as possible to the center of the displayed portion of the list.

If you look at the above image, you will see an example of this situation. The partial keyword (just above and to the left of the top left-hand corner of the list box) is 'phon', and the list has been positioned to the closest keyword, which is 'phong'.

Once the list is displayed, you can cause the highlighted entry to be inserted into the line by just pressing ENTER, SPACE, TAB, or CTRL+SPACE again, or by double-clicking on a list entry. Pressing the ESCAPE key will remove the listbox without altering the line you are editing. You can navigate the listbox by using the up, down, page-up and page-down keys on your keyboard, by the mouse, or by typing (see below). If you cause text to be inserted by any of the above methods other than SPACE, the edit caret will be positioned immediately at the end of the inserted word. If, however, you press SPACE, the word will be inserted followed by a space, and the new edit position will be after the space.

While the list is displayed, even though the up and down arrow keys map to the listbox, the normal character keys still map to the editor. If you continue to type, the letters will be typed into the line at the editor caret position, and, additionally, the list box will automatically scroll so that the highlighted line is always the keyword that has the closest match to what you have typed in.

Summary

Just like keyword expansion, the codelist feature can seem complicated when explained in words. However, once you get used to it, it will become quite natural to use.

Configuring the Internal Editor

The built-in editor is extensively customizable. It utilizes syntax highlighting and understands .POV and .INC files as being in POV syntax. You can change the color settings used from the properties dialog (Alt + Enter). It also has built-in syntax highlighting for C, C++, Java, Basic, Pascal, SQL, HTML and XML.

Important Editor Notes

One important thing to note right away is that the editor properties dialog only allows you to set things that are implemented within the editor (remember, the editor is two components - a DLL called 'povcmax32.dll' (or similar), and another DLL which loads and 'wraps' it into POV-Ray for Windows). There are some other options implemented within the editor wrapper code in POV-Ray for Windows which are able to be accessed via the Editor menu (only visible when an editor is selected). For example, the keybinding for saving a file (Ctrl-S) is not listed in the editor properties since this function is handled by the wrapper code. You can't change this assignment.

Some people have asked why the don't ask again option in the render save dialog is not persistent across sessions. This is by design and is not likely to change.

The edit window context menu has an option for 'show/hide message window'. This window - when displayed at the bottom of an editor window - is sizable. A quick way to close the message window is just to hit ESCAPE, or drag the divider down to within a few pixels of the bottom border - when you release the mouse, the message window will vanish.

You can also tell POVWIN not to display the message window automatically when starting a render. You do this from the Editor menu, by turning off 'Auto-Show Parse Messages'. This is most useful with the Error File option.

POVWIN will optionally automatically load a file in which a parse error has occurred into the editor (or select it if it's already loaded) and place the cursor on the line and column of the offending code. This is able to be turned on or off using the 'Auto-Load Error File' option in the Editor menu. Also, if this option is on, and the message window was displayed automatically (see above), it will be closed automatically rather than being left open. The text describing the error will be displayed in the status bar at the bottom of the window. Note that, occasionally, if the error occurs inside a macro, the displayed line/column for the error will be wrong (though this is uncommon).

Trademarks

Default Key Mappings