> For the complete documentation index, see [llms.txt](https://guide.cronuszen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.cronuszen.com/gpcscripting/gpc-script-guide/reference/additional-built-ins/oled-display-built-ins.md).
# OLED display built-ins
The Zen OLED is 128 × 64 monochrome pixels. Valid coordinates are X `0..127` and Y `0..63`.
{% hint style="warning" %}
Draw only when a screen or value changes. Repeated full-screen work in every VM cycle can make the script unresponsive.
{% endhint %}
***
#### `cls_oled`
Fills the complete display with one color.
**Syntax**
```gpc
cls_oled(color);
```
**Parameters**
* `color`: `OLED_BLACK` (`0`) or `OLED_WHITE` (`1`).
**Returns**
Nothing.
**Example**
{% code title="cls-oled.gpc" %}
```gpc
init {
cls_oled(OLED_BLACK);
}
```
{% endcode %}
***
#### `pixel_oled`
Sets one pixel.
**Syntax**
```gpc
pixel_oled(x, y, color);
```
**Parameters**
* `x`: `0..127`.
* `y`: `0..63`.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
**Returns**
Nothing.
**Example**
{% code title="pixel-oled.gpc" %}
```gpc
int oled_dirty = TRUE;
main {
if(oled_dirty) {
cls_oled(OLED_BLACK);
pixel_oled(64, 32, OLED_WHITE);
oled_dirty = FALSE;
}
}
```
{% endcode %}
***
#### `line_oled`
Draws a line between two points.
**Syntax**
```gpc
line_oled(x, y, to_x, to_y, thickness, color);
```
**Parameters**
* `x`, `to_x`: `0..127`.
* `y`, `to_y`: `0..63`.
* `thickness`: `1..127`.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
**Returns**
Nothing.
**Example**
{% code title="line-oled.gpc" %}
```gpc
init {
cls_oled(OLED_BLACK);
line_oled(0, 63, 127, 0, 1, OLED_WHITE);
}
```
{% endcode %}
***
#### `rect_oled`
Draws a rectangle outline or a filled rectangle.
**Syntax**
```gpc
rect_oled(x, y, width, height, fill, color);
```
**Parameters**
* `x`: `0..127`.
* `y`: `0..63`.
* `width`: `1..128`.
* `height`: `1..64`.
* `fill`: `TRUE` for filled or `FALSE` for outline.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
**Returns**
Nothing.
**Example**
{% code title="rect-oled.gpc" %}
```gpc
init {
cls_oled(OLED_BLACK);
rect_oled(4, 4, 120, 56, FALSE, OLED_WHITE);
}
```
{% endcode %}
Keep the full rectangle within the display: `x + width <= 128` and `y + height <= 64`.
***
#### `circle_oled`
Draws a circle outline or a filled circle.
**Syntax**
```gpc
circle_oled(x, y, radius, fill, color);
```
**Parameters**
* `x`: center X, `0..127`.
* `y`: center Y, `0..63`.
* `radius`: `1..63`.
* `fill`: `TRUE` or `FALSE`.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
**Returns**
Nothing.
**Example**
{% code title="circle-oled.gpc" %}
```gpc
init {
cls_oled(OLED_BLACK);
circle_oled(64, 32, 18, TRUE, OLED_WHITE);
}
```
{% endcode %}
Choose a center and radius that do not push the intended drawing outside the screen.
***
#### `putc_oled`
Writes one ASCII or glyph byte into the OLED text buffer. It does not draw until `puts_oled` is called.
**Syntax**
```gpc
putc_oled(position, ascii_code);
```
**Parameters**
* `position`: buffer position `1..18` on the current 32-bit target.
* `ascii_code`: supported byte `32..136`.
**Returns**
Nothing.
**Example**
{% code title="putc-oled.gpc" %}
```gpc
init {
putc_oled(1, ASCII_UPPER_H);
putc_oled(2, ASCII_UPPER_I);
}
```
{% endcode %}
***
#### `puts_oled`
Draws buffered characters using a built-in OLED font.
**Syntax**
```gpc
puts_oled(x, y, font, length, color);
```
**Parameters**
* `x`: `0..127`.
* `y`: `0..63`.
* `font`: `OLED_FONT_SMALL`, `OLED_FONT_MEDIUM`, or `OLED_FONT_LARGE`.
* `length`: `1..18` on the current 32-bit target.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
**Returns**
Nothing.
**Example**
{% code title="puts-oled.gpc" %}
```gpc
init {
cls_oled(OLED_BLACK);
putc_oled(1, ASCII_UPPER_H);
putc_oled(2, ASCII_UPPER_I);
puts_oled(8, 8, OLED_FONT_MEDIUM, 2, OLED_WHITE);
}
```
{% endcode %}
The large font cannot render every special glyph. Compile and device-test the selected byte and font combination.
***
#### `image_oled`
Draws a packed monochrome const image record.
**Syntax**
```gpc
image_oled(x, y, color, clear_background, image_address);
```
**Parameters**
* `x`: `0..127`.
* `y`: `0..63`.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
* `clear_background`: `TRUE` to clear the image rectangle before drawing.
* `image_address`: `addr(ImageName)` or a valid image-row address.
**Returns**
Nothing.
**Example**
{% code title="image-oled.gpc" %}
```gpc
const image FRAME_ICON = {
8, 8,
0xFF, 0x81, 0x81, 0x81,
0x81, 0x81, 0x81, 0xFF
};
init {
cls_oled(OLED_BLACK);
image_oled(60, 28, OLED_WHITE, TRUE, addr(FRAME_ICON));
}
```
{% endcode %}
The data begins with width and height, followed by exactly `ceil(width * height / 8)` packed pixel bytes.
***
#### `print`
Draws a const string using a built-in font. `print` is the current 32-bit name; `printf` is retained only as a deprecated compatibility alias.
**Syntax**
```gpc
print(x, y, font, color, string_address);
```
**Parameters**
* `x`: `0..127`.
* `y`: `0..63`.
* `font`: `OLED_FONT_SMALL`, `OLED_FONT_MEDIUM`, or `OLED_FONT_LARGE`.
* `color`: `OLED_BLACK` or `OLED_WHITE`.
* `string_address`: `addr(StringName)` or a valid string-row address.
**Returns**
Nothing.
**Example**
{% code title="print.gpc" %}
```gpc
const string READY_TEXT = "READY";
int oled_dirty = TRUE;
main {
if(oled_dirty) {
cls_oled(OLED_BLACK);
print(30, 22, OLED_FONT_MEDIUM, OLED_WHITE, addr(READY_TEXT));
oled_dirty = FALSE;
}
}
```
{% endcode %}
Use a declared const string; a bare string literal is not a runtime address argument.
***
#### Custom button badge
{% code title="button-badge.gpc" %}
```gpc
int oled_dirty = TRUE;
main {
if(oled_dirty) {
cls_oled(OLED_BLACK);
circle_oled(64, 32, 12, TRUE, OLED_WHITE);
putc_oled(1, ASCII_UPPER_A);
puts_oled(61, 27, OLED_FONT_SMALL, 1, OLED_BLACK);
oled_dirty = FALSE;
}
}
```
{% endcode %}
This builds a reusable visual button from a circle and one buffered character. Keep drawing separate from menu state mutation so viewing a page cannot accidentally change or save settings.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://guide.cronuszen.com/gpcscripting/gpc-script-guide/reference/additional-built-ins/oled-display-built-ins.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.