# Unit CastleSphereSampling

Classes, Interfaces, Objects and Records
Types
Constants
Variables

## Description

Random sampling of points (directions) on a sphere and hemisphere. Useful e.g. for ray-tracers.

Most of the implementation based on "Global Illumination Compendium" IV.B [http://www.cs.kuleuven.ac.be/˜phil/GI/]. See also images there, they help to illustrate the meaning of some functions here.

We use two ways to represent points on hemisphere:

1. Functions without "XYZ" suffix return vector of 2 floats = two angles, called phi and theta (in this order). Phi (in [0, 2*Pi]) is an angle from some chosen meridian. Theta (in [0, Pi/2] for hemisphere and [0, Pi] for sphere) is an angle from chosen vector pointing outward from the (hemi)sphere. See images in "Global Illumination Compendium", they are probably much easier to understand than this definition.

2. Functions with "XYZ" suffix return 3D point x, y, z.

• (0, 0, 0) is the center of (hemi)sphere,

• (0, 0, 1) is the chosen outward vector (i.e. Theta = 0 there),

• (1, 0, 0) is the direction where Phi = 0 and Theta = Pi/2,

• (0, 1, 0) is the direction where Phi = Pi/2 and Theta = Pi/2.

This is matching conventions in "Global Illumination Compendium", see there (point 21).

Functions with Density <> Const return PdfValue for returned point, i.e. for density p(Theta) it's PfdValue = p(Result). These functions try to calculate PdfValue smartly (often calculating PfdValue and calculating Result uses the same intermediate calculation, so we can save some computation). PdfValue is needed for importance sampling.

## Overview

### Functions and Procedures

 `function PhiThetaToXYZ(const PhiTheta: TVector2; const SphereRadius: Single) :TVector3; overload;` `function PhiThetaToXYZ(const PhiTheta: TVector2; const SphereTheta0: TVector3): TVector3; overload;` `function XYZToPhiTheta(const XYZ: TVector3): TVector2;` `function RandomHemispherePointConst: TVector2;` `function RandomHemispherePointConstXYZ: TVector3;` `function RandomHemispherePointCosTheta( out PdfValue: Single): TVector2;` `function RandomHemispherePointCosThetaXYZ( out PdfValue: Single): TVector3;` `function RandomHemispherePointCosThetaExp(const n: Single; out PdfValue: Single): TVector2;` `function RandomHemispherePointCosThetaExpXYZ(const n: Single; out PdfValue: Single): TVector3;`

## Description

### Functions and Procedures

 `function PhiThetaToXYZ(const PhiTheta: TVector2; const SphereRadius: Single) :TVector3; overload;` Convert from PhiTheta representation of (hemi)sphere direction to XYZ representation. See the beginning of this unit's documentation, CastleSphereSampling, for more precise description of XYZ representation.
 `function PhiThetaToXYZ(const PhiTheta: TVector2; const SphereTheta0: TVector3): TVector3; overload;` Convert from PhiTheta representation of (hemi)sphere direction to XYZ representation. This is the more advanced version where you can freely specify which vector is the "main outside (hemi)sphere vector", SphereTheta0. Points with Theta = 0 are exactly on SphereTheta0. It is undefined where point like (Phi = 0, Theta = Pi/2) (or any other point with Theta <> 0) will be placed, i.e. it's not defined where's the "chosen meridian" for Phi = 0. However it's defined that this meridian will be determined only by SphereTheta0, and this is usually sufficient (since this makes sure that sampling and then converting to XYZ multiple points with the same SphereTheta0 will preserve sampled density). Note that the length of SphereTheta0 determines also the sphere radius.
 `function XYZToPhiTheta(const XYZ: TVector3): TVector2;` Convert from XYZ representation of (hemi)sphere direction to PhiTheta.
 `function RandomHemispherePointConst: TVector2;` Random point (direction) on unit hemisphere, sampled with constant density (p(Theta) = 1/2*Pi).
 `function RandomHemispherePointConstXYZ: TVector3;`
 `function RandomHemispherePointCosTheta( out PdfValue: Single): TVector2;` Random point (direction) on unit hemisphere, sampled with density p(Theta) = cos(Theta)/Pi.
 `function RandomHemispherePointCosThetaXYZ( out PdfValue: Single): TVector3;`
 `function RandomHemispherePointCosThetaExp(const n: Single; out PdfValue: Single): TVector2;` Random point (direction) on unit hemisphere, sampled with density p(Theta) = (n+1) * (cos(Theta))ˆn / 2*Pi.
 `function RandomHemispherePointCosThetaExpXYZ(const n: Single; out PdfValue: Single): TVector3;`

Generated by PasDoc 0.16.0.