Simple utilities API and related functions. More...

Classes
struct	oqmc::EncodeKey
	Key to encode pixel coordinates. More...

Functions
template<int XBits, int YBits, int ZBits>
std::uint16_t	oqmc::encodeBits16 (EncodeKey key)
	Encode a key value into 16 bits.

template<int XBits, int YBits, int ZBits>
EncodeKey	oqmc::decodeBits16 (std::uint16_t value)
	Decode a value back into a key.

float	oqmc::uintToFloat (std::uint32_t value)
	Convert an integer into a [0, 1) float.

constexpr std::uint32_t	oqmc::randomDigitScramble (std::uint32_t value, std::uint32_t hash)
	Random digit scramble an element in a sequence.

template<int Table, int Depth>
void	oqmc::shuffledScrambledLookup (std::uint32_t index, std::uint32_t hash, const std::uint32_t table[][Table], std::uint32_t sample[Depth])
	Compute a randomised value from a pre-computed table.

constexpr std::uint32_t	oqmc::laineKarrasPermutation (std::uint32_t value, std::uint32_t seed)
	Laine and Karras style permutation.

constexpr std::uint32_t	oqmc::reverseAndShuffle (std::uint32_t value, std::uint32_t seed)
	Reverse input bits and shuffle order.

constexpr std::uint32_t	oqmc::shuffle (std::uint32_t value, std::uint32_t seed)
	Compute a hash based owen scramble.

constexpr std::uint32_t	oqmc::uintToRange (std::uint32_t value, std::uint32_t range)
	Compute an unsigned integer within 0-bounded half-open range.

constexpr std::uint32_t	oqmc::uintToRange (std::uint32_t value, std::uint32_t begin, std::uint32_t end)
	Compute an unsigned integer within half-open range.

constexpr std::uint32_t	oqmc::reverseBits32 (std::uint32_t value)
	Reverse bits of an unsigned 32 bit integer.

constexpr std::uint16_t	oqmc::reverseBits16 (std::uint16_t value)
	Reverse bits of an unsigned 16 bit integer.

constexpr std::uint32_t	oqmc::rotateBits (std::uint32_t value, std::uint32_t distance)
	Rotate bits in an integer value.

constexpr std::uint32_t	oqmc::rotateBytes (std::uint32_t value, int distance)
	Rotate bytes in an integer value.

Detailed Description

This module captures an assortment of utility functions used in OpenQMC to build higher level components. However, they can also be used directly if needed and might be useful for other purposes, or when constructing new sampler types.

Utilities cover the following functions:

Integer to floating point conversion.
Encoding and decoding integer values.
Reversing and rotating integer bits.
Randomising and shuffling integers.
Mapping integers to a finite range.
Randomised table access.

Class Documentation

◆ oqmc::EncodeKey

struct oqmc::EncodeKey

This structure stores integer coordinate information for each axis of a 3 dimensional array.

Public Attributes
int	x
	x axis coordinate.

int	y
	y axis coordinate.

int	z
	z axis coordinate.

Member Data Documentation

◆ x

int oqmc::EncodeKey::x

◆ y

int oqmc::EncodeKey::y

◆ z

int oqmc::EncodeKey::z

Function Documentation

◆ encodeBits16()

template<int XBits, int YBits, int ZBits>

std::uint16_t oqmc::encodeBits16 ( EncodeKey key )

inline

#include <oqmc/encode.h>

Given a coordinate key and a given precision for each axis, encode the values into a single 16 bit integer value. This can be a lossy operation. The sum of all precisions must be equal to or less than 16 bits. Decode the values using the decodeBits16 function.

Template Parameters

XBits	Requested precision along the X axis.
YBits	Requested precision along the Y axis.
ZBits	Requested precision along the Z axis.

Parameters

[in] key Key of coordinates to encode.

Returns: Encoded 16 bit integer.

◆ decodeBits16()

template<int XBits, int YBits, int ZBits>

EncodeKey oqmc::decodeBits16 ( std::uint16_t value )

inline

#include <oqmc/encode.h>

Given a encoded 16 bit integer value and a given precision for each axis, decode the values into a coordinate key. This can be a lossy operation. The sum of all precisions must be equal to or less than 16 bits. Encode the values using the encodeBits16 function.

Template Parameters

XBits	Requested precision along the X axis.
YBits	Requested precision along the Y axis.
ZBits	Requested precision along the Z axis.

Parameters

[in] value Encoded 16 bit integer.

Returns: Key of encoded coordinates.

Here is the caller graph for this function:

◆ uintToFloat()

float oqmc::uintToFloat ( std::uint32_t value )

inline

#include <oqmc/float.h>

Given any representable 32 bit unsigned integer, scale the value into a [0, 1) floating point representation. Note that this operation is lossy and may not be reversible.

Parameters

[in] value Input integer value within the range [0, 2^32).

Returns: Floating point number within the range [0, 1).

Here is the caller graph for this function:

◆ randomDigitScramble()

constexpr std::uint32_t oqmc::randomDigitScramble	(	std::uint32_t	value,
		std::uint32_t	hash
	)

constexpr

#include <oqmc/lookup.h>

Given a value and a random number, efficiently randomise the value using the random digit scramble method from Kollig and Keller in 'Efficient Multidimensional Sampling'. The implementation just requires a single XOR operation, which although fast will not remove any pre-existing structure present in a sequence. The seed input must be constant for a given sequence.

Parameters

[in]	value	Sequence element.
[in]	hash	Random number.

Returns: Randomised element.

Here is the caller graph for this function:

◆ shuffledScrambledLookup()

template<int Table, int Depth>

void oqmc::shuffledScrambledLookup	(	std::uint32_t	index,
		std::uint32_t	hash,
		const std::uint32_t	table[][Table],
		std::uint32_t	sample[Depth]
	)

inline

#include <oqmc/lookup.h>

Given an index and a seed, compute an scrambled sequence value. The index will be shuffled in a manner that is progressive friendly. The value can be multi-dimensional. For a given sequence, the seed value must be constant. Table element size must be equal to or greater than 2^16. An index greater than 2^16 will reuse table samples.

Template Parameters

Table	Dimensional size of input table.
Depth	Dimensional space of output, up to 4 dimensions.

Parameters

[in]	index	Input index of sequence value.
[in]	hash	Hashed seed to randomise the sequence.
[in]	table	Pre-computed input table.
[out]	sample	Randomised sequence value.

Precondition: Table input must be pre-computed using an initialisation function.

◆ laineKarrasPermutation()

constexpr std::uint32_t oqmc::laineKarrasPermutation	(	std::uint32_t	value,
		std::uint32_t	seed
	)

constexpr

#include <oqmc/permute.h>

Given an unsigned integer number, permute the bits so that lower bits effect higher bits, but not the other way around. When combined with a reversal of bits before and after, this forms an efficient hash based owen scrambling scheme.

Parameters

[in]	value	Integer value to permute.
[in]	seed	Seed value to randomise the permutation.

Returns: Permuted output value.

Here is the caller graph for this function:

◆ reverseAndShuffle()

constexpr std::uint32_t oqmc::reverseAndShuffle	(	std::uint32_t	value,
		std::uint32_t	seed
	)

constexpr

#include <oqmc/permute.h>

Given an unsigned integer number, reverse the bit order and then perform a Laine and Karras style permutation.

Parameters

[in]	value	Integer value to reverse and permute.
[in]	seed	Seed value to randomise the permutation.

Returns: Reversed and permuted output value.

Here is the caller graph for this function:

◆ shuffle()

constexpr std::uint32_t oqmc::shuffle	(	std::uint32_t	value,
		std::uint32_t	seed
	)

constexpr

#include <oqmc/permute.h>

Given an unsigned integer, use a hash based technique to perform an owen scramble. This can be used to scramble a value, or to shuffle the order of a sequence in a progressive friendly manner.

Parameters

[in]	value	Integer value to be scrambled.
[in]	seed	Seed value to randomise the scramble.

Returns: Scrambled output value.

Here is the caller graph for this function:

◆ uintToRange() [1/2]

constexpr std::uint32_t oqmc::uintToRange	(	std::uint32_t	value,
		std::uint32_t	range
	)

constexpr

#include <oqmc/range.h>

Given a range defined using a single unsigned integer, map a full range 32 bit unsigned integer into range.

This function will avoid any division using a multiplication method that preserves the high order bits. This means that PRNGs with weak low order bits, as welll as QMC sequences, will both retain their good properties.

Due to these reasons, this function should be prefered over other naive methods such as a modulo operator. It does however still introduce a form of bias at large non power-of-two ranges. This could be resolved with a simple extension ivolving a rejection method. However such methods do not integrate well with the larger design, and so are not used as a practical compromise.

For further information see Section 4 in https://arxiv.org/abs/1805.10941 as well as https://www.pcg-random.org/posts/bounded-rands.html from PCG.

Parameters

[in]	value	Full ranged 32 bit unsigned integer.
[in]	range	Exclusive end of integer range. Greater than zero.

Returns: Output value remapped within integer range.

Here is the caller graph for this function:

◆ uintToRange() [2/2]

constexpr std::uint32_t oqmc::uintToRange	(	std::uint32_t	value,
		std::uint32_t	begin,
		std::uint32_t	end
	)

constexpr

#include <oqmc/range.h>

Given a range defined using two unsigned integers, map a full range 32 bit unsigned integer into range. This function is based upon the other uint to range function and has the same properties.

Parameters

[in]	value	Full ranged 32 bit unsigned integer.
[in]	begin	Inclusive beginning of integer range. Less than end.
[in]	end	Exclusive end of integer range. Greater than begin.

Returns: Output value remapped within integer range.

◆ reverseBits32()

constexpr std::uint32_t oqmc::reverseBits32 ( std::uint32_t value )

constexpr

#include <oqmc/reverse.h>

Given a 32 bit unsigned integer value, reverse the order of bits so that the most significant bits become the least significant, and vise versa.

Parameters

[in] value Integer value to reverse.

Returns: Reversed integer value.

Here is the caller graph for this function:

◆ reverseBits16()

constexpr std::uint16_t oqmc::reverseBits16 ( std::uint16_t value )

constexpr

#include <oqmc/reverse.h>

Given a 16 bit unsigned integer value, reverse the order of bits so that the most significant bits become the least significant, and vise versa.

Parameters

[in] value Integer value to reverse.

Returns: Reversed integer value.

Here is the caller graph for this function:

◆ rotateBits()

constexpr std::uint32_t oqmc::rotateBits	(	std::uint32_t	value,
		std::uint32_t	distance
	)

constexpr

#include <oqmc/rotate.h>

Offset bits in a 32 bit integer a given distance, while wrapping the bits so that the value remains the same every distance multiplier of 32.

Parameters

[in]	value	Initial integer of bits.
[in]	distance	Distance to offset.

Returns: Input value after bit rotation.

Here is the caller graph for this function:

◆ rotateBytes()

constexpr std::uint32_t oqmc::rotateBytes	(	std::uint32_t	value,
		int	distance
	)

constexpr

#include <oqmc/rotate.h>

Offset bytes in a 4 byte integer a given distance, while wrapping the bytes so that the value remains the same every distance multiplier of 4.

Parameters

[in]	value	Initial integer of bits.
[in]	distance	Distance to offset.

Returns: Input value after byte rotation.

Here is the caller graph for this function:

Classes

Functions

Detailed Description

Class Documentation

◆ oqmc::EncodeKey

Public Attributes

Member Data Documentation

◆ x

◆ y

◆ z

Function Documentation

◆ encodeBits16()

◆ decodeBits16()

◆ uintToFloat()

◆ randomDigitScramble()

◆ shuffledScrambledLookup()

◆ laineKarrasPermutation()

◆ reverseAndShuffle()

◆ shuffle()

◆ uintToRange() [1/2]

◆ uintToRange() [2/2]

◆ reverseBits32()

◆ reverseBits16()

◆ rotateBits()

◆ rotateBytes()