---
name: "notcurses_channels"
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_channels"
---

# notcurses\_channels(3)

operations on notcurses channels

## NAME

notcurses\_channels - operations on notcurses channels

## SYNOPSIS

**#include \<notcurses/notcurses.h\>**

-

  ```
  #define NCCHANNEL_INITIALIZER(r, g, b) \
    (((uint32_t)r << 16u) + ((uint32_t)g << 8u) + (b) + NC_BGDEFAULT_MASK)
  #define NCCHANNELS_INITIALIZER(fr, fg, fb, br, bg, bb) \
    ((NCCHANNEL_INITIALIZER(fr, fg, fb) << 32ull) + \
     (NCCHANNEL_INITIALIZER(br, bg, bb)))
  ```

**uint32\_t ncchannel\_r(uint32\_t** *channel***);**

**uint32\_t ncchannel\_g(uint32\_t** *channel***);**

**uint32\_t ncchannel\_b(uint32\_t** *channel***);**

**uint32\_t ncchannel\_rgb(uint32\_t** *channel***);**

**uint32\_t ncchannel\_rgb8(uint32\_t** *channel***,** **uint32\_t\* restrict** *r***, uint32\_t\* restrict** *g***, uint32\_t\* restrict** *b***);**

**int ncchannel\_set\_rgb8(uint32\_t\*** *channel***,** **unsigned** *r***, unsigned** *g***, unsigned** *b***);**

**int ncchannel\_set(uint32\_t\*** *channel***, uint32\_t** *rgb***);**

**uint32\_t ncchannel\_alpha(uint32\_t** *channel***);**

**int ncchannel\_set\_alpha(uint32\_t\*** *channel***,** **unsigned** *alpha***);**

**bool ncchannel\_default\_p(uint32\_t** *channel***);**

**uint32\_t ncchannel\_set\_default(uint32\_t\*** *channel***);**

**uint32\_t ncchannels\_fg\_rgb(uint64\_t** *channels***);**

**uint32\_t ncchannels\_bg\_rgb(uint64\_t** *channels***);**

**int ncchannels\_set\_fg\_rgb(uint64\_t\*** *channels***,** **uint32\_t** *rgb***);**

**int ncchannels\_set\_bg\_rgb(uint64\_t\*** *channels***,** **uint32\_t** *rgb***);**

**unsigned ncchannels\_fg\_alpha(uint64\_t** *channels***);**

**unsigned ncchannels\_bg\_alpha(uint64\_t** *channels***);**

**int ncchannels\_set\_fg\_alpha(uint64\_t\*** *channels***,** **int** *alpha***);**

**int ncchannels\_set\_bg\_alpha(uint64\_t\*** *channels***,** **int** *alpha***);**

**uint32\_t ncchannels\_fg\_rgb8(uint64\_t** *channels***,** **unsigned\*** *r***, unsigned\*** *g***,** **unsigned\*** *b***);**

**uint32\_t ncchannels\_bg\_rgb8(uint64\_t** *channels***,** **unsigned\*** *r***, unsigned\*** *g***,** **unsigned\*** *b***);**

**int ncchannels\_set\_fg\_rgb8(uint64\_t\*** *channels***,** **unsigned** *r***, unsigned** *g***, unsigned** *b***);**

**int ncchannels\_set\_bg\_rgb8(uint64\_t\*** *channels***,** **unsigned** *r***, unsigned** *g***, unsigned** *b***);**

**bool ncchannels\_fg\_default\_p(uint64\_t** *channels***);**

**bool ncchannels\_bg\_default\_p(uint64\_t** *channels***);**

**uint64\_t ncchannels\_set\_fg\_default(uint64\_t\*** *channels***);**

**uint64\_t ncchannels\_set\_bg\_default(uint64\_t\*** *channels***);**

**uint64\_t ncchannels\_reverse(uint64\_t** *channels***);**

**unsigned ncchannel\_palindex(uint32\_t** *channel***);**

**bool ncchannel\_palindex\_p(uint32\_t** *channel***);**

**int ncchannel\_set\_palindex(uint32\_t\*** *channel***,** **unsigned** *idx***);**

**unsigned ncchannels\_fg\_palindex(uint64\_t** *channels***);**

**unsigned ncchannels\_bg\_palindex(uint64\_t** *channels***);**

**int ncchannels\_set\_fg\_palindex(uint64\_t\*** *channels***, unsigned** *idx***);**

**int ncchannels\_set\_bg\_palindex(uint64\_t\*** *channels***, unsigned** *idx***);**

**uint64\_t ncchannels\_set\_channels(uint64\_t\*** *dst***,** **uint64\_t** *channels***);**

**uint64\_t ncchannels\_channels(uint64\_t** *channels***);**

**uint64\_t ncchannels\_combine(uint32\_t** *fchan***,** **uint32\_t** *bchan***);**

## DESCRIPTION

Channels ought not be manually manipulated. They contain several bits used "behind the scenes", and e.g. direct assignment is likely to lead to strange and infrequent failures. To assign one channel pair to another, use **ncchannels\_set\_channels**. To assign a channel to a channel pair's foreground, use **ncchannels\_set\_fchannel**. To assign a channel to a channel pair's background, use **ncchannels\_set\_bchannel**.

**ncchannel\_palindex** extracts the palette index from a channel. The channel must be palette-indexed, or the return value is meaningless. Verify palette indexing with **ncchannel\_palindex\_p**. A channel can be set to palette indexed mode (and have the index set) with **ncchannel\_set\_palindex**. The index must be less than **NCPALETTESIZE**.

**ncchannels\_combine** creates a new channel pair using ***fchan*** as the foreground channel and ***bchan*** as the background channel.

## RETURN VALUES

Functions returning **int** return -1 on failure, or 0 on success. Failure is always due to invalid inputs. Functions returning **bool** are predicates, and return the requested value. Functions returning **unsigned** forms return the input, modified as requested.

**ncchannels\_reverse** inverts the color components of the two channels, while holding all other elements constant. It's the Notcurses approximation to reverse video.

## SEE ALSO

**[notcurses(3)](/notcurses/3.md)**, **[notcurses\_cell(3)](/notcurses_cell/3.md)**, **[notcurses\_plane(3)](/notcurses_plane/3.md)**, **[notcurses\_output(3)](/notcurses_output/3.md)**

## AUTHORS

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