Simplified Brain Screen C API

Files
file	screen.h

Classes
struct	screen_touch_status_s
struct	screen_touch_status_s_t

Typedefs
typedef struct screen_touch_status_s	screen_touch_status_s_t
typedef void(*	touch_event_cb_fn_t) ()

Enumerations
enum	text_format_e_t {   E_TEXT_SMALL = 0 , E_TEXT_MEDIUM , E_TEXT_LARGE , E_TEXT_MEDIUM_CENTER ,   E_TEXT_LARGE_CENTER }
enum	last_touch_e_t { E_TOUCH_RELEASED = 0 , E_TOUCH_PRESSED , E_TOUCH_HELD , E_TOUCH_ERROR }

Screen Graphical Display Functions
These functions allow programmers to display shapes on the v5 screen
uint32_t	screen_set_pen (uint32_t color)
uint32_t	screen_set_eraser (uint32_t color)
uint32_t	screen_get_pen (void)
uint32_t	screen_get_eraser (void)
uint32_t	screen_erase (void)
uint32_t	screen_scroll (int16_t start_line, int16_t lines)
uint32_t	screen_scroll_area (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t lines)
uint32_t	screen_copy_area (int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint32_t *buf, int32_t stride)
uint32_t	screen_draw_pixel (int16_t x, int16_t y)
uint32_t	screen_erase_pixel (int16_t x, int16_t y)
uint32_t	screen_draw_line (int16_t x0, int16_t y0, int16_t x1, int16_t y1)
uint32_t	screen_erase_line (int16_t x0, int16_t y0, int16_t x1, int16_t y1)
uint32_t	screen_draw_rect (int16_t x0, int16_t y0, int16_t x1, int16_t y1)
uint32_t	screen_erase_rect (int16_t x0, int16_t y0, int16_t x1, int16_t y1)
uint32_t	screen_fill_rect (int16_t x0, int16_t y0, int16_t x1, int16_t y1)
uint32_t	screen_draw_circle (int16_t x, int16_t y, int16_t radius)
uint32_t	screen_erase_circle (int16_t x, int16_t y, int16_t radius)
uint32_t	screen_fill_circle (int16_t x, int16_t y, int16_t radius)

Screen Text Display Functions
These functions allow programmers to display text on the v5 screen
uint32_t	screen_print (text_format_e_t txt_fmt, const int16_t line, const char *text,...)
uint32_t	screen_print_at (text_format_e_t txt_fmt, const int16_t x, const int16_t y, const char *text,...)
uint32_t	screen_vprintf (text_format_e_t txt_fmt, const int16_t line, const char *text, va_list args)
uint32_t	screen_vprintf_at (text_format_e_t txt_fmt, const int16_t x, const int16_t y, const char *text, va_list args)

Screen Touch Functions
These functions allow programmers to access information about screen touches
screen_touch_status_s_t	screen_touch_status (void)
uint32_t	screen_touch_callback (touch_event_cb_fn_t cb, last_touch_e_t event_type)

Detailed Description

Enumeration Type Documentation

last_touch_e_t

enum last_touch_e_t

Enum indicating what the current touch status is for the touchscreen.

Enumerator
E_TOUCH_RELEASED	Last interaction with screen was a quick press.
E_TOUCH_PRESSED	Last interaction with screen was a release.
E_TOUCH_HELD	User is holding screen down.
E_TOUCH_ERROR	An error occured while taking/returning the mutex.

text_format_e_t

enum text_format_e_t

Different font sizes that can be used in printing text.

Enumerator
E_TEXT_SMALL	Small text font size.
E_TEXT_MEDIUM	Normal/Medium text font size.
E_TEXT_LARGE	Large text font size.
E_TEXT_MEDIUM_CENTER	Medium centered text.
E_TEXT_LARGE_CENTER	Large centered text.

Function Documentation

screen_copy_area()

uint32_t screen_copy_area	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1,
		uint32_t *	buf,
		int32_t	stride )

Copy a screen region (designated by a rectangle) from an off-screen buffer to the screen

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x,y) coordinates of the first corner of the rectangular region of the screen
x1,y1	The (x,y) coordinates of the second corner of the rectangular region of the screen
buf	Off-screen buffer containing screen data
stride	Off-screen buffer width in pixels, such that image size is stride-padding

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_draw_circle()

uint32_t screen_draw_circle	(	int16_t	x,
		int16_t	y,
		int16_t	radius )

Draw a circle on the screen using the current pen color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x,y	The (x,y) coordinates of the center of the circle
r	The radius of the circle

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_draw_line()

uint32_t screen_draw_line	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1 )

Draw a line on the screen using the current pen color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x, y) coordinates of the first point of the line
x1,y1	The (x, y) coordinates of the second point of the line

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_draw_pixel()

uint32_t screen_draw_pixel	(	int16_t	x,
		int16_t	y )

Draw a single pixel on the screen using the current pen color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x,y	The (x,y) coordinates of the pixel

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_draw_rect()

uint32_t screen_draw_rect	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1 )

Draw a rectangle on the screen using the current pen color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x,y) coordinates of the first point of the rectangle
x1,y1	The (x,y) coordinates of the second point of the rectangle

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_erase()

uint32_t screen_erase

(

void

)

Clear display with eraser color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_erase_circle()

uint32_t screen_erase_circle	(	int16_t	x,
		int16_t	y,
		int16_t	radius )

Erase a circle on the screen using the current eraser color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x,y	The (x,y) coordinates of the center of the circle
r	The radius of the circle

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_erase_line()

uint32_t screen_erase_line	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1 )

Erase a line on the screen using the current eraser color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x, y) coordinates of the first point of the line
x1,y1	The (x, y) coordinates of the second point of the line

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_erase_pixel()

uint32_t screen_erase_pixel	(	int16_t	x,
		int16_t	y )

Erase a pixel from the screen (Sets the location)

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x,y	The (x,y) coordinates of the erased

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_erase_rect()

uint32_t screen_erase_rect	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1 )

Erase a rectangle on the screen using the current eraser color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x,y) coordinates of the first point of the rectangle
x1,y1	The (x,y) coordinates of the second point of the rectangle

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_fill_circle()

uint32_t screen_fill_circle	(	int16_t	x,
		int16_t	y,
		int16_t	radius )

Fill a circular region of the screen using the current pen color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x,y	The (x,y) coordinates of the center of the circle
r	The radius of the circle

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_fill_rect()

uint32_t screen_fill_rect	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1 )

Fill a rectangular region of the screen using the current pen color

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x,y) coordinates of the first point of the rectangle
x1,y1	The (x,y) coordinates of the second point of the rectangle

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_get_eraser()

uint32_t screen_get_eraser

(

void

)

Get the current eraser color.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Returns

The current eraser color in the form of a value from the enum defined in colors.h, or PROS_ERR if there was an error taking or returning the screen mutex.

Example

screen_get_pen()

uint32_t screen_get_pen

(

void

)

Get the current pen color.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Returns

The current pen color in the form of a value from the enum defined in colors.h, or PROS_ERR if there was an error taking or returning the screen mutex.

Example

screen_print()

uint32_t screen_print	(	text_format_e_t	txt_fmt,
		const int16_t	line,
		const char *	text,
			... )

Print a formatted string to the screen on the specified line

Will default to a medium sized font by default if invalid txt_fmt is given.

Parameters

txt_fmt	Text format enum that determines if the text is medium, large, medium_center, or large_center. (DOES NOT SUPPORT SMALL)
line	The line number on which to print
text	Format string
...	Optional list of arguments for the format string

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_print_at()

uint32_t screen_print_at	(	text_format_e_t	txt_fmt,
		const int16_t	x,
		const int16_t	y,
		const char *	text,
			... )

Print a formatted string to the screen at the specified point

Will default to a medium sized font by default if invalid txt_fmt is given.

Text formats medium_center and large_center will default to medium and large respectively.

Parameters

txt_fmt	Text format enum that determines if the text is small, medium, or large.
x	The y coordinate of the top left corner of the string
y	The x coordinate of the top left corner of the string
text	Format string
...	Optional list of arguments for the format string

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_scroll()

uint32_t screen_scroll	(	int16_t	start_line,
		int16_t	lines )

Scroll lines on the display upwards.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

start_line	The line from which scrolling will start
lines	The number of lines to scroll up

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_scroll_area()

uint32_t screen_scroll_area	(	int16_t	x0,
		int16_t	y0,
		int16_t	x1,
		int16_t	y1,
		int16_t	lines )

Scroll lines within a region on the display

This function behaves in the same way as screen_scroll, except that you specify a rectangular region within which to scroll lines instead of a start line.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

x0,y0	The (x,y) coordinates of the first corner of the rectangular region
x1,y1	The (x,y) coordinates of the second corner of the rectangular region
lines	The number of lines to scroll upwards

Returns

1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

Example

screen_set_eraser()

uint32_t screen_set_eraser

(

uint32_t

color

)

Set the eraser color for erasing and the current background.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

color

The background color to set (it is recommended to use values from the enum defined in colors.h)

Returns

Returns 1 if the mutex was successfully returned, or PROS_ERR if there was an error either taking or returning the screen mutex.

Example

screen_set_pen()

uint32_t screen_set_pen

(

uint32_t

color

)

Set the pen color for subsequent graphics operations

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

color

The pen color to set (it is recommended to use values from the enum defined in colors.h)

Returns

Returns 1 if the mutex was successfully returned, or PROS_ERR if there was an error either taking or returning the screen mutex.

Example

screen_touch_callback()

uint32_t screen_touch_callback	(	touch_event_cb_fn_t	cb,
		last_touch_e_t	event_type )

Assigns a callback function to be called when a certain touch event happens.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

cb	Function pointer to callback when event type happens
event_type	Touch event that will trigger the callback.

Returns

1 if there were no errors, or PROS_ERR if an error occured while taking or returning the screen mutex.

Example

screen_touch_status()

screen_touch_status_s_t screen_touch_status

(

void

)

Gets the touch status of the last touch of the screen.

Returns

The last_touch_e_t enum specifier that indicates the last touch status of the screen (E_TOUCH_EVENT_RELEASE, E_TOUCH_EVENT_PRESS, or E_TOUCH_EVENT_PRESS_AND_HOLD). This will be released by default if no action was taken. If an error occured, the screen_touch_status_s_t will have its last_touch_e_t enum specifier set to E_TOUCH_ERR, and other values set to -1.

Example

screen_vprintf()

uint32_t screen_vprintf	(	text_format_e_t	txt_fmt,
		const int16_t	line,
		const char *	text,
		va_list	args )

Print a formatted string to the screen on the specified line

Same as display_printf except that this uses a va_list instead of the ellipsis operator so this can be used by other functions.

Will default to a medium sized font by default if invalid txt_fmt is given. Exposed mostly for writing libraries and custom functions.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

txt_fmt	Text format enum that determines if the text is medium, large, medium_center, or large_center. (DOES NOT SUPPORT SMALL)
line	The line number on which to print
text	Format string
args	List of arguments for the format string

Returns

1 if there were no errors, or PROS_ERR if an error occured while taking or returning the screen mutex.

screen_vprintf_at()

uint32_t screen_vprintf_at	(	text_format_e_t	txt_fmt,
		const int16_t	x,
		const int16_t	y,
		const char *	text,
		va_list	args )

Print a formatted string to the screen at the specified coordinates

Same as display_printf_at except that this uses a va_list instead of the ellipsis operator so this can be used by other functions.

Will default to a medium sized font by default if invalid txt_fmt is given.

Text formats medium_center and large_center will default to medium and large respectively. Exposed mostly for writing libraries and custom functions.

This function uses the following values of errno when an error state is reached: EACCESS - Another resource is currently trying to access the screen mutex.

Parameters

txt_fmt	Text format enum that determines if the text is small, medium, or large.
x,y	The (x,y) coordinates of the top left corner of the string
text	Format string
args	List of arguments for the format string

Returns

1 if there were no errors, or PROS_ERR if an error occured while taking or returning the screen mutex.