Simplified Brain Screen C++ API¶

pros::screen ¶

Note

The default color for the pen is white, while the default eraser color is black.

Drawing Functions ¶

set_pen ¶

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.

void set_pen(const std::uint32_t color);

void initialize() {
  pros::screen::set_pen(COLOR_RED);
}

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

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

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

set_eraser ¶

Set the eraser 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.

void set_eraser(const std::uint32_t color);

void initialize() {
  pros::screen::set_eraser(COLOR_RED);
}

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

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

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

get_pen ¶

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.

void get_pen(const std::uint32_t color);

void initialize() {
  pros::screen::set_pen(COLOR_RED);
}

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

Returns: The current pen color of the screen object in the form of a value from the enum defined in colors.h.

get_eraser ¶

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.

void get_eraser(const std::uint32_t color);

void initialize() {
  pros::screen::set_pen(COLOR_RED);
}

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

Returns: The current eraser color of the screen object in the form of a value from the enum defined in colors.h.

erase ¶

Clear entire 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.

void erase();

void initialize() {
  pros::screen::set_eraser(COLOR_RED);
}

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

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

scroll ¶

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.

void scroll(const std::int16_t start_line, const std::int16_t lines);

void opcontrol() {
   pros::screen::print(TEXT_MEDIUM, 4, "Line Here");
   // Scroll 3 lines
   pros::screen::scroll(4, 3);
}

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

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

scroll_area ¶

Scroll lines within a region on the display

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.

void scroll_area(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1, std::int16_t lines);

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

Parameters
x0	The x coordinate of the top left corner of the rectangular region
y0	The y coordinate of the top left corner of the rectangular region
x1	The x coordinate of the bottom right corner of the rectangular region
y1	The y coordinate of the bottom right corner of the rectangular region
lines	The number of lines to scroll up

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

copy_area ¶

Copy a screen region (designated by a rectangle) to an off-screen buffer from 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.

void copy_area(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1, uint32_t* buf, const std::int32_t stride);

void opcontrol() {
   uint32_t* buf = malloc(sizeof(uint32_t) * 400 * 200);
   pros::screen::print(TEXT_MEDIUM, 1, "Line Here");

   // Copies area of the screen including text
   pros::screen::copy_area(0, 0, 400, 200, (uint32_t*)buf, 400 + 1);
   // Equation for stride is x2 - x1 + 1
}

Parameters
x0	The x coordinate of the top left corner of the rectangular region
y0	The y coordinate of the top left corner of the rectangular region
x1	The x coordinate of the bottom right corner of the rectangular region
y1	The y coordinate of the bottom right corner of the rectangular region
buf	Off-screen buffer containing screen data
stride	Off-screen buffer width in pixels, such that image size is stride-padding

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

draw_pixel ¶

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.

void draw_pixel(const std::int16_t x, const std::int16_t y);

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

Parameters
x	The x coordinate of the pixel
y	The y coordinate of the pixel

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

erase_pixel ¶

Erase a pixel from 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.

void erase_pixel(const std::int16_t x, const std::int16_t y);

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

Parameters
x	The x coordinate of the pixel
y	The y coordinate of the pixel

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

draw_line ¶

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.

void draw_line(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1);

void opcontrol() {
    // Draw line down the screen at x = 100
    pros::screen::draw_line(100,0,100,200);

}

Parameters
x0	The x coordinate of the first point of the line
y0	The y coordinate of the first point of the line
x1	The x coordinate of the second point of the line
y1	The y coordinate of the second point of the line

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

erase_line ¶

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.

void erase_line(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1);

void opcontrol() {
    // Color the Screen in Red
    pros::screen::set_pen(COLOR_RED);
    pros::screen::fill_rect(0,0,400,200);
    // Erase line down the screen at x = 100
    pros::screen::erase_line(100,0,100,200);
}

Parameters
x0	The x coordinate of the first point of the line
y0	The y coordinate of the first point of the line
x1	The x coordinate of the second point of the line
y1	The y coordinate of the second point of the line

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

draw_rect ¶

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.

void draw_rect(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1);

void opcontrol() {
    // Color the Screen in Red
    pros::screen::set_pen(COLOR_RED);
    pros::screen::draw_rect(1,1,480,200);
}

Parameters
x0	The x coordinate of the top left point of the line
y0	The y coordinate of the top left point of the line
x1	The x coordinate of the bottom right point of the line
y1	The y coordinate of the bottom right point of the line

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

erase_rect ¶

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.

void erase_rect(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1);

void opcontrol() {
    // Draw Box Around Half the Screen in Red
    pros::screen::set_eraser(COLOR_RED);
    pros::screen::erase_rect(5,5,240,200);
}

Parameters
x0	The x coordinate of the top left point of the line
y0	The y coordinate of the top left point of the line
x1	The x coordinate of the bottom right point of the line
y1	The y coordinate of the bottom right point of the line

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

fill_rect ¶

Fill a rectanglular region 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.

void fill_rect(const std::int16_t x0, const std::int16_t y0, const std::int16_t x1, const std::int16_t y1);

void opcontrol() {
    // Fill Around Half the Screen in Red
    pros::screen::set_pen(COLOR_RED);
    pros::screen::fill_rect(5,5,240,200);
}

Parameters
x0	The x coordinate of the top left point of the line
y0	The y coordinate of the top left point of the line
x1	The x coordinate of the bottom right point of the line
y1	The y coordinate of the bottom right point of the line

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

draw_circle ¶

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.

void draw_circle(const std::int16_t x, const std::int16_t y, const std::int16_t radius);

void opcontrol() {
    // Draw a circle with radius of 100 in red
    pros::screen::set_pen(COLOR_RED);
    pros::screen::draw_circle(240, 200, 100);
}

Parameters
x	The x coordinate of the center of the circle
y	The y coordinate of the center of the circle
radius	Radius of the circle

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

erase_circle ¶

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.

void erase_circle(const std::int16_t x, const std::int16_t y, const std::int16_t radius);

void opcontrol() {
    pros::screen::set_pen(COLOR_RED);
    pros::screen::fill_rect(5,5,240,200);
    // Erase a circle with radius of 100 in COLOR_BLUE
    pros::screen::set_pen(COLOR_BLUE);
    pros::screen::erase_circle(240, 200, 100);
}

Parameters
x	The x coordinate of the center of the circle
y	The y coordinate of the center of the circle
radius	Radius of the circle

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

fill_circle ¶

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.

void fill_circle(const std::int16_t x, const std::int16_t y, const std::int16_t radius);

void opcontrol() {
    pros::screen::set_pen(COLOR_RED);
    pros::screen::fill_rect(5,5,240,200);
    // Fill a circlular area with radius of 100 in COLOR_BLUE
    pros::screen::set_pen(COLOR_BLUE);
    pros::screen::fill_circle(240, 200, 100);
}

Parameters
x	The x coordinate of the center of the circle
y	The y coordinate of the center of the circle
radius	Radius of the circle

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

Text Printing Functions ¶

print ¶

Print a formatted string to the screen, with a line and text style specifier.

void print(pros::text_format_e_t txt_fmt, const std::int16_t line, const char* text, Params... args);

void opcontrol() {
    int i = 0;

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

Parameters
txt_fmt	Text format enum that determines if the text is medium, large, medium_center, or large_center.
line	The one indexed line number on which to print
text	Formatted string for printing variables and text
…	Optional list of arguments for the format string

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

print ¶

Print a formatted string to the screen at a coordinate location

void print(pros::text_format_e_t txt_fmt, const std::int16_t x, const std::int16_t y, const char* text, Params... args);

void opcontrol() {
    int i = 0;

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

Parameters
txt_fmt	Text format enum that determines if the text is small, medium, or large.
x	The x-coordinate to display the string
y	The y-coordinate to display the string
text	Formatted string for printing variables and text
…	Optional list of arguments for the format string

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

Touch Related Functions ¶

touch_status ¶

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

screen_touch_status_s_t touch_status();

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

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

Returns: The screen_touch_status_s_t struct that indicates the last touch status of the screen.

touch_callback ¶

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.

void touch_callback(touch_event_cb_fn_t cb, last_touch_e_t event_type);

void changePixel() {
   pros::screen_touch_status_s_t status = pros::screen::touch_status();
   pros::screen::draw_pixel(status.x, status.y);
   printf("Touch callback executed!   x = %i, y = %i \n", status.x, status.y);
}

void opcontrol() {
   pros::Controller master(pros::E_CONTROLLER_MASTER);
   pros::Motor left_mtr(1);
   pros::Motor right_mtr(2);

   pros::screen::touch_callback(changePixel, TOUCH_PRESSED);
   while(1) {
      pros::delay(20);
   }
}

Parameters
cb	Function pointer to callback
event_type	The touch type for the callback to be triggered

Returns: 1 if the operation was successful or PROS_ERR if the operation failed, setting errno.

Enumerated Values ¶

pros::text_format_e_t ¶

Different font sizes that can be used in printing text.

typedef enum {
   E_TEXT_SMALL = 0,
   E_TEXT_MEDIUM,
   E_TEXT_LARGE,
   E_TEXT_MEDIUM_CENTER,
   E_TEXT_LARGE_CENTER
} text_format_e_t;

Value
E_TEXT_SMALL	Small text font size (Only available in coordinate printing)
E_TEXT_MEDIUM	Normal/Medium text font size
E_TEXT_LARGE	Large text font size
E_TEXT_MEDIUM_CENTER	Medium centered text (Only available in line printing)
E_TEXT_LARGE_CENTER	Large centered text (Only available in line printing)

—

pros::last_touch_e_t ¶

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

typedef enum {
   E_TOUCH_RELEASED = 0,
   E_TOUCH_PRESSED,
   E_TOUCH_HELD
} last_touch_e_t;

Value
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

—

Structures ¶

pros::screen_touch_status_s_t ¶

typedef struct screen_touch_status_s {
   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.
} screen_touch_status_s_t;

Typedefs ¶

pros::touch_event_cb_fn_t ¶

typedef void (*touch_event_cb_fn_t)();

A callback function for a screen callback

This will be called each time its corresponding touch type is happens.