Difference between revisions of "Documentation Talk:Reference Section 2"

From POV-Wiki
Jump to navigation Jump to search
m (started talk page (rand/seed))
 
m (follow up)
 
(3 intermediate revisions by 3 users not shown)
Line 28: Line 28:
 
calls to <code>rand()</code>. This is very annoying.</p>
 
calls to <code>rand()</code>. This is very annoying.</p>
 
<p>
 
<p>
 +
 +
 +
 +
 +
I think the text <br/>
 +
 +
In addition to the above built-in functions, you may also define your own functions
 +
using the #macro directive. See the section "User Defined Macros" for more details.<br/>
 +
 +
should be changed to<br/>
 +
 +
In addition to the above built-in functions, you may also define your own functions
 +
using the function keyword. See the section "User Defined Functions" for more details.<br>
 +
 +
Considering that #macro is different from a function and clicking on the function
 +
keyword in the overview bring you here.[[User:Froesccn|Froesccn]] 22:42, 31 August 2010 (UTC)
 +
 +
:* done --[[User:Jholsenback|jholsenback]] 11:01, 1 September 2010 (UTC)
 +
----
 +
* Adding bitwise_and, bitwise_or & bitwise_xor: syntax description (only the FLOAT_FUNCTION of the PRE is updated) & functions description (further down, in atanh and ceil). the warning apply to all 3 functions.
 +
--[[User:Le Forgeron|Le Forgeron]] 09:12, 4 December 2010 (UTC)
 +
 +
:* tis done: --[[User:Jholsenback|jholsenback]] 13:28, 4 December 2010 (UTC)
 +
 +
----
 +
====Float Expressions====
 +
<!--<indexentry "Expressions, float" "Float, expressions">--->
 +
 +
<p>Many parts of the POV-Ray language require you to specify one or more
 +
floating point numbers. A floating point number is a number with a decimal
 +
point. Floats may be specified using literals, identifiers or functions which
 +
return float values. You may also create very complex float expressions from
 +
combinations of any of these using various familiar operators.</p>
 +
<p>
 +
Where POV-Ray needs an integer value it allows you to specify a float value
 +
and it truncates it to an integer. When POV-Ray needs a logical or boolean
 +
value it interprets any non-zero float as true and zero as false. Because
 +
float comparisons are subject to rounding errors POV-Ray accepts values
 +
extremely close to zero as being false when doing boolean functions.
 +
Typically values whose absolute values are less than a preset value <em>
 +
epsilon</em> are considered false for logical expressions. The value of <em>
 +
epsilon</em> is system dependent but is generally about 1.0e-10. Two floats
 +
<em>a</em> and <em>b</em> are considered to be equal if <em>abs(a-b) &lt;
 +
epsilon.</em></p>
 +
<p>
 +
The full syntax for float expressions is given below. Detailed explanations
 +
are given in the following sub-sections.</p>
 +
<pre>
 +
FLOAT:
 +
  NUMERIC_TERM [SIGN NUMERIC_TERM]...
 +
SIGN:
 +
  + | -
 +
NUMERIC_TERM:
 +
  NUMERIC_FACTOR [MULT NUMERIC_FACTOR]...
 +
MULT:
 +
  * | /
 +
NUMERIC_FACTOR:
 +
  FLOAT_LITERAL        |
 +
  FLOAT_IDENTIFIER    |
 +
  SIGN NUMERIC_FACTOR  |
 +
  FLOAT_FUNCTION      |
 +
  FLOAT_BUILT-IN_IDENT |
 +
  ( FULL_EXPRESSION )  |
 +
  ! NUMERIC_FACTOR
 +
VECTOR DECIMAL_POINT DOT_ITEM FLOAT_LITERAL:
 +
  [DIGIT...] [DECIMAL_POINT] DIGIT... [EXP [SIGN] DIGIT...]
 +
DIGIT:
 +
  0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
 +
DECIMAL_POINT:
 +
  .
 +
EXP:
 +
  e | E
 +
DOT_ITEM:
 +
  x | y | z | t | u | v | red | blue | green | filter |
 +
  transmit | gray
 +
FLOAT_FUNCTION:
 +
  abs( FLOAT ) | acos( FLOAT ) | acosh( FLOAT ) | asc( STRING ) |
 +
  asin( FLOAT ) | asinh( FLOAT ) | atan( FLOAT) | atanh( FLOAT) |
 +
  atan2( FLOAT , FLOAT ) | bitwise_and( FLOAT, FLOAT, ...) |
 +
  bitwise_or (FLOAT, FLOAT, ...) | bitwise_xor ( FLOAT, FLOAT, ...) |
 +
  ceil( FLOAT ) | cos( FLOAT ) | cosh( FLOAT ) | defined(IDENTIFIER ) |
 +
  degrees( FLOAT ) | dimensions( ARRAY_IDENTIFIER ) |
 +
  dimension_size( ARRAY_IDENTIFIER , FLOAT ) |
 +
  div( FLOAT , FLOAT ) | exp( FLOAT ) | file_exists( STRING ) |
 +
  floor( FLOAT ) | int( FLOAT ) | ln(Float | log( FLOAT ) |
 +
  max( FLOAT , FLOAT, ... ) | min( FLOAT , FLOAT, ... ) |
 +
  mod( FLOAT , FLOAT ) | pow( FLOAT , FLOAT ) |
 +
  radians( FLOAT ) | rand( FLOAT ) | seed( FLOAT ) |
 +
  select( FLOAT, FLOAT, FLOAT [,FLOAT]) | sin( FLOAT ) |
 +
  sinh( FLOAT ) | sqrt( FLOAT ) | strcmp( STRING , STRING ) |
 +
  strlen( STRING ) | tan( FLOAT ) | tanh( FLOAT ) |
 +
  val( STRING ) | vdot( VECTOR , VECTOR ) | vlength( VECTOR ) |
 +
  FLOAT_BUILT-IN_IDENT:
 +
  clock | clock_delta | clock_on | false | final_clock |
 +
  final_frame | frame_number | initial_clock | initial_frame |
 +
  image_width | image_height | no | off | on | pi | true |
 +
  version | yes |
 +
FULL_EXPRESSION:
 +
  LOGICAL_EXPRESSION [? FULL_EXPRESSION : FULL_EXPRESSION]
 +
LOGICAL_EXPRESSION:
 +
  REL_TERM [LOGICAL_OPERATOR REL_TERM]...
 +
LOGICAL_OPERATOR:
 +
  &amp; | | (note: this means an ampersand or a
 +
    vertical bar is a logical operator)
 +
REL_TERM:
 +
  FLOAT [REL_OPERATOR FLOAT]...
 +
REL_OPERATOR:
 +
  &lt; | &lt;= | = | &gt;= | &gt; | !=
 +
INT:
 +
  FLOAT (note: any syntax which requires a
 +
  integer INT will accept a FLOAT
 +
  and it will be truncated to an
 +
  integer internally by POV-Ray).
 +
</pre>
 +
----
 +
<p>
 +
<!--<indexentry primary "bitwise_and">--->
 +
<code> bitwise_and(A,B,...)</code> Bitwise And of two or more float values considered as integers.</p>
 +
<p>
 +
<!--<indexentry primary "bitwise_or">--->
 +
<code> bitwise_or(A,B,...)</code> Bitwise Or of two or more float values considered as integers.</p>
 +
<p>
 +
<!--<indexentry primary "bitwise_xor">--->
 +
<code> bitwise_xor(A,B,...)</code> Bitwise Xor of two or more float values considered as integers.</p>
 +
<p class="Warning"><strong>Note:</strong> Each para­meter is first con­verted to integer (so frac­tional part is ignored), and the com­pu­tation is per­formed on a clas­sical int (do not expect to much pre­cision, as con­vertion from a double pre­cision number (usually with 52 bits man­tissa) to an integer and back to a double pre­cision number is not the best way to keep track of every bits).</p>

Latest revision as of 13:28, 4 December 2010

rand(I) Returns the next pseudo-random number from the stream specified by the positive integer I. You must call seed() to initialize a random stream before calling rand(). The numbers are uniformly distributed, and have values between 0.0 and 1.0, inclusively. The numbers generated by separate streams are independent random variables.

seed(I) Initializes a new pseudo-random stream with the initial seed value A. The number corresponding to this random stream is returned. Any number of pseudo-random streams may be used as shown in the example below:

#declare R1 = seed(0);
#declare R2 = seed(12345);
sphere { <rand(R1), rand(R1), rand(R1)>, rand(R2) }

Multiple random generators are very useful in situations where you use rand() to place a group of objects, and then decide to use rand() in another location earlier in the file to set some colors or place another group of objects. Without separate rand() streams, all of your objects would move when you added more calls to rand(). This is very annoying.

I think the text
In addition to the above built-in functions, you may also define your own functions using the #macro directive. See the section "User Defined Macros" for more details.
should be changed to
In addition to the above built-in functions, you may also define your own functions using the function keyword. See the section "User Defined Functions" for more details.
Considering that #macro is different from a function and clicking on the function keyword in the overview bring you here.Froesccn 22:42, 31 August 2010 (UTC)


  • Adding bitwise_and, bitwise_or & bitwise_xor: syntax description (only the FLOAT_FUNCTION of the PRE is updated) & functions description (further down, in atanh and ceil). the warning apply to all 3 functions.

--Le Forgeron 09:12, 4 December 2010 (UTC)


Float Expressions

Many parts of the POV-Ray language require you to specify one or more floating point numbers. A floating point number is a number with a decimal point. Floats may be specified using literals, identifiers or functions which return float values. You may also create very complex float expressions from combinations of any of these using various familiar operators.

Where POV-Ray needs an integer value it allows you to specify a float value and it truncates it to an integer. When POV-Ray needs a logical or boolean value it interprets any non-zero float as true and zero as false. Because float comparisons are subject to rounding errors POV-Ray accepts values extremely close to zero as being false when doing boolean functions. Typically values whose absolute values are less than a preset value epsilon are considered false for logical expressions. The value of epsilon is system dependent but is generally about 1.0e-10. Two floats a and b are considered to be equal if abs(a-b) < epsilon.

The full syntax for float expressions is given below. Detailed explanations are given in the following sub-sections.

FLOAT:
  NUMERIC_TERM [SIGN NUMERIC_TERM]...
SIGN:
  + | -
NUMERIC_TERM:
  NUMERIC_FACTOR [MULT NUMERIC_FACTOR]...
MULT:
  * | /
NUMERIC_FACTOR:
  FLOAT_LITERAL        |
  FLOAT_IDENTIFIER     |
  SIGN NUMERIC_FACTOR  |
  FLOAT_FUNCTION       |
  FLOAT_BUILT-IN_IDENT |
  ( FULL_EXPRESSION )  |
  ! NUMERIC_FACTOR
VECTOR DECIMAL_POINT DOT_ITEM FLOAT_LITERAL:
  [DIGIT...] [DECIMAL_POINT] DIGIT... [EXP [SIGN] DIGIT...]
DIGIT:
  0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
DECIMAL_POINT:
  .
EXP:
  e | E
DOT_ITEM:
  x | y | z | t | u | v | red | blue | green | filter |
  transmit | gray
FLOAT_FUNCTION:
  abs( FLOAT ) | acos( FLOAT ) | acosh( FLOAT ) | asc( STRING ) |
  asin( FLOAT ) | asinh( FLOAT ) | atan( FLOAT) | atanh( FLOAT) |
  atan2( FLOAT , FLOAT ) | bitwise_and( FLOAT, FLOAT, ...) |
  bitwise_or (FLOAT, FLOAT, ...) | bitwise_xor ( FLOAT, FLOAT, ...) |
  ceil( FLOAT ) | cos( FLOAT ) | cosh( FLOAT ) | defined(IDENTIFIER ) |
  degrees( FLOAT ) | dimensions( ARRAY_IDENTIFIER ) |
  dimension_size( ARRAY_IDENTIFIER , FLOAT ) | 
  div( FLOAT , FLOAT ) | exp( FLOAT ) | file_exists( STRING ) |
  floor( FLOAT ) | int( FLOAT ) | ln(Float | log( FLOAT ) |
  max( FLOAT , FLOAT, ... ) | min( FLOAT , FLOAT, ... ) |
  mod( FLOAT , FLOAT ) | pow( FLOAT , FLOAT ) |
  radians( FLOAT ) | rand( FLOAT ) | seed( FLOAT ) |
  select( FLOAT, FLOAT, FLOAT [,FLOAT]) | sin( FLOAT ) |
  sinh( FLOAT ) | sqrt( FLOAT ) | strcmp( STRING , STRING ) |
  strlen( STRING ) | tan( FLOAT ) | tanh( FLOAT ) |
  val( STRING ) | vdot( VECTOR , VECTOR ) | vlength( VECTOR ) | 
  FLOAT_BUILT-IN_IDENT:
  clock | clock_delta | clock_on | false | final_clock |
  final_frame | frame_number | initial_clock | initial_frame |
  image_width | image_height | no | off | on | pi | true |
  version | yes |
FULL_EXPRESSION:
  LOGICAL_EXPRESSION [? FULL_EXPRESSION : FULL_EXPRESSION]
LOGICAL_EXPRESSION:
  REL_TERM [LOGICAL_OPERATOR REL_TERM]...
LOGICAL_OPERATOR:
  & | | (note: this means an ampersand or a 
     vertical bar is a logical operator) 
REL_TERM:
  FLOAT [REL_OPERATOR FLOAT]...
REL_OPERATOR:
  < | <= | = | >= | > | !=
INT:
  FLOAT (note: any syntax which requires a
   integer INT will accept a FLOAT
   and it will be truncated to an
   integer internally by POV-Ray).

bitwise_and(A,B,...) Bitwise And of two or more float values considered as integers.

bitwise_or(A,B,...) Bitwise Or of two or more float values considered as integers.

bitwise_xor(A,B,...) Bitwise Xor of two or more float values considered as integers.

Note: Each para­meter is first con­verted to integer (so frac­tional part is ignored), and the com­pu­tation is per­formed on a clas­sical int (do not expect to much pre­cision, as con­vertion from a double pre­cision number (usually with 52 bits man­tissa) to an integer and back to a double pre­cision number is not the best way to keep track of every bits).