Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Marcussacapuces91/doc-TFT_eSPI/llms.txt

Use this file to discover all available pages before exploring further.

TFT_eSPI version 2.x introduced a viewport/clipping system (signalled by TFT_ESPI_FEATURES bit 0 being set) that lets you constrain all drawing operations to a rectangular sub-region of the display. Any pixel written outside the viewport is silently discarded with no performance penalty. Below the viewport layer is the address-window layer — raw hardware window commands that set the pixel RAM pointer before a burst write. Both layers are documented here, along with helper functions for checking whether a rectangle intersects the current viewport and for drawing a coloured border around it.

​
setViewport() — Define the Active Clipping Region

void setViewport(int32_t x, int32_t y, int32_t w, int32_t h, bool vpDatum = true)
Restricts all subsequent drawing operations to the rectangular region defined by (x, y, w, h). Pixels drawn outside this region are discarded. When vpDatum is true the coordinate origin (0, 0) is relocated to the top-left corner of the viewport, so you can write self-contained widget code that always draws from (0, 0).
​
x
int32_t
X position of the viewport top-left corner in screen coordinates.
​
y
int32_t
Y position of the viewport top-left corner in screen coordinates.
​
w
int32_t
Viewport width in pixels.
​
h
int32_t
Viewport height in pixels.
​
vpDatum
bool
When true (default), drawing coordinates are relative to the viewport top-left corner — (0, 0) maps to the viewport origin. When false, screen coordinates are used but drawing outside the viewport is still clipped.
// Restrict drawing to the top-left 160×120 quarter
tft.setViewport(0, 0, 160, 120);
tft.fillScreen(TFT_NAVY);    // only fills the viewport
tft.drawRect(0, 0, 160, 120, TFT_WHITE); // border at viewport edge

// Two independent "panels" with datum-relative coordinates
tft.setViewport(0,   0,   160, 240, true);
drawWidget();   // draws from (0,0) = screen (0,0)

tft.setViewport(160, 0,   160, 240, true);
drawWidget();   // same code, draws from (0,0) = screen (160,0)

tft.resetViewport();
With vpDatum = true, each widget or panel can be coded assuming (0, 0) is its own top-left corner — simply reposition the viewport before calling the draw routine.

​
resetViewport() — Remove Viewport Clipping

void resetViewport(void)
Resets the viewport to the full display area and clears the datum offset. After calling this function drawing operations span the entire screen again. 
tft.resetViewport();
tft.fillScreen(TFT_BLACK); // clears the whole screen

​
checkViewport() — Test Rectangle Intersection

bool checkViewport(int32_t x, int32_t y, int32_t w, int32_t h)
Returns true if the rectangle (x, y, w, h) intersects the current viewport. Useful for early-exit optimizations in render loops — if the target bounding box does not intersect the viewport, the draw call can be skipped entirely.
​
x
int32_t
X coordinate of the test rectangle (screen or viewport-relative, consistent with the current datum setting).
​
y
int32_t
Y coordinate of the test rectangle.
​
w
int32_t
Width of the test rectangle.
​
h
int32_t
Height of the test rectangle.
Returns: bool — true if the rectangle overlaps the viewport; false otherwise. 
if (tft.checkViewport(spriteX, spriteY, spriteW, spriteH)) {
  sprite.pushSprite(spriteX, spriteY);
}

​
getViewportX() / getViewportY() — Read Viewport Position

int32_t getViewportX(void)
int32_t getViewportY(void)
Return the screen-coordinate position of the viewport’s top-left corner. Returns: int32_t — viewport X or Y position in screen pixels.

​
getViewportWidth() / getViewportHeight() — Read Viewport Size

int32_t getViewportWidth(void)
int32_t getViewportHeight(void)
Return the current viewport width and height. Returns: int32_t — viewport width or height in pixels. 
int32_t vw = tft.getViewportWidth();
int32_t vh = tft.getViewportHeight();
tft.drawRect(0, 0, vw, vh, TFT_RED); // border around current viewport

​
getViewportDatum() — Read Datum Setting

bool getViewportDatum(void)
Returns the vpDatum flag set by the last setViewport() call. Returns: bool — true if coordinates are relative to the viewport origin; false for screen coordinates.

​
frameViewport() — Draw a Border Around the Viewport

void frameViewport(uint16_t color, int32_t w)
Draws a coloured rectangular border of width w pixels along the inner edge of the current viewport. This is a convenience function equivalent to drawing four filled rectangles at the viewport perimeter.
​
color
uint16_t
Border colour (RGB565 or TFT_* constant).
​
w
int32_t
Border thickness in pixels.
tft.setViewport(20, 20, 200, 150);
tft.fillScreen(TFT_DARKGREY);
tft.frameViewport(TFT_WHITE, 2); // 2-pixel white border

​
setWindow() — Set Hardware Pixel RAM Window

void setWindow(int32_t xs, int32_t ys, int32_t xe, int32_t ye)
Sets the display controller’s pixel address window using start and end (inclusive) coordinates. After calling this, pixel data can be streamed with pushColor(), pushColors(), or pushBlock(). This is a virtual method overridden by each driver.
​
xs
int32_t
Start X coordinate (top-left, inclusive).
​
ys
int32_t
Start Y coordinate (top-left, inclusive).
​
xe
int32_t
End X coordinate (bottom-right, inclusive).
​
ye
int32_t
End Y coordinate (bottom-right, inclusive).
tft.startWrite();
tft.setWindow(0, 0, 239, 319); // full screen window on a 240×320 display
for (int i = 0; i < 240 * 320; i++) {
  tft.pushColor(TFT_BLACK);
}
tft.endWrite();
setWindow() uses inclusive end coordinates. If you have a width and height, use setAddrWindow() instead.

​
setAddrWindow() — Set Hardware Window (Width/Height Form)

void setAddrWindow(int32_t xs, int32_t ys, int32_t w, int32_t h)
Like setWindow() but takes a width and height instead of end coordinates, matching the convention used by most higher-level drawing calls.
​
xs
int32_t
Start X coordinate.
​
ys
int32_t
Start Y coordinate.
​
w
int32_t
Window width in pixels.
​
h
int32_t
Window height in pixels.
tft.startWrite();
tft.setAddrWindow(10, 10, 100, 80);
tft.pushColors(imageData, 100 * 80, true);
tft.endWrite();

​
clipAddrWindow() — Clip Window to Display Bounds

bool clipAddrWindow(int32_t *x, int32_t *y, int32_t *w, int32_t *h)
Clips a width/height-form window to the display boundaries, modifying the values in place. Returns false if the clipped window has zero or negative area (i.e. the window is entirely off-screen), in which case the caller should skip the draw operation.
​
x
int32_t *
Pointer to the X start coordinate; modified in place.
​
y
int32_t *
Pointer to the Y start coordinate; modified in place.
​
w
int32_t *
Pointer to the width; modified in place.
​
h
int32_t *
Pointer to the height; modified in place.
Returns: bool — true if the clipped window has a non-zero area; false if it is entirely off-screen. 
int32_t x = -10, y = 5, w = 60, h = 40;
if (tft.clipAddrWindow(&x, &y, &w, &h)) {
  tft.setAddrWindow(x, y, w, h);
  // push pixels ...
}

​
clipWindow() — Clip Window to Display Bounds (End-Coordinate Form)

bool clipWindow(int32_t *xs, int32_t *ys, int32_t *xe, int32_t *ye)
Like clipAddrWindow() but operates on inclusive end-coordinate pairs (xs, ys) to (xe, ye). Modifies the coordinates in place and returns false if the result is degenerate.
​
xs
int32_t *
Pointer to the start X; modified in place.
​
ys
int32_t *
Pointer to the start Y; modified in place.
​
xe
int32_t *
Pointer to the end X (inclusive); modified in place.
​
ye
int32_t *
Pointer to the end Y (inclusive); modified in place.
Returns: bool — true if the clipped window is valid; false if entirely off-screen. 
int32_t xs = 200, ys = 100, xe = 280, ye = 200;
if (tft.clipWindow(&xs, &ys, &xe, &ye)) {
  tft.setWindow(xs, ys, xe, ye);
  // stream pixels ...
}

Build docs developers (and LLMs) love

Get started for freeTalk to us