---
name: "notcurses_pile"
section: "3"
platform: "linux"
package: "notcurses"
version: "3.0.17-3"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/notcurses_pile"
---

# notcurses\_pile(3)

operations on Notcurses piles

## NAME

notcurses\_pile - operations on Notcurses piles

## SYNOPSIS

**struct ncplane\* notcurses\_top(struct notcurses\*** *n***);**

**struct ncplane\* notcurses\_bottom(struct notcurses\*** *n***);**

**struct ncplane\* ncpile\_top(struct ncplane\*** *n***);**

**struct ncplane\* ncpile\_bottom(struct ncplane\*** *n***);**

## DESCRIPTION

Notcurses does not export the **ncpile** type, nor any functionality that uses it directly. Piles are nonetheless an important concept in Notcurses. Functions which operate on piles (e.g. **ncpile\_render(3)** are invoked with any **ncplane** within that pile.

Piles are collections of **ncplane**s, independent from one another for purposes of rendering and also thread-safety. While only one pile can be rasterized (written to the display) at a time, arbitrary concurrent actions can be safely performed on distinct piles. Piles do not compose: rasterizing a pile destroys any overlapping material.

A pile is created in one of three ways:

- •

  **ncpile\_create(3)** is called,

- •

  **ncvisual\_blit(3)** is called with a **NULL** target plane ***n***, or

- •

  **ncplane\_reparent(3)** is called with ***n*** equal to ***newparent***, and ***n*** is not already a root plane.

A pile is destroyed whenever its last **ncplane** is destroyed, or reparented into some other pile.

The planes of a pile are totally ordered along the z-axis. **ncpile\_top** and **ncpile\_bottom** return the topmost and bottommost planes, respectively, of the pile containing their argument. **notcurses\_top** and **notcurses\_bottom** do the same for the standard pile.

## NOTES

## BUGS

## SEE ALSO

**[notcurses(3)](/notcurses/3.md)**, **[notcurses\_plane(3)](/notcurses_plane/3.md)**, **[notcurses\_render(3)](/notcurses_render/3.md)**, **[notcurses\_visual(3)](/notcurses_visual/3.md)**

## AUTHORS

nick black ⟨nickblack@linux.com⟩\\c.