A generic, two-dimensional sampler that is sometimes useful when writing shaders. More...
Data Structures | |
| struct | AtSampler |
| Opaque data type for a sampler. More... | |
| struct | AtSamplerIterator |
| Opaque data type for a sampler iterator. More... | |
Functions | |
| AI_API AtSampler * | AiSampler (uint32_t 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 AI_DEVICE bool | AiSamplerGetSample (AtSamplerIterator *iterator, float *sample) |
| Get the next sample in an iterator. More... | |
| AI_API AI_PURE int | AiSamplerGetSampleCount (const AtSamplerIterator *iterator) |
| Get the number of samples taken from this iterator. More... | |
| AI_API AI_PURE float | AiSamplerGetSampleInvCount (const AtSamplerIterator *iterator) |
| Get the inverse sample count. More... | |
| AI_API void | AiSamplerDestroy (AtSampler *sampler) |
| Destroy a sampler object. More... | |
A generic, two-dimensional sampler that is sometimes useful when writing shaders.
| AI_API AtSampler * AiSampler | ( | uint32_t | 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.
If you have multiple AtSampler instances in your shading network, you must use different seeds to 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 | 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 AI_DEVICE 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 AI_PURE 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 AI_PURE 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 |