Typedefs | Functions
Sampler API

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 AtSamplerAiSampler (int nsamples, int ndim)
 Create a user sampler. More...
 
AI_API AtSamplerAiSamplerSeeded (int seed, int nsamples, int ndim)
 Create a user sampler with a unique seed. More...
 
AI_API AtSamplerIteratorAiSamplerIterator (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...
 

Detailed Description

Function Documentation

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.

Warning
Currently limited to two-dimensional point sets.
Parameters
nsamplesthe square root of the number of samples that will be taken
ndimnumber of dimensions of the point set
Returns
an AtSampler object, or NULL if 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.

Warning
Currently limited to two-dimensional point sets.
Deprecated:
In a future version, AiSamplerSeeded() may replace AiSampler() and will itself be removed from the API.
Parameters
seedthe unique seed for this sampler
nsamplesthe square root of the number of samples that will be taken
ndimnumber of dimensions of the point set
Returns
an AtSampler object, or NULL if 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).

Parameters
samplersampler to iterate over
sgcurrent shader globals
Returns
an iterator for the specified sampler, or NULL if the sampler is NULL
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.

Parameters
ititerator to get a sample from
samplea sample point in [0,1)^ndim
Returns
true while there are samples to iterate over
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.

Parameters
itsample iterator
Returns
number of samples taken from this 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.

Parameters
itsample iterator
Returns
one over number of samples taken
AI_API void AiSamplerDestroy ( AtSampler sampler)

Destroy a sampler object.

Call this in node_finish to release memory.

Parameters
samplersampler to destroy

© 2009-2013 Solid Angle SL · all rights reserved · www.solidangle.com