Typedefs | |
typedef struct AtSampler | AtSampler |
Opaque data type for a sampler. | |
typedef struct AtSamplerIterator | AtSamplerIterator |
Opaque data type for a sampler iterator. | |
Functions | |
AI_API AtSampler * | AiSampler (int nsamples, int ndim) |
Create a user sampler. More... | |
AI_API AtSampler * | AiSamplerSeeded (int seed, int nsamples, int ndim) |
Create a user sampler with a unique seed. More... | |
AI_API AtSamplerIterator * | AiSamplerIterator (const AtSampler *sampler, const AtShaderGlobals *sg) |
Prepare an iterator to loop over the specified sampler. More... | |
AI_API bool | AiSamplerGetSample (AtSamplerIterator *iterator, float *sample) |
Get the next sample in an iterator. More... | |
AI_API int | AiSamplerGetSampleCount (const AtSamplerIterator *iterator) |
Get the number of samples taken from this iterator. More... | |
AI_API float | AiSamplerGetSampleInvCount (const AtSamplerIterator *iterator) |
Get the inverse sample count. More... | |
AI_API void | AiSamplerDestroy (AtSampler *sampler) |
Destroy a sampler object. More... | |
AI_API AtSampler* AiSampler | ( | int | nsamples, |
int | ndim | ||
) |
Create a user sampler.
Creates a sequence of n-dimensional sampling points. Call this function to prepare the point set. Because this involves memory allocation and other potentially expensive operations, one should not create a sampler inside a shader's shader_evaluate
method. Instead, one should create the sampler inside node_initialize
and destroy it via AiSamplerDestroy() from inside node_finish
. In order to retrieve the sequence of samples from an AtSampler, one must create an iterator via AiSamplerIterator() prior to retrieving samples with AiSamplerGetSample(). The iterator must be created each time a sequence of samples is requested.
nsamples | the square root of the number of samples that will be taken |
ndim | number of dimensions of the point set |
nsamples
< 1 or ndim
!= 2 AI_API AtSampler* AiSamplerSeeded | ( | int | seed, |
int | nsamples, | ||
int | ndim | ||
) |
Create a user sampler with a unique seed.
Creates a sequence of n-dimensional sampling points. Call this function to prepare the point set. Because this involves memory allocation and other potentially expensive operations, one should not create a sampler inside a shader's shader_evaluate
method. Instead, one should create the sampler inside node_initialize
and destroy it via AiSamplerDestroy() from inside node_finish
. In order to retrieve the sequence of samples from an AtSampler, one must create an iterator via AiSamplerIterator() prior to retrieving samples with AiSamplerGetSample(). The iterator must be created each time a sequence of samples is requested.
It is suggested to use this seeded version insted of AiSampler() if you have multiple AtSampler instances in your shading network, as using different seeds will avoid correlation artifacts.
seed | the unique seed for this sampler |
nsamples | the square root of the number of samples that will be taken |
ndim | number of dimensions of the point set |
nsamples
< 1 or ndim
!= 2 AI_API AtSamplerIterator* AiSamplerIterator | ( | const AtSampler * | sampler, |
const AtShaderGlobals * | sg | ||
) |
Prepare an iterator to loop over the specified sampler.
Call once before your sampling loop. The iterator guarantees a unique sequence of sample points based on the pixel location, subpixel sample, ray-tree depth, etc. However, creating an AtSamplerIterator multiple times in the same rendering state (e.g. multiple times in the same shader_evaluate
method) will produce identical sampling patterns. The iterator will automatically switch to using a single sample if invoked "behind" another ray split (such as after a diffuse or glossy ray).
sampler | sampler to iterate over |
sg | current shader globals |
AI_API bool AiSamplerGetSample | ( | AtSamplerIterator * | it, |
float * | sample | ||
) |
Get the next sample in an iterator.
Call this in a loop to obtain new samples until it returns false.
it | iterator to get a sample from |
sample | a sample point in [0,1)^ndim |
AI_API int AiSamplerGetSampleCount | ( | const AtSamplerIterator * | it | ) |
Get the number of samples taken from this iterator.
Call this after the loop is done to see exactly how many samples were taken.
it | sample iterator |
AI_API float AiSamplerGetSampleInvCount | ( | const AtSamplerIterator * | it | ) |
Get the inverse sample count.
Call this after the loop is done to normalize your integral. This avoids calling AiSamplerGetSampleCount(), checking for 0 and inverting the result.
it | sample iterator |
AI_API void AiSamplerDestroy | ( | AtSampler * | sampler | ) |
Destroy a sampler object.
Call this in node_finish
to release memory.
sampler | sampler to destroy |