TextureMapper

touchgfx/widgets/TextureMapper.hpp

The TextureMapper widget displays a transformed image. It can be used to generate effects where an image should be rotated in two or three dimensions.

The image can be freely scaled and rotated in three dimensions. The scaling and rotation is done around the adjustable origin. A virtual camera is applied to the rendered image yielding a perspective impression. The amount of perspective impression can be adjusted. The transformed image is clipped according to the dimensions of the TextureMapper widget. In order to make the image fully visible the TextureMapper should be large enough to accommodate the transformed image, which may be larger than the raw image.

See: Widget

Note:

The drawing of this widget is not trivial and typically has a significant performance penalty. The number of pixels drawn, the presence of global alpha or per pixel alpha inflicts the computation and should be considered.
This widget does not support 1 bit per pixel color depth.

Inherits from: Image, Widget, Drawable

Inherited by: AnimationTextureMapper

Public Types


enum	RenderingAlgorithm { NEAREST_NEIGHBOR, BILINEAR_INTERPOLATION }
	Rendering algorithm to use when scaling the bitmap.

Public Functions


virtual void	draw(const Rect & invalidatedArea) const
	Draw this drawable.

virtual float	getBitmapPositionX() const
	Gets bitmap position x coordinate.

virtual float	getBitmapPositionY() const
	Gets bitmap position y coordinate.

virtual float	getCameraDistance() const
	Gets camera distance.

virtual float	getCameraX() const
	Gets camera x coordinate.

virtual float	getCameraY() const
	Gets camera y coordinate.

virtual float	getOrigoX() const
	Gets transformation origo x coordinate.

virtual float	getOrigoY() const
	Gets transformation origo y coordinate.

virtual float	getOrigoZ() const
	Gets transformation origo z coordinate.

virtual RenderingAlgorithm	getRenderingAlgorithm() const
	Gets the algorithm used when rendering.

virtual float	getScale() const
	Gets the scale of the image.

virtual Rect	getSolidRect() const
	Get (the largest possible) rectangle that is guaranteed to be solid (opaque).

virtual float	getX0() const
	Get the x coordinate of the top left corner of the transformed bitmap.

virtual float	getX1() const
	Get the x coordinate of the top right corner of the transformed bitmap.

virtual float	getX2() const
	Get the x coordinate of the bottom right of the transformed bitmap.

virtual float	getX3() const
	Get the x coordinate of the bottom left corner of the transformed bitmap.

virtual float	getXAngle() const
	Get the x angle in radians.

virtual float	getY0() const
	Get the y coordinate of the top left corner of the transformed bitmap.

virtual float	getY1() const
	Get the y coordinate of the top right corner of the transformed bitmap.

virtual float	getY2() const
	Get the y coordinate of the bottom right corner of the transformed bitmap.

virtual float	getY3() const
	Get the y coordinate of the bottom left corner of the transformed bitmap.

virtual float	getYAngle() const
	Get the y angle in radians.

virtual float	getZ0() const
	Get the z coordinate of the top left corner of the transformed bitmap.

virtual float	getZ1() const
	Get the z coordinate of the top right corner of the transformed bitmap.

virtual float	getZ2() const
	Get the z coordinate of the bottom right corner of the transformed bitmap.

virtual float	getZ3() const
	Get the z coordinate of the bottom left corner of the transformed bitmap.

virtual float	getZAngle() const
	Get the z angle in radians.

virtual void	invalidateContent() const
	Tell the framework that the contents of the Drawable needs to be redrawn.

virtual void	setAngles(float newXAngle, float newYAngle, float newZAngle)
	Sets the angles in radians of the image.

virtual void	setBitmap(const Bitmap & bmp)
	Sets the bitmap for this TextureMapper and updates the width and height of this widget to match those of the Bitmap.

virtual void	setBitmapPosition(float x, float y)
	Sets the position of the bitmap within the TextureMapper.

virtual void	setBitmapPosition(int x, int y)
	Sets the position of the bitmap within the TextureMapper.

virtual void	setCamera(float x, float y)
	Sets the camera coordinate.

virtual void	setCameraDistance(float d)
	Sets camera distance.

virtual void	setOrigo(float x, float y)
	Sets the transformation origo (center) in two dimensions.

virtual void	setOrigo(float x, float y, float z)
	Sets the transformation origo (center).

virtual void	setRenderingAlgorithm(RenderingAlgorithm algorithm)
	Sets the render algorithm to be used.

virtual void	setScale(float newScale)
	Sets the scale of the image.

virtual void	setXAngle(float newXAngle)
	Sets the x angle in radians.

virtual void	setYAngle(float newYAngle)
	Sets the y angle in radians.

virtual void	setZAngle(float newZAngle)
	Sets the z angle in radians.

	TextureMapper(const Bitmap & bmp =Bitmap())
	Constructs a new TextureMapper with a default alpha value of 255 (solid) and a default Bitmap (undefined) if none is specified.

	TOUCHGFX_DEPRECATED("Please use invalidateContent() instead." , void invalidateBoundingRect() const )
	Invalidate the bounding rectangle of the transformed bitmap.

virtual void	updateAngles(float newXAngle, float newYAngle, float newZAngle)
	Updates the angles in radians of the image.

virtual void	updateScale(float newScale)
	Updates the scale of the image.

virtual void	updateXAngle(float newXAngle)
	Updates the x angle in radians.

virtual void	updateYAngle(float newYAngle)
	Updates the y angle in radians.

virtual void	updateZAngle(float newZAngle)
	Updates the z angle in radians.

Protected Functions


void	applyTransformation()
	Transform the bitmap using the supplied origo, scale, rotation and camera.

void	drawQuad(const Rect & invalidatedArea, uint16_t fb, const float triangleXs, const float triangleYs, const float triangleZs, const float triangleUs, const float triangleVs) const
	The TextureMapper will draw the transformed bitmap by drawing one transformed quad.

Rect	getBoundingRect() const
	Gets bounding rectangle of the transformed bitmap.

RenderingVariant	lookupRenderVariant() const
	Returns the rendering variant based on the bitmap format, alpha value and rendering algorithm.

Protected Attributes


float	cameraDistance
	The camera distance.

RenderingAlgorithm	currentRenderingAlgorithm
	The current rendering algorithm.

float	imageX0
	The coordinate for the image points.

float	imageX1
	The coordinate for the image points.

float	imageX2
	The coordinate for the image points.

float	imageX3
	The coordinate for the image points.

float	imageY0
	The coordinate for the image points.

float	imageY1
	The coordinate for the image points.

float	imageY2
	The coordinate for the image points.

float	imageY3
	The coordinate for the image points.

float	imageZ0
	The coordinate for the image points.

float	imageZ1
	The coordinate for the image points.

float	imageZ2
	The coordinate for the image points.

float	imageZ3
	The coordinate for the image points.

float	scale
	The scale.

uint16_t	subDivisionSize
	The size of the affine sub divisions.

float	xAngle
	The angle x in radians.

float	xBitmapPosition
	The bitmap position x.

float	xCamera
	The camera x coordinate.

float	xOrigo
	The origo x coordinate.

float	yAngle
	The angle y in radians.

float	yBitmapPosition
	The bitmap position y.

float	yCamera
	The camera y coordinate.

float	yOrigo
	The origo y coordinate.

float	zAngle
	The angle z in radians.

float	zOrigo
	The origo z coordinate.

const int	MINIMAL_CAMERA_DISTANCE
	The minimal camera distance.

Additional inherited members

Public Functions inherited from Image


uint8_t	getAlpha() const
	Gets the current alpha value of the widget.

Bitmap	getBitmap() const
	Gets the Bitmap currently assigned to the Image widget.

BitmapId	getBitmapId() const
	Gets the BitmapId currently assigned to the Image widget.

	Image(const Bitmap & bmp =Bitmap())
	Constructs a new Image with a default alpha value of 255 (solid) and a default Bitmap (undefined) if none is specified.

void	setAlpha(uint8_t newAlpha)
	Sets the opacity (alpha value).

Protected Attributes inherited from Image


uint8_t	alpha
	The Alpha for this image.

Bitmap	bitmap
	The Bitmap to display.


virtual void	getLastChild(int16_t , int16_t , Drawable ** last)
	Since a Widget is only one Drawable, Widget::getLastChild simply yields itself as result, but only if the Widget isVisible and isTouchable.

Public Functions inherited from Drawable


void	center()
	Centers the Drawable inside its parent.

void	centerX()
	Center the Drawable horizontally inside its parent.

void	centerY()
	Center the Drawable vertically inside its parent.

virtual void	childGeometryChanged()
	This function can be called on parent nodes to signal that the size or position of one or more of its children has changed.

	Drawable()
	Initializes a new instance of the Drawable class.

void	drawToDynamicBitmap(BitmapId id)
	Render the Drawable object into a dynamic bitmap.

void	expand(int margin =0)
	Expands the Drawable to have the same size as its parent with a given margin around the edge.

Rect	getAbsoluteRect() const
	Helper function for obtaining the rectangle this Drawable covers, expressed in absolute coordinates.

virtual Drawable *	getFirstChild()
	Function for obtaining the first child of this drawable if any.

int16_t	getHeight() const
	Gets the height of this Drawable.

virtual void	getLastChild(int16_t x, int16_t y, Drawable ** last) =0
	Function for obtaining the the last child of this drawable that intersects with the specified point.

Drawable *	getNextSibling()
	Gets the next sibling node.

Drawable *	getParent() const
	Returns the parent node.

const Rect &	getRect() const
	Gets the rectangle this Drawable covers, in coordinates relative to its parent.

virtual Rect	getSolidRectAbsolute()
	Helper function for obtaining the largest solid rect (as implemented by getSolidRect()) expressed in absolute coordinates.

virtual void	getVisibleRect(Rect & rect) const
	Function for finding the visible part of this drawable.

int16_t	getWidth() const
	Gets the width of this Drawable.

int16_t	getX() const
	Gets the x coordinate of this Drawable, relative to its parent.

int16_t	getY() const
	Gets the y coordinate of this Drawable, relative to its parent.

virtual void	handleClickEvent(const ClickEvent & event)
	Defines the event handler interface for ClickEvents.

virtual void	handleDragEvent(const DragEvent & event)
	Defines the event handler interface for DragEvents.

virtual void	handleGestureEvent(const GestureEvent & event)
	Defines the event handler interface for GestureEvents.

virtual void	handleTickEvent()
	Called periodically by the framework if the Drawable instance has subscribed to timer ticks.

virtual void	invalidate() const
	Tell the framework that this entire Drawable needs to be redrawn.

virtual void	invalidateRect(Rect & invalidatedArea) const
	Request that a region of this drawable is redrawn.

bool	isTouchable() const
	Gets whether this Drawable receives touch events or not.

bool	isVisible() const
	Gets whether this Drawable is visible.

virtual void	moveRelative(int16_t x, int16_t y)
	Moves the drawable.

virtual void	moveTo(int16_t x, int16_t y)
	Moves the drawable.

virtual void	setHeight(int16_t height)
	Sets the height of this drawable.

void	setPosition(const Drawable & drawable)
	Sets the position of the Drawable to the same as the given Drawable.

void	setPosition(int16_t x, int16_t y, int16_t width, int16_t height)
	Sets the size and position of this Drawable, relative to its parent.

void	setTouchable(bool touch)
	Controls whether this Drawable receives touch events or not.

void	setVisible(bool vis)
	Controls whether this Drawable should be visible.

virtual void	setWidth(int16_t width)
	Sets the width of this drawable.

void	setWidthHeight(const Bitmap & bitmap)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

void	setWidthHeight(const Drawable & drawable)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

void	setWidthHeight(const Rect & other)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

void	setWidthHeight(int16_t width, int16_t height)
	Sets the dimensions (width and height) of the Drawable without changing the x and y coordinates).

virtual void	setX(int16_t x)
	Sets the x coordinate of this Drawable, relative to its parent.

void	setXY(const Drawable & drawable)
	Sets the x and y coordinates of this Drawable.

void	setXY(int16_t x, int16_t y)
	Sets the x and y coordinates of this Drawable, relative to its parent.

virtual void	setY(int16_t y)
	Sets the y coordinate of this Drawable, relative to its parent.

virtual void	translateRectToAbsolute(Rect & r) const
	Helper function for converting a region of this Drawable to absolute coordinates.

virtual	~Drawable()
	Finalizes an instance of the Drawable class.

Protected Attributes inherited from Drawable


Drawable *	nextSibling
	Pointer to the next Drawable.

Drawable *	parent
	Pointer to this drawable's parent.

Rect	rect
	The coordinates of this Drawable, relative to its parent.

bool	touchable
	True if this drawable should receive touch events.

bool	visible
	True if this drawable should be drawn.

Public Types Documentation

RenderingAlgorithm

Rendering algorithm to use when scaling the bitmap.


NEAREST_NEIGHBOR	Fast but not a very good image quality. Good for fast animations.
BILINEAR_INTERPOLATION	Slower but better image quality. Good for static representation of a scaled image.

Public Functions Documentation

draw

Draw this drawable.

It is a requirement that the draw implementation does not draw outside the region specified by invalidatedArea.

Parameters:


invalidatedArea	The sub-region of this drawable that needs to be redrawn, expressed in coordinates relative to its parent (e.g. for a complete redraw, invalidatedArea will be (0, 0, width, height).

Reimplements: touchgfx::Image::draw

getBitmapPositionX


virtual float getBitmapPositionX	(			)	const

Gets bitmap position x coordinate.

Returns:

The bitmap position x coordinate.

See also:

setBitmapPosition

getBitmapPositionY


virtual float getBitmapPositionY	(			)	const

Gets bitmap position y coordinate.

Returns:

The bitmap position y coordinate.

See also:

setBitmapPosition

getCameraDistance


virtual float getCameraDistance	(			)	const

Gets camera distance.

Returns:

The camera distance.

See also:

setCameraDistance

getCameraX


virtual float getCameraX	(			)	const

Gets camera x coordinate.

Returns:

The camera x coordinate.

See also:

setCamera

getCameraY


virtual float getCameraY	(			)	const

Gets camera y coordinate.

Returns:

The camera y coordinate.

See also:

setCamera

getOrigoX


virtual float getOrigoX	(			)	const

Gets transformation origo x coordinate.

Returns:

The transformation origo x coordinate.

See also:

setOrigo

getOrigoY


virtual float getOrigoY	(			)	const

Gets transformation origo y coordinate.

Returns:

The transformation origo y coordinate.

See also:

setOrigo

getOrigoZ


virtual float getOrigoZ	(			)	const

Gets transformation origo z coordinate.

Returns:

The transformation origo z coordinate.

See also:

setOrigo

getRenderingAlgorithm


virtual RenderingAlgorithm getRenderingAlgorithm	(			)	const

Gets the algorithm used when rendering.

Returns:

The algorithm used when rendering.

getScale


virtual float getScale	(			)	const

Gets the scale of the image.

Returns:

The scale.

See also:

setScale

getSolidRect


virtual Rect getSolidRect	(			)	const

Get (the largest possible) rectangle that is guaranteed to be solid (opaque).

This information is important, as any Drawable underneath the solid area does not need to be drawn.

Returns:

The solid rectangle part of the Drawable.

Note

The rectangle returned must be relative to upper left corner of the Drawable, meaning that a completely solid widget should return the full size Rect(0, 0, getWidth(), getHeight()). If no area can be guaranteed to be solid, an empty Rect must be returned. Failing to return the correct rectangle may result in errors on the display.

Reimplements: touchgfx::Image::getSolidRect

getX0


virtual float getX0	(			)	const

Get the x coordinate of the top left corner of the transformed bitmap.

Returns:

The X0 coordinate.

getX1


virtual float getX1	(			)	const

Get the x coordinate of the top right corner of the transformed bitmap.

Returns:

The X1 coordinate.

getX2


virtual float getX2	(			)	const

Get the x coordinate of the bottom right of the transformed bitmap.

Returns:

The X2 coordinate.

getX3


virtual float getX3	(			)	const

Get the x coordinate of the bottom left corner of the transformed bitmap.

Returns:

The X3 coordinate.

getXAngle


virtual float getXAngle	(			)	const

Get the x angle in radians.

Returns:

The x angle.

Note

Angles are given in radians, so a full circle is 2*PI.

See also:

updateXAngle

getY0


virtual float getY0	(			)	const

Get the y coordinate of the top left corner of the transformed bitmap.

Returns:

The Y0 coordinate.

getY1


virtual float getY1	(			)	const

Get the y coordinate of the top right corner of the transformed bitmap.

Returns:

The Y1 coordinate.

getY2


virtual float getY2	(			)	const

Get the y coordinate of the bottom right corner of the transformed bitmap.

Returns:

The Y2 coordinate.

getY3


virtual float getY3	(			)	const

Get the y coordinate of the bottom left corner of the transformed bitmap.

Returns:

The Y3 coordinate.

getYAngle


virtual float getYAngle	(			)	const

Get the y angle in radians.

Returns:

The y angle.

Note

Angles are given in radians, so a full circle is 2*PI.

See also:

updateYAngle

getZ0


virtual float getZ0	(			)	const

Get the z coordinate of the top left corner of the transformed bitmap.

Returns:

The Z0 coordinate.

getZ1


virtual float getZ1	(			)	const

Get the z coordinate of the top right corner of the transformed bitmap.

Returns:

The Z1 coordinate.

getZ2


virtual float getZ2	(			)	const

Get the z coordinate of the bottom right corner of the transformed bitmap.

Returns:

The Z2 coordinate.

getZ3


virtual float getZ3	(			)	const

Get the z coordinate of the bottom left corner of the transformed bitmap.

Returns:

The Z3 coordinate.

getZAngle


virtual float getZAngle	(			)	const

Get the z angle in radians.

Returns:

The z angle.

Note

Angles are given in radians, so a full circle is 2*PI.

See also:

updateZAngle

invalidateContent


virtual void invalidateContent	(			)	const

Tell the framework that the contents of the Drawable needs to be redrawn.

If the Drawable is invisible, nothing happens. Subclasses of Drawable are encouraged to implement this function and invalidate as little as possible, i.e. the smallest rectangle covering the visual element(s) drawn by the widget.

Reimplements: touchgfx::Image::invalidateContent

setAngles

Sets the angles in radians of the image.

Parameters:


newXAngle	The new x Angle.
newYAngle	The new y Angle.
newZAngle	The new x Angle.

Note

The area covered by the image before/after changing the angles is NOT invalidated. Angles are given in radians, so a full circle is 2*PI.

setBitmap

Sets the bitmap for this TextureMapper and updates the width and height of this widget to match those of the Bitmap.

Parameters:


bmp	The bitmap instance.

Note

The user code must call invalidate() in order to update the image on the display.

Reimplements: touchgfx::Image::setBitmap

setBitmapPosition

Sets the position of the bitmap within the TextureMapper.

The bitmap is clipped with respect to the dimensions of the TextureMapper widget.

Parameters:


x	The x coordinate.
y	The y coordinate.

See also:

getBitmapPositionX, getBitmapPositionY

setBitmapPosition

Sets the position of the bitmap within the TextureMapper.

The bitmap is clipped with respect to the dimensions of the TextureMapper widget.

Parameters:


x	The x coordinate.
y	The y coordinate.

See also:

getBitmapPositionX, getBitmapPositionY

setCamera

Sets the camera coordinate.

Parameters:


x	The x coordinate for the camera.
y	The y coordinate for the camera.

See also:

getCameraX, getCameraY

setCameraDistance

Sets camera distance.

If the given value is below TextureMapper::MINIMAL_CAMERA_DISTANCE, it will be set to TextureMapper::MINIMAL_CAMERA_DISTANCE.

Parameters:


d	The new camera distance.

See also:

getCameraDistance

setOrigo

Sets the transformation origo (center) in two dimensions.

Leaves the z coordinate untouched.

Parameters:


x	The x coordinate.
y	The y coordinate.

See also:

getOrigoX, getOrigoY

setOrigo

Sets the transformation origo (center).

Parameters:


x	The x coordinate.
y	The y coordinate.
z	The z coordinate.

See also:

getOrigoX, getOrigoY, getOrigoZ

setRenderingAlgorithm

Sets the render algorithm to be used.

Default setting is NEAREST_NEIGHBOR.

Parameters:


algorithm	The algorithm to use when rendering.

setScale

Sets the scale of the image.

Parameters:


newScale	The new scale value.

See also:

updateScale, getScale

setXAngle

Sets the x angle in radians.

Parameters:


newXAngle	The new x angle.

Note

The area covered by the image before/after changing the angle is NOT invalidated. Angles are given in radians, so a full circle is 2*PI.

See also:

setAngles, updateXAngle, getXAngle

setYAngle

Sets the y angle in radians.

Parameters:


newYAngle	The new y angle.

Note

The area covered by the image before/after changing the angle is NOT invalidated. Angles are given in radians, so a full circle is 2*PI.

See also:

setAngles, updateYAngle, getYAngle

setZAngle

Sets the z angle in radians.

Parameters:


newZAngle	The new z angle.

Note

The area covered by the image before/after changing the angle is NOT invalidated. Angles are given in radians, so a full circle is 2*PI.

See also:

setAngles, updateZAngle, getZAngle

TextureMapper

Constructs a new TextureMapper with a default alpha value of 255 (solid) and a default Bitmap (undefined) if none is specified.

If a Bitmap is passed to the constructor, the width and height of this widget is set to those of the bitmap.

Parameters:


bmp	(Optional) The bitmap to display.

See also:

setBitmap

TOUCHGFX_DEPRECATED

Invalidate the bounding rectangle of the transformed bitmap.

Deprecated

Please use invalidateContent() instead.

See also:

getBoundingRect

updateAngles

Updates the angles in radians of the image.

The area covered by the image before and after changing the angles is invalidated, which is the smallest required rectangle.

Parameters:


newXAngle	The new x Angle.
newYAngle	The new y Angle.
newZAngle	The new x Angle.

Note

Angles are given in radians, so a full circle is 2*PI.

updateScale

Updates the scale of the image.

This implies invalidating the area covered by the texture mapper.

Parameters:


newScale	The new scale value.

See also:

setScale, getScale

updateXAngle

Updates the x angle in radians.

Parameters:


newXAngle	The new x angle.

Note

Angles are given in radians, so a full circle is 2*PI.

See also:

updateAngles, getXAngle

updateYAngle

Updates the y angle in radians.

Parameters:


newYAngle	The new y angle.

Note

Angles are given in radians, so a full circle is 2*PI.

See also:

updateAngles, getYAngle

updateZAngle

Updates the z angle in radians.

Parameters:


newZAngle	The new z angle.

Note

Angles are given in radians, so a full circle is 2*PI.

See also:

updateAngles, getZAngle

Protected Functions Documentation

applyTransformation

Transform the bitmap using the supplied origo, scale, rotation and camera.

This method is called by all the methods that manipulate origo, scale, rotation and camera.

drawQuad


void drawQuad	(	const Rect &	invalidatedArea ,	const
		uint16_t *	fb ,	const
		const float *	triangleXs ,	const
		const float *	triangleYs ,	const
		const float *	triangleZs ,	const
		const float *	triangleUs ,	const
		const float *	triangleVs	const
		)	const

The TextureMapper will draw the transformed bitmap by drawing one transformed quad.

The quad is drawn from the points 0,1,2,3 using the x,y,z values from each point along with the u,v coordinates in the bitmap associated with each point.

Parameters:


invalidatedArea	The invalidated area.
fb	The framebuffer.
triangleXs	The triangle xs.
triangleYs	The triangle ys.
triangleZs	The triangle zs.
triangleUs	The triangle us.
triangleVs	The triangle vs.

getBoundingRect

Gets bounding rectangle of the transformed bitmap.

This is the smallest possible rectangle which covers the image of the bitmap after applying scale and rotation.

Returns:

The bounding rectangle.

lookupRenderVariant

Returns the rendering variant based on the bitmap format, alpha value and rendering algorithm.

Returns:

The RenderingVariant.

Protected Attributes Documentation

cameraDistance

The camera distance.