#include <Sampler.h>

Public Types
enum	EdgeHandling { eEdgeZero , eEdgeClamp , eEdgeFromIop }
	What to do when sampling off the edges of the input.

Public Member Functions
	Sampler (Iop iop, int x, int y, int r, int t, const ChannelSet &channels, Filter filter=nullptr, EdgeHandling edges=eEdgeFromIop, InterestRatchet *ir=nullptr, bool loadOndemand=true, bool needsThreadSafety=false)

	Sampler (Iop iop, const Box &box, const ChannelSet &channels, Filter filter=nullptr, EdgeHandling edges=eEdgeFromIop, InterestRatchet *ir=nullptr, bool loadOnDemand=true, bool needsThreadSafety=false)

Iop *	iop () const

const Format &	format () const

const ChannelSet &	channels () const

Filter *	filter () const
	Default filter to use if no filter is provided to sample methods.

void	setFilter (Filter *filter)
	Override the default filter provided to constructor, if any.

float	at (int x, int y, Channel z) const
	Sample a single pixel, with edge clipping but no filtering.

void	at (int x, int y, const ChannelSet &get, Pixel &out) const
	Same except samples get channels.

void	at (int x, int y, Pixel &out) const
	Same except samples out.channels.

void	sample (const Vector2 &center, const Vector2 &dU, const Vector2 &dV, Filter *filter, const ChannelSet &get, Pixel &out)

void	sample (const Vector2 &center, const Vector2 &dU, const Vector2 &dV, Filter *filter, Pixel &out)
	Same except samples out.channels.

void	sample (const Vector2 &center, const Vector2 &dU, const Vector2 &dV, const ChannelSet &get, Pixel &out)
	Same except the filter used is the pre-assigned one.

void	sample (const Vector2 &center, const Vector2 &dU, const Vector2 &dV, Pixel &out)
	Same except the filter used is the pre-assigned one and samples out.channels.

void	sample (float cx, float cy, float W, float H, Filter *filter, const ChannelSet &get, Pixel &out)
	Sample a rectangular area. Note that cx,cy is the center of the rectangle, not the corner.

void	sample (float cx, float cy, float W, float H, Filter *filter, Pixel &out)
	Same except samples out.channels.

void	sample (float cx, float cy, float W, float H, const ChannelSet &get, Pixel &out)
	Same except the filter used is the pre-assigned one.

void	sample (float cx, float cy, float W, float H, Pixel &out)
	Same except the filter used is the pre-assigned one and samples out.channels.

void	sample (const SamplePosition &samplePosition, Pixel &out)

void	sampleTextureUV (const fdk::Vec3f &UV, const fdk::Vec3f &dU, const fdk::Vec3f &dV, Filter *filter, const ChannelSet &get, Pixel &out) const

float	sampleTextureUV (const fdk::Vec3f &UV, const fdk::Vec3f &dU, const fdk::Vec3f &dV, Filter *filter, Channel chan) const

Detailed Description

A class for sampling pixels from an image. It works like a Tile, but with sample methods. This is generally more efficient than making many calls to Iop::sample although it may render more than you need from the input if you don't sample all of the requested box.

Important Note - this class is not thread safe and should not be shared between multiple engine threads, as the underlying tile cache may crash. Each engine thread should have its own Sampler copy, but if sharing the Sampler cannot be avoided then it's better to use Iop::sample() which is slower but thread safe.

Constructor & Destructor Documentation

◆ Sampler()

DD::Image::Sampler::Sampler	(	Iop *	iop,
		int	x,
		int	y,
		int	r,
		int	t,
		const ChannelSet &	channels,
		Filter *	filter = `nullptr`,
		EdgeHandling	edges = `eEdgeFromIop`,
		InterestRatchet *	ir = `nullptr`,
		bool	loadOndemand = `true`,
		bool	needsThreadSafety = `false`
	)

Construct a Sampler.

If filter isn't specified at construction time then it must be supplied as an argument to any later calls to sample() instead. needsThreadSafety should be set to true if the sampler needs to support concurrent access from multiple threads. Note that this comes with a small performance overhead so should only be set if it is actually needed.

Member Function Documentation

◆ sample() [1/2]

void DD::Image::Sampler::sample	(	const Vector2 &	center,
		const Vector2 &	dU,
		const Vector2 &	dV,
		Filter *	filter,
		const ChannelSet &	get,
		Pixel &	out
	)

Sample a parallelogram. It is centered on center and the length of the two axis are given by dU and dV. The channels requested by get are put into out.

The default implementation turns the parallelogram into a rectangle of the same area and calls the rectangle sample() function.

References filter(), and sample().

Referenced by sample().

◆ sample() [2/2]

void DD::Image::Sampler::sample	(	const SamplePosition &	samplePosition,
		Pixel &	out
	)

Specialized version for two-pass sampling and uses the filter that was previously specified when the sampler was constructed.

◆ sampleTextureUV() [1/2]

void DD::Image::Sampler::sampleTextureUV	(	const fdk::Vec3f &	UV,
		const fdk::Vec3f &	dU,
		const fdk::Vec3f &	dV,
		Filter *	filter,
		const ChannelSet &	get,
		Pixel &	out
	)		const

Specialized version for texture sampling where UV is a texture coordinate between 0..1 to be fitted into the Format, and dU and dV are its partial derivatives. ChannelSet get is provided separately so that a subset of out can be filled without affecting its assigned ChannelSet, which is ignored.

References filter().

Referenced by slr::SlrShadingContext::sample().

◆ sampleTextureUV() [2/2]

float DD::Image::Sampler::sampleTextureUV	(	const fdk::Vec3f &	UV,
		const fdk::Vec3f &	dU,
		const fdk::Vec3f &	dV,
		Filter *	filter,
		Channel	chan
	)		const

Same but samples a single channel at a time. This has a slightly higher per-Channel setup overhead cost but avoids the need to dynamically create Pixels in high performance code only needing to filter a single channel. Avoid calling this from inside a ChannelSet/ChannelPack loop.