Generic sampler state type. More...
Public Member Functions | |
| State64Bit ()=default | |
| Construct an invalid object. | |
| State64Bit (int x, int y, int frame, int index) | |
| Parametrised pixel constructor. | |
| State64Bit | pixelDecorrelate () const |
| Decorrelate state between pixels. | |
| State64Bit | newDomain (int key) const |
| Derive a sampler object as a new domain. | |
| State64Bit | newDomainSplit (int key, int size, int index) const |
| Derive a split sampler object with a local and a global distribution. | |
| State64Bit | newDomainDistrib (int key, int index) const |
| Derive a split sampler object with a local distribution. | |
| template<int Size> | |
| void | drawRnd (std::uint32_t rnd[Size]) const |
| Draw integer pseudo random values from domain. | |
Public Attributes | |
| std::uint32_t | patternId |
| Identifier for domain pattern. | |
| std::uint16_t | sampleId |
| Identifier for sample index. | |
| std::uint16_t | pixelId |
| Identifier for pixel position. | |
Static Public Attributes | |
| static constexpr auto | maxIndexBitSize = 16 |
| 2^16 index upper limit. | |
| static constexpr auto | maxIndexSize = 1 << 16 |
| 2^16 index upper limit. | |
| static constexpr auto | spatialEncodeBitSizeX = 8 |
| 256 pixels in x. | |
| static constexpr auto | spatialEncodeBitSizeY = 8 |
| 256 pixels in y. | |
Detailed Description
This type is used to represent the state of higher level sampler implementations. The size of the type is carefully handled to make sure it is appropriate to pass-by-value. This allows for efficient functional style use of the higher level API, an important requirement of the API design. This type also provides functionality to mutate the state when building new domains, along with the computation of generic PRNG values.
Constructor & Destructor Documentation
◆ State64Bit() [1/2]
|
default |
Create a placeholder object to allocate containers, etc. The resulting object is invalid, and you should initialise it by replacing the object with another from a parametrised constructor.
◆ State64Bit() [2/2]
Create an object based on the pixel, frame and sample indices. Once constructed the state object is valid and ready to use. Pixels are correlated by default, use pixelDecorrelate() to decorrelate pixels.
- Parameters
-
[in] x Pixel coordinate on the x axis. [in] y Pixel coordinate on the y axis. [in] frame Time index value. [in] index Sample index. Must be positive.
Member Function Documentation
◆ pixelDecorrelate()
|
inline |
Using the pixelId, randomise the object state so that correlation between pixels is removed. You may want to call this after initial construction of which leaves pixels correlated as default.
- Returns
- Decorrelated state object.
◆ newDomain()
|
inline |
The function derives a mutated copy of the current sampler object. This new object is called a domain. Each domain produces an independent 4 dimensional pattern. Calling the draw* member functions below on the new child domain will produce a different value to that of the current parent domain.
N child domains can be derived from a single parent domain with the use of the key argument. Keys must have at least one bit difference, but can be a simple incrementing sequence. A single child domain can itself derive N child domains. This process results in a domain tree.
The calling code can use up to 4 dimensions from each domain (these are typically of the highest quality), joining them together to form an N dimensional pattern. This technique is called padding.
- Parameters
-
[in] key Index key of next domain.
- Returns
- Child domain based on the current object state and key.
◆ newDomainSplit()
|
inline |
Like newDomain, this function derives a mutated copy of the current sampler object. However, using a technique called splitting, this domain can have a higher sample rate based on a fixed multiplier.
The result from taking N indexed domains with this function will be both a locally and a gloablly well distributed sub-pattern. This sub-pattern will of the highest quality due to being globally correlated with the sub-patterns of other samples.
If a mutliplier is adaptive (non-constant or unknown) then either the newDomainDistrib or newDomainChain functions should be used instead. These methods relax the constraint for a fixed multiplier, allowing for adaptive multilpiers in excahnge for a reduction in the quality
Calling code should use a constant key for any given domain while then incrementing the index value N times to increase the sampling rate by N for that given domain. The function will be called N times, once for each unique index. N must be passed as 'size' and remain constant.
- Parameters
-
[in] key Index key of next domain. [in] size Sample index multiplier. Must greater than zero. [in] index Sample index of next domain. Must be positive.
- Returns
- Child domain based on the current object state, key and size.
◆ newDomainDistrib()
|
inline |
Like newDomain, this function derives a mutated copy of the current sampler object. However, using a technique called splitting, this domain can have a higher sample rate based on an adaptive multiplier.
The result from taking N indexed domains with this function will be a locally well distributed sub-pattern. This sub-pattern will be of lower quality when combined with the sub-patterns of other samples. That is because the correlation between the sub-patterns globally is lost.
If a mutliplier is fixed (constant and known) then the newDomainSplit function will produce better quality sample points and should be used instead. This is because newDomainSplit will preserved correlation between sub-patterns from other samples.
Calling code should use a constant key for any given domain while then incrementing the index value N times to increase the sampling rate by N for that given domain. The function will be called N times, once for each unique index.
- Parameters
-
[in] key Index key of next domain. [in] index Sample index of next domain. Must be positive.
- Returns
- Child domain based on the current object state and key.
◆ drawRnd()
This can compute rnd values with up to 4 dimensions for the given domain. The operation does not change the state of the object, and for a single domain and index, the result of this function will always be the same. Output values are uniformly distributed integers within the range of [0, 2^32).
These values are of low quality but are fast to compute and have little risk of biasing an estimate. For higher quality samples, use the drawSample member functions above.
- Template Parameters
-
Size Number of dimensions to draw. Must be within [1, 4].
- Parameters
-
[out] rnd Output array to store rnd values.
Member Data Documentation
◆ maxIndexBitSize
◆ maxIndexSize
◆ spatialEncodeBitSizeX
◆ spatialEncodeBitSizeY
◆ patternId
| std::uint32_t oqmc::State64Bit::patternId |
◆ sampleId
| std::uint16_t oqmc::State64Bit::sampleId |
◆ pixelId
| std::uint16_t oqmc::State64Bit::pixelId |
The documentation for this struct was generated from the following file:
- oqmc/state.h
