Difference between revisions of "Documentation:Tutorial Section 1.1"

From POV-Wiki
Jump to navigation Jump to search
m (accidentlly deleted bottm nav)
m (consistency)
 
(12 intermediate revisions by 3 users not shown)
Line 211: Line 211:
 
===How Do I Begin?===
 
===How Do I Begin?===
 
   <p>POV-Ray scenes are described in a special text language called a
 
   <p>POV-Ray scenes are described in a special text language called a
   <!--<linkto "scene description language">scene description language</linkto>--->[[Documentation:Reference Section 2#Scene Description Language|scene description language]].
+
   <!--<linkto "scene description language">scene description language</linkto>--->[[Reference:Scene Description Language|scene description language]].
 
   You will type commands into a plain  text file and POV-Ray will read it
 
   You will type commands into a plain  text file and POV-Ray will read it
 
   to create the image. The process of running POV-Ray is a little different
 
   to create the image. The process of running POV-Ray is a little different
Line 224: Line 224:
  
 
===Notation and Basic Assumptions===
 
===Notation and Basic Assumptions===
<p>Throughout the tutorial and reference books, a consistent notation is used to mark keywords of the scene description language, command line switches, INI file keywords and file names.</p>
+
<p>Throughout the tutorial and reference sections, a consistent notation is used to mark keywords of the scene description language, command line switches, INI file keywords and file names.</p>
 
<p><strong>For example:</strong></p>
 
<p><strong>For example:</strong></p>
 
<p>Scene description language keywords and command-line switches:</p>
 
<p>Scene description language keywords and command-line switches:</p>
Line 256: Line 256:
 
</ul>
 
</ul>
  
<p class="Note"><strong>Note:</strong> POV-Ray is a command-line program on Unix and other text-based operating systems and is menu-driven on Windows and Macintosh platforms. Some of these operating systems use folders to store files while others use directories. Some separate the folders and sub-folders with a slash character (<code>/</code>), back-slash character (<code>\</code>), or others. </p>
+
<p>{{New}} in version 3.8 these additional annotations appear throughout the documentation:</p>
<p>We have tried to make this documentation as generic as possible but sometimes we have to refer to folders, files, options etc. and there is noway to escape it. Here are some assumptions we make...</p><ol><li> You installed POV-Ray in the <code>C:\POVRAY36</code> directory. For MS-Dos this is probably true but for Unix it might be <code>/usr/povray3</code>, or for Windows it might be<code> C:\Program Files\POV-Ray for Windows v3.6</code>, for Mac it might be <code>MyHD:Apps:POV-Ray 36:</code>, or you may have used some other drive or directory. So if we tell you that Include files are stored in the <code>\povray36\include</code> directory, we assume you can translate that to something like<code>::POVRAY36:INCLUDE</code> or <code>C:\Program Files\POV-Ray for Windows v3.6\include</code> or whatever is appropriate for your platform, operating system and installation.<li> POV-Ray uses INI files and/or command-line switches (if available) to choose options in all versions, but Windows and Mac also use dialog boxes or menu choices to set options. We will describe options assuming you are using switches or INI files when describing what the options do. We have taken care to use the same terminology in designing menus and dialogs as we use in describing switches or INI keywords. See your version-specific documentation on menu and dialogs.<li> Some of you are reading this using a help-reader, built-in help,web-browser, formatted printout, or plain text file. We assume you know how to get around in which ever medium you are using. We will say See the chapter on <!--<linkto "Setting POV-Ray Options">Setting POV-Ray Options</linkto>--->[[Documentation:Tutorial Section 2.1#Setting POV-Ray Options|Setting POV-Ray Options]] we assume you can click, scroll, browse, flip pages or whatever to get there.</ol>
+
<ul class="index">
 +
  <li>{{Change}} followed by a version reference and designates a behavior change</li>
 +
  <li>{{New}} followed by a version reference to designate feature addition</li>
 +
  <li>The generic form <code>vX.y.z</code> of the version number and it's short form <code>vX.y</code> currently v3.8.0 and
 +
    v3.8 respectively</li> 
 +
</ul>
 +
 
 +
<p class="Note"><strong>Note:</strong> POV-Ray is available as a command-line program on some platforms and as a GUI on others. Some of these platforms use folders to store files while others use directories. Some separate the folders and sub-folders with a slash character (<code>/</code>), back-slash character (<code>\</code>), or others. We have tried to make this documentation as generic as possible but sometimes we have to refer to folders, files, options etc., and rather than try to represent all possible combinations
 +
we sometimes simplify the documentation by referring to a hypothetical 'standard installation' of POV-Ray upon a Microsoft Windows computer.
 +
</p>
 +
<p> Here are some additional assumptions to be found in the documentation:</p>
 +
<ol>
 +
<li>You installed POV-Ray in the default location for Windows, with the binaries in <code>c:\Program Files\POV-Ray\vX.y</code> and include/scene files in <code>My Documents\POV-Ray\vX.y</code>.
 +
If we say 'include files are stored in the <code>include</code> directory', we mean the directory called 'include' located immediately within the folder which was used for documents, in the above case, it would be <code>My Documents\POV-Ray\vX.y\include</code>. We assume you can translate that to something like <code>/usr/local/share/povray/vX.y/include</code> for Linux or whatever is appropriate for your platform, operating system and personal installation.
 +
<li> POV-Ray uses INI files and/or command-line switches (if available) to choose options in all versions, but some platforms (e.g. Windows) also use dialog boxes or menu choices to set options. We will describe options assuming you are using switches or INI files when describing what the options do, as it is consistent across all platforms (all GUI versions of POV-Ray also provide a means of accepting command-line options and reading INI files from within the GUI - generally speaking, the menus and dialogs just provide
 +
an easier means of doing the same thing).
 +
<li>You may be reading this documentation using an operating-system specific help program, web browser, physical printout, PDF viewer, or text editor. We assume you know how to get around in which ever medium you are using. If we say &quot;See the chapter on <!--<linkto "Setting POV-Ray Options">Setting POV-Ray Options</linkto>--->[[Documentation:Tutorial Section 2.2#Setting POV-Ray Options|Setting POV-Ray Options]]&quot; we assume you can click, scroll, browse, flip pages or whatever to get there.</ol>
 
<!--<wikinav>--->
 
<!--<wikinav>--->
 
<br>
 
<br>

Latest revision as of 15:59, 4 July 2017

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


The Early History of POV-Ray

The Original Creation Message

11906 S16/Raytraced Images
   07-Mar-91 18:56:37
Sb: DKB Development
Fm: David Buck 70521,1371
To: All

Greetings all.  This is my first posting to this group, so you'll
have to excuse me if I make any mistakes in this post.

Finally, after several weeks of waiting, I've received my CompuServe
account.  It's nice to see that people are enjoying my raytracer
(DKB, of course). I have noticed, however, that you are less than
satisfied at the support I've been able to provide <grin>.
True, I'm the first to admit that the support is poor.  I have 
little time these days to work on graphics - it takes long enough
to answer all the questions I get asked on a daily basis from all
across the world.

My motivation for releasing the raytracer as Freely Distributable
software in the first place was to allow people to have some fun
with a program I'd developed for just that purpose.  I don't 
consider it to be a professional package - I know it's nowhere near
that good.  I didn't make it shareware, however, because I knew I
wouldn't have much time for support.  I didn't want the hassles of
maintaining user lists, sending updates and notices, etc.

There has recently been a proposal in this forum that you write
your own raytracer to use instead of DKB.  Perhaps I can make that
prospect a little bit easier.  Suppose we take DKB and use it as a
base for a completely new system (the name "Renderdog" has
been tossed around, but I'm not fond of that one <g>). I would
like to propose the name "Software Taskforce on Animation and
Rendering" or STAR.  I would imagine that there would be
several packages developed such as:

 STAR Light  - the raytracer
 STAR Guider - an animation system
 STAR Maker - a user interface for StarLight

If you decide to do this, I would like to place a few rules on the
packages (or at least those developed from DKB):

  - they will remain freely distributable
  - support and maintenance of this new product will be undertaken
    by the STAR team (including but not limited to myself)
  - the programs will remain as portable as possible

What do you think of this proposal?

David Buck

The Name

More on how POV-Ray came to its name.

**************************************************************
from Chris Young, to whom I asked if POV's name was related
to the title of a sci-fi book I had just found on a flea market.
**************************************************************
 
Varley is one of my favorite authors and I've owned that book 
long before POV-Ray existed.  POV-Ray was originally going to be 
called Starlight or StarLite or something similar but somebody 
else, I don't know who, said we'd get in trademark trouble over 
some existing product.  Drew Wells was team leader and he picked 
Persistence of Vision based on the properties of the human visual 
system. I also felt there was a double meaning in that POV-Ray 
was the continuation (or persistance) of David K. Buck's DKB-Trace.  
I warned Drew about Varley's book but book titles aren't as messy 
as product names.  Note also that Public Broadcasting System has 
a documentary series called POV but that stands for Point Of View 
which is the filmmaking term for hand-held camera, cinema-verite 
style used in many documentaries.
 
I wanted to take our team name from the Fractint Stone Soup Group 
and call us the Crystal Soup Group but I got voted down.
 
        Chris Young, POV-Team Coordinator

**************************************************************
from unknown source
**************************************************************
 
After the recent thread on the starting time of POV-Ray I did
a search and found this post to this very news group from
David Buck himself. The message places the birth of the POV-Ray
project to be in May of 1991. A very historic event!
 
I hope I'm not stepping on toes by re-posting
it  :-)
 
Harold
 
Sun, 19 Feb 1995 19:14:44 GMT
(STEERPIKE) says:
>I had always presumed that Persistance of Vision was a pun on
>the name of Salvador Dali's painting "The Persistance of
>Memory". Is this right, and if not, how did POV-Ray come to 
> have such a poetic name? :)
 
The POV-Ray project started in May 1991 when I first proposed the
idea to a group of people on CompuServe.  They liked my DKBTrace
raytracer but didn't like the fact that I was too slow adding new
features to it.  They were going to re-write a raytracer from
scratch, but I suggested that after version 2.12 of DKBTrace, they
could take the code as is and develop it from there into a new
raytracer.  The first name was STAR - an acronym for something or
other.  Then someone in the group came up with "Persistance of
Vision".  We liked it because of its reference to Dali (I
believe the painting was actually called Persistance of Vision - am
I mistaken?).  Moreover, it seemed to symbolize the team who 
"Persisted" to achieve their "Vision".  The 
third reference was to the phychological effect that seeing an image
flashed on a screen causes you to retain that image in short term
memory.  Thus, your memory was a representation of reality but not
really reality. They all seemed to fit together to make a nice name.
Early on, we were abbreviating the name to PVRay, but we were
concerned about a commercial product called PV-Wave.  We agreed to
change the abbreviation to POV-Ray and standardize on the spelling.
 
>David Buck

A Historic 'Version History'

The version history as it was included in PV-Ray 0.5 BETA. Notice the name changes...

Persistence of Vision Raytracer Version History
-------------------------------------------------

 PV-Ray was originally DKBTrace Ver. 2.12 written by David Buck. He 
donated the rights to his source code so the PV-Team could enhance
this raytracer as a group project similar to Fractint. The source
code for PV-Ray will always be freely distributable subject to the
restrictions in the header files. Thanks David, for your generous
gift!
	
Version 0.02 BETA Release 7/29/91 (as STAR-Light)
----------------------------------
 First version is still basically DKBTrace 2.12 with a few new
 features.
 
 - Materials mapping added by Drew Wells.(see matmap.dat)
 - ONION & LEOPARD textures added by Scott Taylor.
 - Time to trace display added by Bill Pulver.
 - Grayscale display (+g) for IBM-PC's added by Scott Taylor.
 - Small wood texture bug fixed to create true cylinders.
 - Verbose now displays more info including file being traced.
 - Option +vO added to enable old-style terse verbose.
 - Texture.c broken into smaller modules.
 - PAINTED1, 2, & 3 added for developers.
 - BUMPY1, 2, & 3 added for developers.
  
PvRay Version 0.5 BETA Release 9/07/91
----------------------------------
 Many more changes this time around, including...

- Many enhancements from Alexander Enzmann
   - Bezier bicubic subpatches
   - Polynomial surfaces
   - New mapping types (sphere, etc.)
   - Sturmian sequences
   - Clipping shapes
   - (have I forgotten anything??)
- Lots of hard work and enhancements by Aaron Collins
- Height fields by Doug Muir
- Bump Mapping by Doug Muir and Drew Wells
- Interpolation by Girish T. Hagan adapted for mapping by Drew Wells
- # and ; are now ignored. 
- case_sensitive keywords and commandline option added by Drew Wells
  > case_sensitive_yes -- All words checked for exact case.
                             Keywords must be in upper case.
                             (*Old DKB Style*)
  > case_sensitive_no  -- Case is ignored for all words.
  > case_sensitive_opt -- DEFAULT - All words checked for exact
                             case except keywords. Keywords will be
                             accepted in upper and/or lower case. 
  > command line -- /ty = yes, /tn = no, /to = opt
- cnvdat.c to convert old dat files included with pvsrc.
- C++ style commenting - // ignore to end of line. 
  and /* ignore between braces */ nesting not allowed.
- New default style verbose trace info (+v1) 
- Old-new style verbose (+v0)
- Verbose trace info outputs to stderr so that stats can be
  redirected to file.
- New stats display outputs to stdout for better redirection.
- New lighting routines by David Buck.
- The declared colors Red, Green, and Blue in colors.dat are now
  CRed, CBlue, CGreen.
- The declared quadric Sphere in shapes.dat is now QSphere.
- Textures.dat has been cleaned up and commented.

How Do I Begin?

POV-Ray scenes are described in a special text language called a scene description language. You will type commands into a plain text file and POV-Ray will read it to create the image. The process of running POV-Ray is a little different on each platform or operating system. You should read the platform-specific documentation as suggested earlier in this introduction. It will tell you how to command POV-Ray to turn your text scene description into an image. You should try rendering several sample images before attempting to create your own.

Once you know how to run POV-Ray on your computer and your operating system, you can proceed with the tutorial which follows. The tutorial explains how to describe the scene using the POV-Ray language.

Notation and Basic Assumptions

Throughout the tutorial and reference sections, a consistent notation is used to mark keywords of the scene description language, command line switches, INI file keywords and file names.

For example:

Scene description language keywords and command-line switches:

  • sphere, 4.0 * sin(45.0)
  • +W640 +H480

Syntax, optional syntax, multiple syntax, and zero or more syntax items allowed respectively:

  • SYNTAX_ITEM
  • [SYNTAX_ITEM]
  • SYNTAX_ITEM...
  • [SYNTAX_ITEM...]

A float value or expression, and a vector value or expression:

  • Value_1
  • <Value_1>

Choices are represented by a vertical bar between syntax items:

  • ITEM1 | ITEM2 | ITEM3

Certain lists and arrays also require square braces as part of the language rather than the language description:

  • [ ITEM ]

New in version 3.8 these additional annotations appear throughout the documentation:

  • Change followed by a version reference and designates a behavior change
  • New followed by a version reference to designate feature addition
  • The generic form vX.y.z of the version number and it's short form vX.y currently v3.8.0 and v3.8 respectively

Note: POV-Ray is available as a command-line program on some platforms and as a GUI on others. Some of these platforms use folders to store files while others use directories. Some separate the folders and sub-folders with a slash character (/), back-slash character (\), or others. We have tried to make this documentation as generic as possible but sometimes we have to refer to folders, files, options etc., and rather than try to represent all possible combinations we sometimes simplify the documentation by referring to a hypothetical 'standard installation' of POV-Ray upon a Microsoft Windows computer.

Here are some additional assumptions to be found in the documentation:

  1. You installed POV-Ray in the default location for Windows, with the binaries in c:\Program Files\POV-Ray\vX.y and include/scene files in My Documents\POV-Ray\vX.y. If we say 'include files are stored in the include directory', we mean the directory called 'include' located immediately within the folder which was used for documents, in the above case, it would be My Documents\POV-Ray\vX.y\include. We assume you can translate that to something like /usr/local/share/povray/vX.y/include for Linux or whatever is appropriate for your platform, operating system and personal installation.
  2. POV-Ray uses INI files and/or command-line switches (if available) to choose options in all versions, but some platforms (e.g. Windows) also use dialog boxes or menu choices to set options. We will describe options assuming you are using switches or INI files when describing what the options do, as it is consistent across all platforms (all GUI versions of POV-Ray also provide a means of accepting command-line options and reading INI files from within the GUI - generally speaking, the menus and dialogs just provide an easier means of doing the same thing).
  3. You may be reading this documentation using an operating-system specific help program, web browser, physical printout, PDF viewer, or text editor. We assume you know how to get around in which ever medium you are using. If we say "See the chapter on Setting POV-Ray Options" we assume you can click, scroll, browse, flip pages or whatever to get there.


The Early History of POV-Ray Getting Started


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