#include <ImFusion/GL/ExplicitMask.h>

An ExplicitMask holds an individual mask value for every pixel. More...

Inheritance diagram for ExplicitMask:

Detailed Description

An ExplicitMask holds an individual mask value for every pixel.

Internally, it uses a SharedImage as storage for the pixel buffer and the returned mask values are retrieved directly from there. The internal mask image will always be of PixelType::UByte and single channel.

Public Member Functions
	ExplicitMask (int width, int height, int slices, uint8_t initial=0)
	Creates a new ExplicitMask of the given size and initialized with the given value.

	ExplicitMask (const vec3i &dimensions, uint8_t initial=0)

	ExplicitMask (std::shared_ptr< TypedImage< uint8_t > > maskImage)
	Creates a new ExplicitMask using the provided mask image.

	ExplicitMask (std::shared_ptr< GlImage > maskImage)
	Creates a new ExplicitMask using the provided mask image.

SharedImage *	maskImage ()
	Returns the internal image holding the mask values.

const SharedImage *	maskImage () const

TypedImage< uint8_t > *	maskImageTyped ()
	Convenience method that retrieves the MemImage from maskImage() and cast it to TypedImage<uint8_t>.

const TypedImage< uint8_t > *	maskImageTyped () const

uint8_t	maskValue (const vec3i &coord, const vec4f &color) const override
	Returns 0 if the given pixel is outside the mask (i.e.

bool	isCompatible (const SharedImage *image) const override
	Returns `true` if the mask can be used with the given image or `false` otherwise.

bool	requiresPixelValue () const override
	Returns true if the maskValue() rely on the pixel value.

std::unique_ptr< TypedImage< uint8_t > >	createExplicitMask (const SharedImage &image, CreateOption createOption=CreateOption::DeepCopy) const override
	Creates an explicit mask representation of this mask for a given image.

std::unique_ptr< GlImage >	createExplicitMaskGl (const GlImage &inputImage, bool normalized=false) override
	Creates an explicit mask representation of this mask when applied to the given image.

int	setIncludeArguments (GL::Program &p, const std::string &prefix="mask") const override
	Called by users of GlMask in order to correctly setup the mask shader.

GlMask *	glMask () override
	Returns the OpenGL-based implementation of the mask interface if available.

void	configure (const Properties *) override
	Configure this object instance by de-serializing the given Properties.

void	configuration (Properties *) const override
	Serialize the current object configuration into the given Properties object.

uint8_t	maskValue (const vec3i &coord, float value=-1.0f) const
	Convenience overload that calls `maskValue(coord, vec4f(value, value, value, 1.0f))`.

Public Member Functions inherited from Mask
uint8_t	maskValue (const vec3i &coord, float value=-1.0f) const
	Convenience overload that calls `maskValue(coord, vec4f(value, value, value, 1.0f))`.

virtual std::unique_ptr< Mask >	resizedMask (const SharedImage &original, const Image &target) const
	Creates a copy of the current mask, resized to the dimensions of the target image.

Public Member Functions inherited from Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.

void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().

void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.

	Configurable (const Configurable &rhs)

	Configurable (Configurable &&rhs) noexcept

Configurable &	operator= (const Configurable &)

Configurable &	operator= (Configurable &&) noexcept

Public Member Functions inherited from GlMask
	GlMask (const std::string &includePath)
	Instantiates a new GL::AbstractInclude using `IMAGE_MASK` as defineName and the given path the to retrieve the GLSL source code from.

Public Member Functions inherited from AbstractInclude
	AbstractInclude (const std::string &defineName, const std::string &includePath)
	Creates a AbstractInclude for the given define and with the corresponding GLSL file at includePath.

const std::string &	defineName () const
	Returns the name of define used by this include.

const std::string &	includePath () const
	Returns the path to the included shader file.

virtual std::function< std::string(const std::string &)>	includeCodeSubstitution () const
	Optionally the abstract include can provide a function to change the shader code.

virtual std::vector< AbstractInclude * >	dependentIncludes () const
	Returns a list of dependent abstract includes that need to be included as well.

virtual Fingerprint	fingerprint () const
	Provides a finger print of the include.

Public Member Functions inherited from MultiIncludable< GlMask >
std::shared_ptr< MultiIncludeType >	createMultiInclude (const std::string &replacementToken)
	Instantiates a new AbstractInclude instance where all occurrences of baseToken provided during construction are replaces with replacementToken according to the specified replacementScheme.

virtual int	setIncludeArguments (Program &prog, IncludeArgumentsTypes... includeArgs, const std::string &token) const=0
	Interface that multi includes should use to configure the shader include (such as setting uniforms, binding textures, etc).

Static Public Member Functions
static std::unique_ptr< ExplicitMask >	convert (std::unique_ptr< SharedImage > maskImage)
	Creates an ExplicitMask from the given SharedImage and takes ownership of it.

static std::unique_ptr< ExplicitMask >	convert (const MemImage &maskImage)
	Creates an ExplicitMask by copying the values of the given MemImage.

static std::unique_ptr< ExplicitMask >	convert (const GlImage &maskImage)
	Creates an ExplicitMask by copying the values of the given GlImage.

Static Public Member Functions inherited from GlMask
static std::string	defineName ()
	Returns "IMAGE_MASK".

static std::string	defineSuffix ()
	Returns "MASK".

static std::string	multiIncludeDefine (const std::string &replacementToken)
	Returns `"IMAGE_" + toUpper(replacementToken)`

Additional Inherited Members
Public Types inherited from Mask
enum class	CreateOption { DeepCopy , ShallowCopyIfPossible }
	Enumeration of available behavior for createExplicitMask() More...

Public Types inherited from MultiIncludable< GlMask >
using	MultiIncludeType
	Alias for type of a multi-include instance of the original include.

Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Protected Member Functions inherited from MultiIncludable< GlMask >
	MultiIncludable (GlMask *crtpInstance, const std::string &baseToken, Flags< ShaderTextReplacement > replacementScheme)
	Instantiate and configure the MultiIncludable interface.

Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Constructor & Destructor Documentation

◆ ExplicitMask() [1/2]

ExplicitMask ( std::shared_ptr< TypedImage< uint8_t > > maskImage )

explicit

Creates a new ExplicitMask using the provided mask image.

Parameters

maskImage Mask image to consume, must be single-channel.

◆ ExplicitMask() [2/2]

ExplicitMask ( std::shared_ptr< GlImage > maskImage )

explicit

Creates a new ExplicitMask using the provided mask image.

Parameters

maskImage Mask image to consume, must be of PixelType::UByte and single-channel.

Member Function Documentation

◆ convert() [1/3]

static std::unique_ptr< ExplicitMask > convert ( std::unique_ptr< SharedImage > maskImage )

static

Creates an ExplicitMask from the given SharedImage and takes ownership of it.

If the input image is not of PixelType::UByte or has more than one channel, it will be converted internally.

◆ convert() [2/3]

static std::unique_ptr< ExplicitMask > convert ( const MemImage & maskImage )

static

Creates an ExplicitMask by copying the values of the given MemImage.

If the input image is not of PixelType::UByte or has more than one channel, it will be converted internally.

◆ convert() [3/3]

static std::unique_ptr< ExplicitMask > convert ( const GlImage & maskImage )

static

Creates an ExplicitMask by copying the values of the given GlImage.

If the input image is not of PixelType::UByte or has more than one channel, it will be converted internally.

◆ maskImage()

SharedImage * maskImage ( )

Returns the internal image holding the mask values.

This image will always be of type UBYTE.

◆ maskValue()

uint8_t maskValue	(	const vec3i &	coord,
		const vec4f &	color ) const

overridevirtual

Returns 0 if the given pixel is outside the mask (i.e.

invisible/to be ignored) or a non-zero value if it is inside the mask (i.e. visible/to be considered).

This function takes both the pixel coordinate and pixel value as input. Concrete implementations of the Mask interface are free to use only either input for their decision if it makes sense. Also, it is up to the implementation whether it supports multi-channel images or not. Subclasses only supporting grayscale images should only use the first channel.

Parameters

coord	Pixel coordinate to be tested against the mask, can be outside of the image.
color	Pixel value (not normalized) to be tested against the mask. This parameter is only needed if requiresPixelValue() returns `true`, which can allow for optimizations where pixel lookup is expensive.

Implements Mask.

◆ isCompatible()

bool isCompatible ( const SharedImage * image ) const

overridevirtual

Returns true if the mask can be used with the given image or false otherwise.

Implements Mask.

◆ requiresPixelValue()

bool requiresPixelValue ( ) const

inlineoverridevirtual

Returns true if the maskValue() rely on the pixel value.

If this method returns false, the maskValue() method can be safely used with only the coordinate. This is useful to avoid an otherwise unnecessary and expensive pixel lookup.

Implements Mask.

◆ createExplicitMask()

std::unique_ptr< TypedImage< uint8_t > > createExplicitMask	(	const SharedImage &	image,
		CreateOption	createOption = CreateOption::DeepCopy ) const

overridevirtual

Creates an explicit mask representation of this mask for a given image.

Parameters

image	Reference image for which to create the mask, must be compatible.
createOption	Subclasses that already store an explicit representation of the mask can optionally return a non-owning TypedImage (shallow copy). If the returned TypedImage will outlive the source Mask, make sure to use CreateOption::DeepCopy.

Reimplemented from Mask.

◆ createExplicitMaskGl()

std::unique_ptr< GlImage > createExplicitMaskGl	(	const GlImage &	inputImage,
		bool	normalized = false )

overridevirtual

Creates an explicit mask representation of this mask when applied to the given image.

Parameters

inputImage	Image to which the mask should be applied for each pixel in order to generate the explicit mask image. Must be compatible with the mask.
normalized	If the this parameter is `true` the resulting binary mask value will be created as CPU uint8_t values 0 and 255 (corresponding to 0 and 1 on the GPU), instead of 0 and 1 (0 and 1/255 on the GPU).

Reimplemented from GlMask.

◆ setIncludeArguments()

int setIncludeArguments	(	GL::Program &	p,
		const std::string &	prefix = "mask" ) const

overridevirtual

Called by users of GlMask in order to correctly setup the mask shader.

Subclasses should implement this function so that it correctly sets all needed uniforms and input textures to be used by the OpenGL shader instance. Make sure to use the given prefix argument instead of a hardcoded "mask" when defining uniform names to support multi-includes where the prefixes have been replaced with unique alternatives. Example:

p.setArgument(prefix + "UseRange", m_useRange);

Implements GlMask.

◆ glMask()

GlMask * glMask ( )

overridevirtual

Returns the OpenGL-based implementation of the mask interface if available.

This function may return nullptr if this is not implemented (default).

Reimplemented from Mask.

◆ configure()

void configure ( const Properties * p )

inlineoverridevirtual

Configure this object instance by de-serializing the given Properties.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configuration() for the inverse functionality

Reimplemented from Configurable.

◆ configuration()

void configuration ( Properties * p ) const

inlineoverridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configure() for the inverse functionality

Reimplemented from Configurable.

The documentation for this class was generated from the following file:

ImFusion/GL/ExplicitMask.h

Detailed Description

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Constructor & Destructor Documentation

◆ ExplicitMask() [1/2]

◆ ExplicitMask() [2/2]

Member Function Documentation

◆ convert() [1/3]

◆ convert() [2/3]

◆ convert() [3/3]

◆ maskImage()

◆ maskValue()

◆ isCompatible()

◆ requiresPixelValue()

◆ createExplicitMask()

◆ createExplicitMaskGl()

◆ setIncludeArguments()

◆ glMask()

◆ configure()

◆ configuration()