draw.h File Reference

Utilities for drawing to the screen. More...

Go to the source code of this file.

Functions
float	AERDrawGetCurrentAlpha (void)
	Query the current global draw alpha. More...
void	AERDrawSetCurrentAlpha (float alpha)
	Set the current global draw alpha. More...
void	AERDrawSprite (int32_t spriteIdx, uint32_t frame, float x, float y, float scale, uint32_t blend)
	Draw a sprite to the screen. More...
void	AERDrawSpriteAdv (int32_t spriteIdx, uint32_t frame, int32_t left, int32_t top, int32_t width, int32_t height, float x, float y, float scaleX, float scaleY, float angle, uint32_t blendNW, uint32_t blendNE, uint32_t blendSE, uint32_t blendSW, float alpha)
	Draw a sprite to the screen. More...
void	AERDrawLine (float x1, float y1, float x2, float y2, uint32_t color)
	Draw a line to the screen. More...
void	AERDrawLineAdv (float x1, float y1, float x2, float y2, float width, uint32_t color1, uint32_t color2)
	Draw a line to the screen. More...
void	AERDrawEllipse (float left, float top, float right, float bottom, uint32_t color, bool outline)
	Draw an ellipse to the screen. More...
void	AERDrawEllipseAdv (float left, float top, float right, float bottom, uint32_t colorCenter, uint32_t colorEdge, bool outline)
	Draw an ellipse to the screen. More...
void	AERDrawTriangle (float x1, float y1, float x2, float y2, float x3, float y3, uint32_t color, bool outline)
	Draw a triangle to the screen. More...
void	AERDrawTriangleAdv (float x1, float y1, float x2, float y2, float x3, float y3, uint32_t color1, uint32_t color2, uint32_t color3, bool outline)
	Draw a triangle to the screen. More...
void	AERDrawRectangle (float left, float top, float right, float bottom, uint32_t color, bool outline)
	Draw a rectangle to the screen. More...
void	AERDrawRectangleAdv (float left, float top, float right, float bottom, uint32_t colorNW, uint32_t colorNE, uint32_t colorSE, uint32_t colorSW, bool outline)
	Draw a rectangle to the screen. More...
void	AERDrawText (const char *text, float x, float y, uint32_t width, float scale, uint32_t color)
	Draw text to the screen. More...
void	AERDrawTextAdv (const char *text, float x, float y, int32_t height, uint32_t width, float scaleX, float scaleY, float angle, uint32_t colorNW, uint32_t colorNE, uint32_t colorSE, uint32_t colorSW, float alpha)
	Draw text to the screen. More...

Detailed Description

Utilities for drawing to the screen.

The functions in this module should only be called from inside object draw event listeners. See AERObjectAttachDrawListener for more information.

Colors

Colors are represented as unsigned 32-bit integers. The least significant byte is the red component, the next byte is the green component, the second most significant byte is the blue component and the most significant byte is unused (it is not used for alpha).

This means that expressing a color in hexadecimal requires writing it in "BGR" order (i.e. the color red=0x0, green=0x70, blue=0xf0 would be written as 0xf07000).

Since

1.1.0

Copyright

2021 the libaermre authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Function Documentation

AERDrawEllipse()

void AERDrawEllipse	(	float	left,
		float	top,
		float	right,
		float	bottom,
		uint32_t	color,
		bool	outline
	)

Draw an ellipse to the screen.

Parameters

[in]	left	X-intercept of the left side of ellipse.
[in]	top	Y-intercept of the top side of ellipse.
[in]	right	X-intercept of the right side of ellipse.
[in]	bottom	Y-intercept of the bottom side of ellipse.
[in]	color	Color of the ellipse. See Colors for more infomation.
[in]	outline	Whether to render a solid ellipse (false) or a 1 pixel wide outline of an ellipse (true).

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.3.0

See also

AERDrawEllipseAdv

AERDrawEllipseAdv()

void AERDrawEllipseAdv	(	float	left,
		float	top,
		float	right,
		float	bottom,
		uint32_t	colorCenter,
		uint32_t	colorEdge,
		bool	outline
	)

Draw an ellipse to the screen.

If more than one color is provided, then the engine will render a smooth gradient.

Parameters

[in]	left	X-intercept of the left side of ellipse.
[in]	top	Y-intercept of the top side of ellipse.
[in]	right	X-intercept of the right side of ellipse.
[in]	bottom	Y-intercept of the bottom side of ellipse.
[in]	colorCenter	Color of the center ellipse. See Colors for more infomation.
[in]	colorEdge	Color of the edge ellipse. See Colors for more infomation.
[in]	outline	Whether to render a solid ellipse (false) or a 1 pixel wide outline of an ellipse (true).

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.3.0

See also

AERDrawEllipse

AERDrawGetCurrentAlpha()

float AERDrawGetCurrentAlpha

(

void

)

Query the current global draw alpha.

Global Alpha

This value is implicitly blended into the final result of all draw functions. For functions that take an explicit alpha value, the global alpha is still factored in.

Returns

Global alpha or -1.0f if unsuccessful.

Exceptions

AER_SEQ_BREAK

if called outside action stage.

Since

1.1.0

AERDrawLine()

void AERDrawLine	(	float	x1,
		float	y1,
		float	x2,
		float	y2,
		uint32_t	color
	)

Draw a line to the screen.

Parameters

[in]	x1	Horizontal position of line start.
[in]	y1	Vertical position of line start.
[in]	x2	Horizontal position of line end.
[in]	y2	Vertical position of line end.
[in]	color	Color of the line. See Colors for more infomation.

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.3.0

See also

AERDrawLineAdv

AERDrawLineAdv()

void AERDrawLineAdv	(	float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	width,
		uint32_t	color1,
		uint32_t	color2
	)

Draw a line to the screen.

If more than one color is provided, then the engine will render a smooth gradient.

Parameters

[in]	x1	Horizontal position of line start.
[in]	y1	Vertical position of line start.
[in]	x2	Horizontal position of line end.
[in]	y2	Vertical position of line end.
[in]	width	Line width in pixels.
[in]	color1	Color of the start of the line. See Colors for more infomation.
[in]	color2	Color of the end of the line. See Colors for more infomation.

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.3.0

See also

AERDrawLine

AERDrawRectangle()

void AERDrawRectangle	(	float	left,
		float	top,
		float	right,
		float	bottom,
		uint32_t	color,
		bool	outline
	)

Draw a rectangle to the screen.

Parameters

[in]	left	X-intercept of the left side of rectangle.
[in]	top	Y-intercept of the top side of rectangle.
[in]	right	X-intercept of the right side of rectangle.
[in]	bottom	Y-intercept of the bottom side of rectangle.
[in]	color	Color of the rectangle. See Colors for more infomation.
[in]	outline	Whether to render a solid rectangle (false) or a 1 pixel wide outline of a rectangle (true).

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.1.0

See also

AERDrawRectangleAdv

AERDrawRectangleAdv()

void AERDrawRectangleAdv	(	float	left,
		float	top,
		float	right,
		float	bottom,
		uint32_t	colorNW,
		uint32_t	colorNE,
		uint32_t	colorSE,
		uint32_t	colorSW,
		bool	outline
	)

Draw a rectangle to the screen.

If more than one color is provided, then the engine will render a smooth gradient.

Parameters

[in]	left	X-intercept of the left side of rectangle.
[in]	top	Y-intercept of the top side of rectangle.
[in]	right	X-intercept of the right side of rectangle.
[in]	bottom	Y-intercept of the bottom side of rectangle.
[in]	colorNW	Color of northwest vertex. See Colors for more infomation.
[in]	colorNE	Color of northeast vertex. See Colors for more infomation.
[in]	colorSE	Color of southeast vertex. See Colors for more infomation.
[in]	colorSW	Color of southwest vertex. See Colors for more infomation.
[in]	outline	Whether to render a solid rectangle (false) or a 1 pixel wide outline of a rectangle (true).

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.1.0

See also

AERDrawRectangle

AERDrawSetCurrentAlpha()

void AERDrawSetCurrentAlpha

(

float

alpha

)

Set the current global draw alpha.

See Global Alpha for more information about this value.

Parameters

[in]

alpha

Global alpha.

Exceptions

AER_SEQ_BREAK	if called outside action stage.
AER_BAD_VAL	if argument alpha is less than 0.0f or greater than 1.0f.

Since

1.1.0

AERDrawSprite()

void AERDrawSprite	(	int32_t	spriteIdx,
		uint32_t	frame,
		float	x,
		float	y,
		float	scale,
		uint32_t	blend
	)

Draw a sprite to the screen.

Parameters

[in]	spriteIdx	Sprite to draw.
[in]	frame	Frame of sprite to draw.
[in]	x	Horizontal position at which to draw sprite.
[in]	y	Vertical position at which to draw sprite.
[in]	scale	Horizontal and vertical scale of text.
[in]	blend	Color to blend with sprite. See Colors for more infomation.

Exceptions

AER_SEQ_BREAK	if called outside draw stage.
AER_FAILED_LOOKUP	if argument spriteIdx is an invalid sprite.
AER_BAD_VAL	if argument frame is greater than or equal to the number of frames in sprite.

Since

1.4.0

See also

AERDrawSpriteAdv

AERDrawSpriteAdv()

void AERDrawSpriteAdv	(	int32_t	spriteIdx,
		uint32_t	frame,
		int32_t	left,
		int32_t	top,
		int32_t	width,
		int32_t	height,
		float	x,
		float	y,
		float	scaleX,
		float	scaleY,
		float	angle,
		uint32_t	blendNW,
		uint32_t	blendNE,
		uint32_t	blendSE,
		uint32_t	blendSW,
		float	alpha
	)

Draw a sprite to the screen.

If more than one blend color is provided, then the engine will render a smooth gradient.

Parameters

[in]	spriteIdx	Sprite to draw.
[in]	frame	Frame of sprite to draw.
[in]	left	Horizontal offset into sprite to draw in pixels.
[in]	top	Vertical offset into sprite to draw in pixels.
[in]	width	Horizontal component of sprite to draw in pixels.
[in]	height	Vertical component of sprite to draw in pixels.
[in]	x	Horizontal position at which to draw sprite.
[in]	y	Vertical position at which to draw sprite.
[in]	scaleX	Horizontal scale of sprite.
[in]	scaleY	Vertical scale of sprite.
[in]	angle	Sprite offset angle in degrees.
[in]	blendNW	Blend color of northwest corner. See Colors for more infomation.
[in]	blendNE	Blend color of northeast corner. See Colors for more infomation.
[in]	blendSE	Blend color of southeast corner. See Colors for more infomation.
[in]	blendSW	Blend color of southwest corner. See Colors for more infomation.
[in]	alpha	Sprite alpha (transparency).

Exceptions

AER_SEQ_BREAK	if called outside draw stage.
AER_FAILED_LOOKUP	if argument spriteIdx is an invalid sprite.
AER_BAD_VAL	if argument alpha is less than 0.0f or greater than 1.0f or if argument frame is greater than or equal to the number of frames in sprite.

Since

1.4.0

See also

AERDrawSprite

AERDrawText()

void AERDrawText	(	const char *	text,
		float	x,
		float	y,
		uint32_t	width,
		float	scale,
		uint32_t	color
	)

Draw text to the screen.

See Text Escape Sequences for more information about text escape sequences.

Parameters

[in]	text	String to draw. Maximum size is 8192 characters including null terminator (will not cause error if larger).
[in]	x	Horizontal position at which to draw text.
[in]	y	Vertical position at which to draw text.
[in]	width	Maximum line width before line break in pixels (not characters).
[in]	scale	Horizontal and vertical scale of text.
[in]	color	Color of text. See Colors for more infomation.

Exceptions

AER_SEQ_BREAK	if called outside draw stage.
AER_NULL_ARG	if argument text is NULL.

Since

1.1.0

See also

AERDrawTextAdv

AERDrawTextAdv()

void AERDrawTextAdv	(	const char *	text,
		float	x,
		float	y,
		int32_t	height,
		uint32_t	width,
		float	scaleX,
		float	scaleY,
		float	angle,
		uint32_t	colorNW,
		uint32_t	colorNE,
		uint32_t	colorSE,
		uint32_t	colorSW,
		float	alpha
	)

Draw text to the screen.

If more than one color is provided, then the engine will render a smooth gradient.

Text Escape Sequences

The game maker engine chose to use the hashtag ('#') character to represent linebreaks. To display a literal hashtag, preceed it with a backslash.

Parameters

[in]	text	String to draw. Maximum size is 8192 characters including null terminator (will not cause error if larger).
[in]	x	Horizontal position at which to draw text.
[in]	y	Vertical position at which to draw text.
[in]	height	Space between each line of text in pixels.
[in]	width	Maximum line width before line break in pixels (not characters).
[in]	scaleX	Horizontal scale of text.
[in]	scaleY	Vertical scale of text.
[in]	angle	Text offset angle in degrees.
[in]	colorNW	Color of northwest corner. See Colors for more infomation.
[in]	colorNE	Color of northeast corner. See Colors for more infomation.
[in]	colorSE	Color of southeast corner. See Colors for more infomation.
[in]	colorSW	Color of southwest corner. See Colors for more infomation.
[in]	alpha	Text alpha (transparency).

Exceptions

AER_SEQ_BREAK	if called outside draw stage.
AER_NULL_ARG	if argument text is NULL.
AER_BAD_VAL	if argument alpha is less than 0.0f or greater than 1.0f.

Since

1.1.0

See also

AERDrawText

AERDrawTriangle()

void AERDrawTriangle	(	float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	x3,
		float	y3,
		uint32_t	color,
		bool	outline
	)

Draw a triangle to the screen.

Parameters

[in]	x1	Horizontal position of first vertex.
[in]	y1	Vertical position of first vertex.
[in]	x2	Horizontal position of second vertex.
[in]	y2	Vertical position of second vertex.
[in]	x3	Horizontal position of third vertex.
[in]	y3	Vertical position of third vertex.
[in]	color	Color of the triangle. See Colors for more infomation.
[in]	outline	Whether to render a solid triangle (false) or a 1 pixel wide outline of a triangle (true).

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.1.0

See also

AERDrawTriangleAdv

AERDrawTriangleAdv()

void AERDrawTriangleAdv	(	float	x1,
		float	y1,
		float	x2,
		float	y2,
		float	x3,
		float	y3,
		uint32_t	color1,
		uint32_t	color2,
		uint32_t	color3,
		bool	outline
	)

Draw a triangle to the screen.

If more than one color is provided, then the engine will render a smooth gradient.

Parameters

[in]	x1	Horizontal position of first vertex.
[in]	y1	Vertical position of first vertex.
[in]	x2	Horizontal position of second vertex.
[in]	y2	Vertical position of second vertex.
[in]	x3	Horizontal position of third vertex.
[in]	y3	Vertical position of third vertex.
[in]	color1	Color of first vertex. See Colors for more infomation.
[in]	color2	Color of second vertex. See Colors for more infomation.
[in]	color3	Color of third vertex. See Colors for more infomation.
[in]	outline	Whether to render a solid triangle (false) or a 1 pixel wide outline of a triangle (true).

Exceptions

AER_SEQ_BREAK

if called outside draw stage.

Since

1.1.0

See also

AERDrawTriangle