Fl_RGB_Image

RGB color image class with support for 1-4 channels

Overview

The Fl_RGB_Image class supports caching and drawing of full-color images with 1 to 4 channels of color information. Images with an even number of channels are assumed to contain alpha information, which is used to blend the image with the contents of the screen.

Header: <FL/Fl_RGB_Image.H> or <FL/Fl_Image.H>

Base Class: Fl_Image

Constructors

Fl_RGB_Image · constructor

Creates an RGB image from raw pixel data.

bits · const uchar*

Pointer to the image data array containing R, G, B [, A] values

W · int

Image width in pixels

H · int

Image height in pixels

D · int · default: "3"

Image depth (number of bytes per pixel):

• 1 = Grayscale
• 2 = Grayscale + Alpha
• 3 = RGB
• 4 = RGBA

LD · int · default: "0"

Line data size in bytes. If 0, assumed to be W * D. If non-zero, must be >= W * D to account for padding.

Fl_RGB_Image(const uchar *bits, int W, int H, int D = 3, int LD = 0);

Fl_RGB_Image · constructor

Creates an RGB image with explicit data length validation.

bits · const uchar*

Pointer to the image data array

bits_length · int

Length of the bits array in bytes (for validation)

W · int

Image width in pixels

H · int

Image height in pixels

D · int

Image depth (bytes per pixel)

LD · int

Line data size in bytes

Fl_RGB_Image(const uchar *bits, int bits_length, int W, int H, int D, int LD);

Fl_RGB_Image · constructor

Creates an RGB image from a pixmap.

pxm · const Fl_Pixmap*

Pointer to the source pixmap

bg · Fl_Color · default: "FL_GRAY"

Background color for transparent areas

Fl_RGB_Image(const Fl_Pixmap *pxm, Fl_Color bg = FL_GRAY);

Public Members

array · const uchar*

Points to the start of the object’s data array containing pixel values.

For Fl_SVG_Image subclass, this member variable initialization may be delayed.

alloc_array · int

If non-zero, the object’s data array is delete[]‘d when deleting the object. Set to 0 if the data is managed externally.

Image Operations

copy · Fl_Image* copy(int W, int H) const

Creates a copy of the image scaled to the specified dimensions.

W · int

Width of the copy

H · int

Height of the copy

Returns a new Fl_RGB_Image that should be released when done.

color_average · void color_average(Fl_Color c, float i)

Averages the image with the specified color.

c · Fl_Color

Color to average with

i · float

Intensity/blend factor (0.0 to 1.0)

desaturate · void desaturate()

Converts the RGB image to grayscale.

Drawing Methods

draw · void draw(int X, int Y, int W, int H, int cx = 0, int cy = 0)

Draws the image to the current drawing surface with a bounding box.

X · int

X coordinate of bounding box

Y · int

Y coordinate of bounding box

W · int

Width of bounding box

H · int

Height of bounding box

cx · int · default: "0"

X offset of image origin

cy · int · default: "0"

Y offset of image origin

draw · void draw(int X, int Y)

Draws the image at the specified position.

X · int

X coordinate for upper-left corner

Y · int

Y coordinate for upper-left corner

Cache Management

uncache · void uncache()

Releases cached platform-specific image data, freeing memory while keeping the image object.

cache_w · int cache_w()

Returns the width of the cached image data.

cache_h · int cache_h()

Returns the height of the cached image data.

Size Limits

max_size · static void max_size(size_t size)

Sets the maximum allowed image size in bytes when creating an Fl_RGB_Image object.

size · size_t

Maximum size in bytes (calculated as w() * h() * d())

The default max_size() value is essentially infinite. This does not apply to direct RGB image creation via the constructor.

max_size · static size_t max_size()

Returns the maximum allowed image size in bytes.

Type Detection

as_svg_image · Fl_SVG_Image* as_svg_image()

Returns a pointer to Fl_SVG_Image if this object is an instance of Fl_SVG_Image, or NULL otherwise.

normalize · void normalize()

Makes sure the object is fully initialized. In particular, ensures the array member variable is non-null.

Widget Integration

label · void label(Fl_Widget* w)

Sets this image as the label for a widget.

label · void label(Fl_Menu_Item* m)

Sets this image as the label for a menu item.

Example Usage

Creating RGB Image from Raw Data

// Create a 100x100 red square
int width = 100, height = 100;
uchar *data = new uchar[width * height * 3];

// Fill with red color (RGB = 255, 0, 0)
for (int i = 0; i < width * height * 3; i += 3) {
    data[i]   = 255;  // R
    data[i+1] = 0;    // G
    data[i+2] = 0;    // B
}

Fl_RGB_Image *img = new Fl_RGB_Image(data, width, height, 3);
img->alloc_array = 1; // Image will delete[] data when destroyed

// Display in a box
Fl_Box *box = new Fl_Box(10, 10, width, height);
img->label(box);

Creating RGBA Image with Alpha Channel

// Create a 50x50 semi-transparent blue square
int w = 50, h = 50;
uchar *rgba = new uchar[w * h * 4];

for (int i = 0; i < w * h * 4; i += 4) {
    rgba[i]   = 0;    // R
    rgba[i+1] = 0;    // G
    rgba[i+2] = 255;  // B
    rgba[i+3] = 128;  // A (50% transparent)
}

Fl_RGB_Image *img = new Fl_RGB_Image(rgba, w, h, 4);
img->alloc_array = 1;
img->draw(100, 100);

Converting Pixmap to RGB Image

// Load XPM data
const char *xpm_data[] = {
    "16 16 2 1",
    ". c #000000",
    "  c #FFFFFF",
    "................",
    // ... more lines
    NULL
};

Fl_Pixmap *pixmap = new Fl_Pixmap(xpm_data);
Fl_RGB_Image *rgb = new Fl_RGB_Image(pixmap, FL_WHITE);

// Now use rgb image
rgb->draw(10, 10);

delete pixmap;
delete rgb;

Image Manipulation

Fl_RGB_Image *img = new Fl_RGB_Image(data, 200, 200, 3);

// Create grayed-out version
Fl_RGB_Image *gray = (Fl_RGB_Image*)img->copy();
gray->desaturate();

// Create tinted version
Fl_RGB_Image *tinted = (Fl_RGB_Image*)img->copy();
tinted->color_average(FL_BLUE, 0.3);

// Scale image
img->scale(100, 100, 1); // Scale to 100x100, maintain aspect ratio

Memory Layout

The array data is organized as follows:

For D=3 (RGB):

[R][G][B][R][G][B][R][G][B]...

For D=4 (RGBA):

[R][G][B][A][R][G][B][A][R][G][B][A]...

For D=1 (Grayscale):

[Gray][Gray][Gray]...

With Line Data (LD):

If LD is specified and non-zero, each scanline has LD bytes instead of W * D bytes, with extra padding:

[Row 0: W*D bytes][Padding]...[Row 1: W*D bytes][Padding]...

See Also

• Fl_Image - Base image class
• Fl_Pixmap - XPM pixmap images
• Drawing Functions - Drawing API