Simplified Brain Screen C API module

Contents

Files

file screen.h
Brain screen display and touch functions.

Namespaces

namespace pros::c

Classes

struct screen_touch_status_s_t
Struct representing screen touch status, screen last x, screen last y, press count, release count.

Screen Graphical Display Functions

These functions allow programmers to display shapes on the v5 screen

uint32_t screen_set_pen(uint32_t color)
Set the pen color for subsequent graphics operations.
uint32_t screen_set_eraser(uint32_t color)
Set the eraser color for erasing and the current background.
uint32_t screen_get_pen(void)
Get the current pen color.
uint32_t screen_get_eraser(void)
Get the current eraser color.
uint32_t screen_erase(void)
Clear display with eraser color.
uint32_t screen_scroll(int16_t start_line, int16_t lines)
Scroll lines on the display upwards.
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.
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.
uint32_t screen_draw_pixel(int16_t x, int16_t y)
Draw a single pixel on the screen using the current pen color.
uint32_t screen_erase_pixel(int16_t x, int16_t y)
Erase a pixel from the screen (Sets the location)
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.
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.
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.
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.
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.
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.
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.
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.

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, ...)
Print a formatted string to the screen on the specified line.
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.
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.
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.

Screen Touch Functions

These functions allow programmers to access information about screen touches

screen_touch_status_s_t screen_touch_status(void)
Gets the touch status of the last touch of the screen.
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.

Enums

enum text_format_e_t { E_TEXT_SMALL = 0, E_TEXT_MEDIUM, E_TEXT_LARGE, E_TEXT_MEDIUM_CENTER, E_TEXT_LARGE_CENTER }
Different font sizes that can be used in printing text.
enum last_touch_e_t { E_TOUCH_RELEASED = 0, E_TOUCH_PRESSED, E_TOUCH_HELD, E_TOUCH_ERROR }
Enum indicating what the current touch status is for the touchscreen.

Typedefs

using touch_event_cb_fn_t = void(*)()

Variables

last_touch_e_t touch_status
Represents if the screen is being held, released, or pressed.
int16_t x
Represents the x value of the location of the touch.
int16_t y
Represents the y value of the location of the touch.
int32_t press_count
Represents how many times the screen has be pressed.
int32_t release_count
Represents how many times the user released after a touch on the screen.

Function documentation

uint32_t screen_set_pen(uint32_t color)
#include <pros/screen.h>

Set the pen color for subsequent graphics operations.

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.

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.

Example

void initialize() {
  screen_set_pen(COLOR_RED);
}

void opcontrol() {
  int iter = 0;
  while(1){
    // This should print in red.
    screen_print(TEXT_MEDIUM, 1, "%d", iter++);
  }
}

uint32_t screen_set_eraser(uint32_t color)
#include <pros/screen.h>

Set the eraser color for erasing and the current background.

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.

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.

Example

void initialize() {
  screen_set_eraser(COLOR_RED);
}

void opcontrol() {
  while(1){
    // This should turn the screen red.
    screen_erase();
  }
}

uint32_t screen_get_pen(void)
#include <pros/screen.h>

Get the current pen color.

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.

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.

Example

void initialize() {
  screen_set_pen(COLOR_RED);
}

void opcontrol() {
  while(1){
    // Should print number equivalent to COLOR_RED defined in colors.h.
    screen_print(TEXT_MEDIUM, 1, "%d", screen_get_pen());
  }
}

uint32_t screen_get_eraser(void)
#include <pros/screen.h>

Get the current eraser color.

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.

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.

Example

void initialize() {
  screen_set_eraser(COLOR_RED);
}

void opcontrol() {
  while(1){
    // Should print number equivalent to COLOR_RED defined in colors.h.
    screen_print(TEXT_MEDIUM, 1, "%d", screen_get_eraser());
  }
}

uint32_t screen_erase(void)
#include <pros/screen.h>

Clear display with eraser color.

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

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.

Example

void initialize() {
  screen_set_eraser(COLOR_RED);
}

void opcontrol() {
  while(1){
    // This should turn the screen red.
    screen_erase();
  }
}

uint32_t screen_scroll(int16_t start_line, int16_t lines)
#include <pros/screen.h>

Scroll lines on the display upwards.

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.

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.

Example

void opcontrol() {
  screen_print(TEXT_MEDIUM, 4, "Line Here");
  // Scroll 3 lines
  screen_scroll(4, 3);
}

uint32_t screen_scroll_area(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t lines)
#include <pros/screen.h>

Scroll lines within a region on the display.

Parameters
x0 The (x,y) coordinates of the first corner of the rectangular region
y0 The (x,y) coordinates of the first corner of the rectangular region
x1 The (x,y) coordinates of the second corner of the rectangular region
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.

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.

Example

void opcontrol() {
  screen_print(TEXT_MEDIUM, 1, "Line Here");
  // Scrolls area of screen upwards slightly. including line of text
  screen_scroll_area(0,0, 400, 200, 3);
}

uint32_t screen_copy_area(int16_t x0, int16_t y0, int16_t x1, int16_t y1, uint32_t* buf, int32_t stride)
#include <pros/screen.h>

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

Parameters
x0 The (x,y) coordinates of the first corner of the rectangular region of the screen
y0 The (x,y) coordinates of the first corner of the rectangular region of the screen
x1 The (x,y) coordinates of the second corner of the rectangular region of the screen
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.

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.

Example

void opcontrol() {
  uint32_t* buf = malloc(sizeof(uint32_t) * 400 * 200);
  screen_print(TEXT_MEDIUM, 1, "Line Here");
  // Copies area of the screen including text
  screen_copy_area(0, 0, 400, 200, (uint32_t*)buf, 400 + 1);
  // Equation for stride is x2 - x1 + 1
}

uint32_t screen_draw_pixel(int16_t x, int16_t y)
#include <pros/screen.h>

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

Parameters
x The (x,y) coordinates of the pixel
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.

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.

Example

int i = 0;
void opcontrol() {
  while(i < 200){
    screen_draw_pixel(100,i++);
    // Draws a line at x = 100 gradually down the screen, pixel by pixel
    delay(200);
  }
}

uint32_t screen_erase_pixel(int16_t x, int16_t y)
#include <pros/screen.h>

Erase a pixel from the screen (Sets the location)

Parameters
x The (x,y) coordinates of the erased
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.

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.

Example

void opcontrol() {
  // Color the Screen in Red
  screen_set_pen(COLOR_RED);
  screen_fill_rect(0,0,400,200);
  int i = 0;
  while(i < 200){
    screen_erase_pixel(100,i++);
    // Erases a line at x = 100 gradually down the screen, pixel by pixel
    delay(200);
  }
}

uint32_t screen_draw_line(int16_t x0, int16_t y0, int16_t x1, int16_t y1)
#include <pros/screen.h>

Draw a line on the screen using the current pen color.

Parameters
x0 The (x, y) coordinates of the first point of the line
y0 The (x, y) coordinates of the first point of the line
x1 The (x, y) coordinates of the second point of the line
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.

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.

Example

void opcontrol() {
     screen_set_pen(COLOR_RED);
  // Draw line down the screen at x = 100
  screen_draw_line(100,0,100,200);
}

uint32_t screen_erase_line(int16_t x0, int16_t y0, int16_t x1, int16_t y1)
#include <pros/screen.h>

Erase a line on the screen using the current eraser color.

Parameters
x0 The (x, y) coordinates of the first point of the line
y0 The (x, y) coordinates of the first point of the line
x1 The (x, y) coordinates of the second point of the line
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.

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.

Example

void opcontrol() {
  // Color the Screen in Red
  screen_set_pen(COLOR_RED);
  screen_fill_rect(0,0,400,200);
  // Erase line down the screen at x = 100
  screen_erase_line(100,0,100,200);
}

uint32_t screen_draw_rect(int16_t x0, int16_t y0, int16_t x1, int16_t y1)
#include <pros/screen.h>

Draw a rectangle on the screen using the current pen color.

Parameters
x0 The (x,y) coordinates of the first point of the rectangle
y0 The (x,y) coordinates of the first point of the rectangle
x1 The (x,y) coordinates of the second point of the rectangle
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.

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.

Example

void opcontrol() {
  screen_set_pen(COLOR_RED);
  screen_draw_rect(1,1,480,200);
}

uint32_t screen_erase_rect(int16_t x0, int16_t y0, int16_t x1, int16_t y1)
#include <pros/screen.h>

Erase a rectangle on the screen using the current eraser color.

Parameters
x0 The (x,y) coordinates of the first point of the rectangle
y0 The (x,y) coordinates of the first point of the rectangle
x1 The (x,y) coordinates of the second point of the rectangle
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.

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.

Example

void opcontrol() {
  // Draw Box Around Half the Screen in Red
  screen_set_eraser(COLOR_RED);
  screen_erase_rect(5,5,240,200);
}

uint32_t screen_fill_rect(int16_t x0, int16_t y0, int16_t x1, int16_t y1)
#include <pros/screen.h>

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

Parameters
x0 The (x,y) coordinates of the first point of the rectangle
y0 The (x,y) coordinates of the first point of the rectangle
x1 The (x,y) coordinates of the second point of the rectangle
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.

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.

Example

void opcontrol() {
  // Fill Around Half the Screen in Red
  screen_set_pen(COLOR_RED);
  screen_fill_rect(5,5,240,200);
}

uint32_t screen_draw_circle(int16_t x, int16_t y, int16_t radius)
#include <pros/screen.h>

Draw a circle on the screen using the current pen color.

Parameters
x The (x,y) coordinates of the center of the circle
y The (x,y) coordinates of the center of the circle
radius
Returns 1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

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.

Example

void opcontrol() {
  // Draw a circle with radius of 100 in red
  screen_set_pen(COLOR_RED);
  screen_draw_circle(240, 200, 100);
}

uint32_t screen_erase_circle(int16_t x, int16_t y, int16_t radius)
#include <pros/screen.h>

Erase a circle on the screen using the current eraser color.

Parameters
x The (x,y) coordinates of the center of the circle
y The (x,y) coordinates of the center of the circle
radius
Returns 1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

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.

Example

void opcontrol() {
  screen_set_pen(COLOR_RED);
  screen_fill_rect(5,5,240,200);
  // Erase a circle with radius of 100 in COLOR_BLUE
  screen_set_pen(COLOR_BLUE);
  screen_erase_circle(240, 200, 100);
}

uint32_t screen_fill_circle(int16_t x, int16_t y, int16_t radius)
#include <pros/screen.h>

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

Parameters
x The (x,y) coordinates of the center of the circle
y The (x,y) coordinates of the center of the circle
radius
Returns 1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

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.

Example

void opcontrol() {
  screen_set_pen(COLOR_RED);
  screen_fill_rect(5,5,240,200);
  // Fill a circlular area with radius of 100 in COLOR_BLUE
  screen_set_pen(COLOR_BLUE);
  screen_fill_circle(240, 200, 100);
}

uint32_t screen_print(text_format_e_t txt_fmt, const int16_t line, const char* text, ...)
#include <pros/screen.h>

Print a formatted string to the screen on the specified line.

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
Returns 1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

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

Example

void opcontrol() {
  int i = 0;

  screen_set_pen(COLOR_BLUE);
  while(1){
    // Will print seconds started since program started on line 3
    screen_print(TEXT_MEDIUM, 3, "Seconds Passed: %3d", i++);
    delay(1000);
  }
}

uint32_t screen_print_at(text_format_e_t txt_fmt, const int16_t x, const int16_t y, const char* text, ...)
#include <pros/screen.h>

Print a formatted string to the screen at the specified point.

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
Returns 1 if there were no errors, or PROS_ERR if an error occured taking or returning the screen mutex.

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.

Example

void opcontrol() {
  int i = 0;

  screen_set_pen(COLOR_BLUE);
  while(1){
    // Will print seconds started since program started.
    screen_print_at(TEXT_SMALL, 3, "Seconds Passed: %3d", i++);
    delay(1000);
  }
}

uint32_t screen_vprintf(text_format_e_t txt_fmt, const int16_t line, const char* text, va_list args)
#include <pros/screen.h>

Print a formatted string to the screen on the specified line.

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.

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.

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)
#include <pros/screen.h>

Print a formatted string to the screen at the specified coordinates.

Parameters
txt_fmt Text format enum that determines if the text is small, medium, or large.
x The (x,y) coordinates of the top left corner of the string
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.

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.

screen_touch_status_s_t screen_touch_status(void)
#include <pros/screen.h>

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

void opcontrol() {
  int i = 0;
  screen_touch_status_s_t status;
  while(1){
    status = screen_touch_status();

    // Will print various information about the last touch
    screen_print(TEXT_MEDIUM, 1, "Touch Status (Type): %d", status.touch_status);
    screen_print(TEXT_MEDIUM, 2, "Last X: %d", status.x);
    screen_print(TEXT_MEDIUM, 3, "Last Y: %d", status.y);
    screen_print(TEXT_MEDIUM, 4, "Press Count: %d", status.press_count);
    screen_print(TEXT_MEDIUM, 5, "Release Count: %d", status.release_count);
    delay(20);
  }
}

uint32_t screen_touch_callback(touch_event_cb_fn_t cb, last_touch_e_t event_type)
#include <pros/screen.h>

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

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.

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.

Example

touch_event_cb_fn_t changePixel(){
  screen_touch_status_s_t status = screen_touch_status();
  screen_draw_pixel(status.x,status.y);
  return NULL;
}

void opcontrol() {
  screen_touch_callback(changePixel(), TOUCH_PRESSED);
  while(1) delay(20);
}

Enum documentation

enum text_format_e_t
#include <pros/screen.h>

Different font sizes that can be used in printing text.

Enumerators
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.

enum last_touch_e_t
#include <pros/screen.h>

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

Enumerators
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.

Typedef documentation

typedef void(*touch_event_cb_fn_t)()
#include <pros/screen.h>

Variable documentation

last_touch_e_t touch_status
#include <pros/screen.h>

Represents if the screen is being held, released, or pressed.

int16_t x
#include <pros/screen.h>

Represents the x value of the location of the touch.

int16_t y
#include <pros/screen.h>

Represents the y value of the location of the touch.

int32_t press_count
#include <pros/screen.h>

Represents how many times the screen has be pressed.

int32_t release_count
#include <pros/screen.h>

Represents how many times the user released after a touch on the screen.