/ 
Graphics-Framebuffer-4.1
River stage zero No dependents
/ Graphics::Framebuffer

NAME

Graphics::Framebuffer - A Simple Framebuffer Graphics Library

SYNOPSIS

use Graphics::Framebuffer;

my $fb = Graphics::Framebuffer->new();

$fb->cls();
$fb->set_color({'red' => 255, 'green' => 255, 'blue' => 255});
$fb->plot({'x' => 28, 'y' => 79,'pixel_size' => 1});
$fb->drawto({'x' => 405,'y' => 681,'pixel_size' => 1});
$fb->circle({'x' => 200, 'y' => 200, 'radius' => 100, 'filled' => 1});

$fb->close_screen();

DESCRIPTION

A (mostly) Pure Perl graphics library for exclusive use in a console framebuffer environment. It is written for simplicity without the need for complex API's and drivers.

Back in the old days, computers drew graphics this way, and it was simple and easy to do. I was writing a console based media playing program, and was not satisfied with the limited abilities offered by the Curses library, and I did not want the overhead of the X environment to get in the way. My intention was to create a mobile media server. In case you are wondering, that project has been quite successful, and I am still making improvements to it.

There are places where Pure Perl just won't cut it. So I use the Imager library to take up the slack. It's just used to load and save images, and draw TrueType text.

I cannot guarantee this will work on your video card, but I have successfully tested it on NVidia GeForce, AMD Radeon, Matrox, and VirtualBox displays. However, you MUST remember, your video driver MUST be framebuffer based. The proprietary Nvidia and AMD drivers will NOT work with this module. You must use the open source video drivers, such as Nouveau, to be able to use this library. Also, it is not going to work from within X, so don't even try it. This is a console only graphics library.

I highly suggest you use 32 bit mode and avoid 16 bit, as it has been a long time since I tested it on a 16 bit graphics mode.

NOTE:

If a framebuffer is not available, the module will go into emulation mode and open a pseudo-screen in the object's hash variable 'SCREEN'

You can write this to a file, whatever. It defaults to a 640x480x32 graphics 'buffer'. However, you can change that by passing parameters to the 'new' method.

You will not be able to see the output directly when in emulation mode. I mainly created this mode so that you could install this module and test code you may be writing to be used on other devices that have accessible framebuffer devices.

METHODS

new

This instantiates the framebuffer object

    my $fb = Graphics::Framebuffer->new(parameter => value);

PARAMETERS

FB_DEVICE
Framebuffer device name. Default is /dev/fb0
VXRES (Emulation Mode Only! Otherwise ignored.)
Width of the emulation framebuffer.  Default is 640.
VYRES (Emulation Mode Only! Otherwise ignored.)
Height of the emulation framebuffer.  Default is 480.
BITS (Emulation Mode Only! Otherwise ignored.)
Number of bits per pixel in the emulation framebuffer.
Default is 32.
BYTES (Emulation Mode Only! Otherwise ignored.)
Number of bytes per pixel in the emulation framebuffer.
It's best to keep it BITS/8.  Default is 4.

screen_close

Unmaps the SCREEN and closes the framebuffer. This is usually automatically called when the object is destroyed.

    $fb->screen_close();

screen_dimensions

Returns the size of the framebuffer in X,Y pixel values.

    my ($width,$height) = $fb->screen_dimensions();

draw_mode

Sets or returns the drawing mode, depending on how it is called.

    my $draw_mode = $fb->draw_mode();

$fb->draw_mode($fb->{'NORMAL_MODE'});
$fb->draw_mode($fb->{'XOR_MODE'});
$fb->draw_mode($fb->{'OR_MODE'});
$fb->draw_mode($fb->{'AND_MODE'});
$fb->draw_mode($fb->{'MASK_MODE'});

normal_mode

This is an alias to draw_mode($fb->{'NORMAL_MODE'})

    $fb->normal_mode();

xor_mode

This is an alias to draw_mode($fb->{'XOR_MODE'})

    $fb->xor_mode();

or_mode

This is an alias to draw_mode($fb->{'OR_MODE'})

    $fb->or_mode();

and_mode

This is an alias to draw_mode($fb->{'AND_MODE'})

    $fb->and_mode();

mask_mode

This is an alias to draw_mode($fb->{'MASK_MODE'})

    $fb->mask_mode();

clear_screen

Fills the entire screen with the background color

    $fb->clear_screen();

cls

The same as clear_screen

    $fb->cls();

attribute_reset

Resets the plot point at 0,0. Resets clipping to the current screen size. Resets the global color to white and resets the drawing mode to NORMAL.

    $fb->attribute_reset();

plot

Set a single pixel in the globally set color at position x,y with the given pixel size (or default). Clipping applies.

    $fb->plot({'x' => 20,'y' => 30, 'pixel_size' => 3});

drawto

Draws a line, in the global color, from the last plotted position to the position x,y. Clipping applies.

    $fb->drawto({
   'x' => 50,
   'y' => 60,
   'pixel_size' => 2
});

draw_arc

Draws an arc of a circle at point x,y.

    x             = x of center of circle
y             = y of center of circle
radius        = radius of circle
start_degrees = starting point, in degrees, of arc
end_degrees   = ending point, in degrees, of arc
granularity   = This is used for accuracy in drawing
                the arc.  The smaller the number, the
                more accurate the arc is drawn, but it
                is also slower.  Values between 0.1
                and 0.01 are usually good.
mode          = Specifies the drawing mode.
                 0 > arc only
                 1 > Filled pie section
                 2 > Poly arc.  Draws a line from x,y to the
                     beginning and ending arc position.

$fb->draw_arc({
   'x'             => 100,
   'y'             => 100,
   'radius'        => 100,
   'start_degrees' => -40,
   'end_degrees'   => 80,
   'grandularity   => .05,
   'mode'          => 2
});

ellipse

Draw an ellipse at center position x,y with XRadius, YRadius. Either a filled out outline is drawn based on the value of $filled. The optional factor value varies from the default 1 to change the look and nature of the output. Clipping Applies.

    $fb->ellipse({
   'x'          => 200,
   'y'          => 250,
   'xradius'    => 50,
   'yradius'    => 100,
   'filled'     => 0,
   'pixel_size' => 4
});

circle

A wrapper for 'ellipse'. I generally only needs x,y, and radius, but filled and pixel_size are also allowed.

    $fb->circle({
   'x'      => 300,
   'y'      => 300,
   'radius' => 100,
   'filled' => 1,
});

polygon

Creates an empty polygon drawn in the global color value. The parameter 'coordinates' is an array of x,y values. The last x,y combination is connected automatically with the first to close the polygon. All x,y values are absolute, not relative. Clipping applies.

    $fb->polygon({
   'coordinates' => [5,5,23,34,7,7],
   'pixel_size'  => 4
});

box

Draws a box from point x,y to point xx,yy, either as an outline, if 'filled' is 0, or as a filled block, if 'filled' is 1.

    $fb->box({
   'x'      => 20,
   'y'      => 50,
   'xx'     => 70,
   'yy'     => 100,
   'filled' => 1,
});

rbox

Draws a box at point x,y with the width 'width' and height 'height'. It draws a frame if 'filled' is 0 or a filled box if 'filled' is 1. 'pixel_size' only applies if 'filled' is 0.

    $fb->rbox({
   'x'          => 100,
   'y'          => 100,
   'width'      => 200,
   'height'     => 150,
   'filled'     => 0,
   'pixel_size' => 2
});

set_color

Sets the drawing color in red, green, and blue, absolute values.

    $fb->set_color({
   'red'   => 255,
   'green' => 255,
   'blue'  => 0
});

set_b_color

Sets the background color in red, green, and blue values.

    $fb->set_b_color({
   'red'   => 0,
   'green' => 0,
   'blue'  => 255
});

pixel

Returns the color of the pixel at coordinate x,y.

    my $pixel = $fb->pixel({'x' => 20,'y' => 25});

# $pixel is a hash reference in the form:
#
# {
#    'red'   => integer value, # 0 - 255
#    'green' => integer value, # 0 - 255
#    'blue'  => integer value, # 0 - 255
#    'raw'   => 32bit value
# }

fill

Does a flood fill starting at point x,y. It samples the color at that point and determines that color to be the "background" color, and proceeds to fill in, with the current global color, until the "background" color is replaced with the new color. Clipping applies.

BECAUSE OF ITS RECURSIVE NATURE, IT CAN CHOW DOWN ON MEMORY LIKE IT IS GOING OUT OF STYLE! Memory is restored when complete, but be prepared to see a lot disappear while it is running! This is a stack issue.

    $fb->fill({'x' => 334, 'y' => 23});

** Perhaps the memory issue could be avoided if somehow the flood fill would operate in blocks, instead of recurse until it can find no more to fill. My brain hurts thinking about it.

Maybe just a different fill algorithmn might be better.

replace_color

This replaces one color with another inside the clipping region. Sort of like a fill without boundary checking.

    $fb->replace_color({
   'old_red'   => 23,
   'old_green' => 48,
   'old_blue'  => 98,
   'new_red'   => 255,
   'new_green' => 255,
   'new_blue'  => 0
});

blit_copy

Copies a square portion of screen graphic data from x,y,w,h to x_dest,y_dest. It copies in the current drawing mode.

    $fb->blit_copy({
   'x'      => 20,
   'y'      => 20,
   'width'  => 30,
   'height' => 30,
   'x_dest' => 200,
   'y_dest' => 200
});

blit_read

Reads in a square portion of screen data at x,y,width,height, and returns the block of raw data as a string.

    my $blit_data = $fb->blit_read({
   'x'      => 30,
   'y'      => 50,
   'width'  => 100,
   'height' => 100
});

blit_write

Writes a previously read block of screen data at x,y,width,height.

    $fb->blit_write({
   'x'      => 0,
   'y'      => 0,
   'width'  => 100,
   'height' => 100,
   'image'  => $blit_data
});

clip_reset

Turns off clipping, and resets the clipping values to the full size of the screen.

    $fb->clip_reset();

clip_set

Sets the clipping rectangle starting at the top left point x,y and ending at bottom right point xx,yy.

    $fb->clip_set({
   'x' => 10,
   'y' => 10,
   'xx' => 300,
   'yy' => 300
});

clip_rset

Sets the clipping rectangle to point x,y,width,height

    $fb->clip_rset({
   'x'      => 10,
   'y'      => 10,
   'width'  => 600,
   'height' => 400
});

ttf_print

Prints TrueType text on the screen at point x,y in the rectangle width,height, using the color 'color', and the face 'face'.

This is best called twice, first in bounding box mode, and then in normal mode.

get_face_name

Returns the TrueType face name based on the parameters passed. It uses the exact same parameters as the ttf_print method.

load_image

Loads an image at point x,y[,width,height]

If 'width' and/or 'height' is given, the image is resized

screen_dump

Dumps the screen to a file given in 'file'. This is a RAW dump.

RGB_to_16

Converts 24 bit color values to 16 bit color values.

RGBA_to_16

Converts 32 bit color values to 16 bit

RGB_to_RGBA

Converts 24 bit color to 32 bit color

AUTHOR

Richard Kelsch <rich@rk-internet.com>

COPYRIGHT

Copyright 2013-2015 Richard Kelsch, All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

Version 4.10 (May 10, 2015)

THANKS

My thanks go out to those using this module and submitting helpful patches and suggestions for improvement:

Markus Maier