---
name: "bitmap"
section: "3caca"
platform: "linux"
package: "libcaca-dev"
version: "0.9-4"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/bitmap/3caca"
---

# bitmap(3caca)

## NAME

Bitmap handling -

### Functions

caca\_bitmap \* **caca\_create\_bitmap** (unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, unsigned int)\
 *Create an internal bitmap object.*  void **caca\_set\_bitmap\_palette** (struct caca\_bitmap \*, unsigned int r\[\], unsigned int g\[\], unsigned int b\[\], unsigned int a\[\])\
 *Set the palette of an 8bpp bitmap object.*  void **caca\_draw\_bitmap** (int, int, int, int, struct caca\_bitmap const \*, void \*)\
 *Draw a bitmap on the screen.*  void **caca\_free\_bitmap** (struct caca\_bitmap \*)\
 *Free the memory associated with a bitmap.*

## Detailed Description

These functions provide high level routines for bitmap allocation and rendering.

## Function Documentation

### struct caca\_bitmap\* caca\_create\_bitmap (unsigned int bpp, unsigned int w, unsigned int h, unsigned int pitch, unsigned int rmask, unsigned int gmask, unsigned int bmask, unsigned int amask)

Create a bitmap structure from its coordinates (depth, width, height and pitch) and pixel mask values. If the depth is 8 bits per pixel, the mask values are ignored and the colour palette should be set using the **caca\_set\_bitmap\_palette()** function. For depths greater than 8 bits per pixel, a zero alpha mask causes the alpha values to be ignored.

**Parameters:**

*bpp* Bitmap depth in bits per pixel. \
 *w* Bitmap width in pixels. \
 *h* Bitmap height in pixels. \
 *pitch* Bitmap pitch in bytes. \
 *rmask* Bitmask for red values. \
 *gmask* Bitmask for green values. \
 *bmask* Bitmask for blue values. \
 *amask* Bitmask for alpha values.

**Returns:**

Bitmap object, or NULL upon error.

### void caca\_draw\_bitmap (int x1, int y1, int x2, int y2, struct caca\_bitmap const \* bitmap, void \* pixels)

Draw a bitmap at the given coordinates. The bitmap can be of any size and will be stretched to the text area.

**Parameters:**

*x1* X coordinate of the upper-left corner of the drawing area. \
 *y1* Y coordinate of the upper-left corner of the drawing area. \
 *x2* X coordinate of the lower-right corner of the drawing area. \
 *y2* Y coordinate of the lower-right corner of the drawing area. \
 *bitmap* Bitmap object to be drawn. \
 *pixels* Bitmap's pixels.

### void caca\_free\_bitmap (struct caca\_bitmap \* bitmap)

Free the memory allocated by **caca\_create\_bitmap()**.

**Parameters:**

*bitmap* Bitmap object.

### void caca\_set\_bitmap\_palette (struct caca\_bitmap \* bitmap, unsigned int red\[\], unsigned int green\[\], unsigned int blue\[\], unsigned int alpha\[\])

Set the palette of an 8 bits per pixel bitmap. Values should be between 0 and 4095 (0xfff).

**Parameters:**

*bitmap* Bitmap object. \
 *red* Array of 256 red values. \
 *green* Array of 256 green values. \
 *blue* Array of 256 blue values. \
 *alpha* Array of 256 alpha values.