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->polygon({'coordinates' => [20,20, 53,3, 233,620], 'pixel_size' => 5});
$fb->box({'x' => 95, 'y' => 100, 'xx' => 400, 'yy' => 600, 'filled' => 1});
$fb->close_screen();DESCRIPTION
A (mostly) Pure Perl graphics library for exclusive use in a Unix console framebuffer environment. It is written for simplicity, without the need for complex API's and drivers with "surfaces" and such.
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. I may even include it in the "examples" directory on future versions.
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 images,, save images, and draw TrueType/Type1 text.
I cannot guarantee this will work on your video card, but I have successfully tested it on NVidia GeForce, AMD Radeon, Matrox, Raspberry PI, Odroid XU3,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 (with output to see). Also, it is not going to work from within X, so don't even try it, it will either crash X, or make a mess on the screen. This is a console only graphics library.
I highly suggest you use 32 bit mode and avoid 16 bit, as the routines are optimized for 32 bit.
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 (on systems without a framebuffer) and test code you may be writing to be used on other devices that have accessible framebuffer devices.
Make sure you have read/write access to the framebuffer device. Usually this just means adding your account to the "video" group. Alternately, you can just run your script as root. Although I don't recommend it.
METHODS
new
This instantiates the framebuffer object
my $fb = Graphics::Framebuffer->new(parameter => value);
PARAMETERS
- FB_DEVICE [/dev/fb0]
-
Framebuffer device name. - FILE_MODE [1 or 0]
-
Sets the internal drawing system to use file handle mode instead of memory mapped mode. File mode is more stable, but a bit slower. I recommend doing this ONLY if you are having issues with memory mapped mode. - MALI [1 or 0]
-
Forces the drawing engine to ignore some of the data returned by the driver, and do a sensible calculation for drawing parameters. This is usually required for ARM MALI GPUs (Hardkernel's Odroid XU3 for example). It gives a correct calculation of internal variables: (Assuming your object variable is $fb) $fb->{'BYTES_PER_LINE'} $fb->{'PIXELS'} $fb->{'BYTES'} $fb->{'smem_len'} This also means, that if drawing looks funky, then perhaps adjusting these internal variables AFTER the object is created, can fix your issue. - FOREGROUND
-
Sets the default foreground color for when 'attribute_reset' is called. It is in the same format as "set_color" expects:
{ # This is the default value 'red' => 255, 'green' => 255, 'blue' => 255, 'alpha' => 255 } =item B< BACKGROUND >Sets the default background color for when 'attribute_reset' is called. It is in the same format as "set_b_color" expects:
{ # This is the default value 'red' => 0, 'green' => 0, 'blue' => 0, 'alpha' => 0 } - SPLASH
-
The splash screen is or is not displayed
A true value turns it on (default) A false value turns it off
- FONT_PATH
-
Overrides the default font path for TrueType/Type1 fonts
If 'ttf_print' is not displaying any text, then this may need to be overridden.
- FONT_FACE
-
Overrides the default font filename for TrueType/Type 1 fonts.
If 'ttf_print' is not displaying any text, then this may need to be overridden.
- SHOW_ERRORS
-
Normally this module is completely silent and does not display errors or warnings (to the best of its ability). This is to prevent corruption of the graphics. However, you can enable error reporting by setting this to 1.
- 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();
splash
Displays the Splash screen. It automatically scales and positions to the clipping region.
This is automatically displayed when this module is initialized, and the variable 'SPLASH' is true (which is the default).
$fb->splash();draw_mode
Sets or returns the drawing mode, depending on how it is called.
my $draw_mode = $fb->draw_mode(); # Returns the current
# Drawing mode.
# Modes explained. These settings are global
# When you draw it...
$fb->draw_mode($fb->{'NORMAL_MODE'}); # Replaces the screen pixel
# with the new pixel.
$fb->alpha_mode($fb->{'ALPHA_MODE'}); # Like OR mode, but uses the
# alpha value on the source
# before writing. (SLOW)
$fb->draw_mode($fb->{'XOR_MODE'}); # Does a bitwise XOR with
# the new pixel and screen
# pixel.
$fb->draw_mode($fb->{'OR_MODE'}); # Does a bitwise OR with
# the new pixel and screen
# pixel.
$fb->draw_mode($fb->{'AND_MODE'}); # Does a bitwise AND with
# the new pixel and screen
# pixel.
$fb->draw_mode($fb->{'MASK_MODE'}); # Draws the new pixel on
# screen areas not equal to
# the background color. (SLOW)
$fb->draw_mode($fb->{'UNMASK_MODE'}); # Draws the new pixel on
# screen areas only equal to
# the background color. (SLOW)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();unmask_mode
This is an alias to draw_mode($fb->{'UNMASK_MODE'})
$fb->unmask_mode();alpha_mode
This is an alias to draw_mode($fb->{'ALPHA_MODE'})
$fb->alpha_mode();clear_screen
Fills the entire screen with the background color
You can add an optional parameter to turn the console cursor on or off too.
$fb->clear_screen(); # Leave cursor as is.
$fb->clear_screen('OFF'); # Turn cursor OFF.
$fb->clear_screen('ON'); # Turn cursor ON.
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 whatever 'FOREGROUND' is set to, and the global background color to whatever 'BACKGROUND' is set to, and resets the drawing mode to NORMAL.
$fb->attribute_reset();
reset
The same as 'attribute_reset'.
$fb->reset();
plot
Set a single pixel in the globally set color at position x,y with the given pixel size (or default). Clipping applies.
'pixel_size', if a positive number greater than 1, is drawn with square pixels. If it's a negative number, then it's drawn with round pixels. Square pixels are much faster.
$fb->plot( { 'x' => 20, 'y' => 30, 'pixel_size' => 3 } );
line
Draws a line, in the global color, from point x,y to point xx,yy. Clipping applies.
$fb->line({
'x' => 50,
'y' => 60,
'xx' => 100,
'yy' => 332
'pixel_size' => 3
});angle_line
Draws a line, in the global foregrounde color, from point x,y at an angle of 'angle', of length 'radius'. Clipping applies.
$fb->angle_line({
'x' => 50,
'y' => 60,
'radius' => 50,
'angle' => 30.3,
'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
});cubic_bezier
Draws a Cubic Bezier curve, based on four control points.
x0,y0 is the beginning point. x3,y3 is the ending point. x1,y1 & x2,y2 are the curve direction points.
$fb->cubic_bezier(
{
'coordinates' => [
x0,y0,
x1,y1,
x2,y2,
x3,y3
],
'pixel_size' => 2
}
);draw_arc
Draws an arc/pie/poly 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. Valid values
are any positive floating point number
down to 0.0001. Anything smaller than
that is just silly.
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 # The object hash has 'ARC', 'PIE',
# and 'POLY_ARC' as a means of filling
# this value.
});arc
Draws an arc of a circle at point x,y. This is an alias to draw_arc above, but no mode parameter needed.
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. Valid values
are any positive floating point number
down to 0.0001.
$fb->arc({
'x' => 100,
'y' => 100,
'radius' => 100,
'start_degrees' => -40,
'end_degrees' => 80,
'grandularity => .05,
});filled_pie
Draws a filled pie wedge at point x,y. This is an alias to draw_arc above, but no mode parameter needed.
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. Valid values
are any positive floating point number
down to 0.0001.
$fb->filled_pie({
'x' => 100,
'y' => 100,
'radius' => 100,
'start_degrees' => -40,
'end_degrees' => 80,
'grandularity => .05,
});poly_arc
Draws a poly arc of a circle at point x,y. This is an alias to draw_arc above, but no mode parameter needed.
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. Valid values
are any positive floating point number
down to 0.0001.
$fb->poly_arc({
'x' => 100,
'y' => 100,
'radius' => 100,
'start_degrees' => -40,
'end_degrees' => 80,
'grandularity => .05,
});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.
$fb->ellipse({
'x' => 200,
'y' => 250,
'xradius' => 50,
'yradius' => 100,
'factor' => 1, # Anything other than 1 has funkiness
'filled' => 1, # optional
'pixel_size' => 4, # optional
'gradient' => { # optional
'start' => {
'red' => 128,
'green' => 59,
'blue' => 0
},
'end' => {
'red' => 0,
'green' => 0,
'blue' => 255
}
}
});circle
A wrapper for 'ellipse'. It generally only needs x,y, and radius, but filled, gradient, and pixel_size are also allowed.
$fb->circle({
'x' => 300,
'y' => 300,
'radius' => 100,
'filled' => 1, # optional
'gradient' => { # optional
'start' => {
'red' => 128,
'green' => 59,
'blue' => 0
},
'end' => {
'red' => 0,
'green' => 0,
'blue' => 255
}
}
});polygon
Creates a polygon drawn in the global color value. The parameter 'coordinates' is a reference to 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.
It is up to you to make sure the coordinates are "sane". Weird things can result from twisted or complex filled polygons.
$fb->polygon({
'coordinates' => [
5,5,
23,34,
70,7
],
'pixel_size' => 1, # optional
'filled' => 1, # optional
'gradient' => { # optional
'start' => {
'red' => 128,
'green' => 59,
'blue' => 0
},
'end' => {
'red' => 0,
'green' => 0,
'blue' => 255
}
}
});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. Filled boxes draw faster than frames. You may also add gradient.
$fb->box({
'x' => 20,
'y' => 50,
'xx' => 70,
'yy' => 100,
'rounded' => 0, # optional
'filled' => 1, # optional
'pixel_size' => 1, # optional
'gradient' => { # optional
'start' => {
'red' => 128,
'green' => 59,
'blue' => 0
},
'end' => {
'red' => 0,
'green' => 0,
'blue' => 255
}
}
});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. Filled boxes draw faster than frames. Gradients are also allowed.
$fb->rbox({
'x' => 100,
'y' => 100,
'width' => 200,
'height' => 150,
'filled' => 0, # optional
'rounded' => 0, # optional
'pixel_size' => 2, # optional
'gradient' => { # optional
'start' => {
'red' => 128,
'green' => 59,
'blue' => 0
},
'end' => {
'red' => 0,
'green' => 0,
'blue' => 255
}
}
});set_color
Sets the drawing color in red, green, and blue, absolute 8 bit values.
Even if you are in 16 bit color mode, use 8 bit values. They will be automatically scaled.
$fb->set_color({
'red' => 255,
'green' => 255,
'blue' => 0
});set_foreground_color
Sets the drawing color in red, green, and blue, absolute values. This is the same as 'set_color' above.
$fb->set_foreground_color({
'red' => 255,
'green' => 255,
'blue' => 0
});set_b_color
Sets the background color in red, green, and blue values.
The same rules as set_color apply.
$fb->set_b_color({
'red' => 0,
'green' => 0,
'blue' => 255
});set_background_color
Same as set_b_color
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
# }get_pixel
Returns the color of the pixel at coordinate x,y. It is the same as 'pixel' above.
my $pixel = $fb->get_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' => 32/24/16 bit value (depending on
# mode)
# }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.
$fb->fill({'x' => 334, 'y' => 23});replace_color
This replaces one color with another inside the clipping region. Sort of like a fill without boundary checking. If you have clipping reset (off), then this is VERY FAST.
$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.
Supports video card acceleration. If acceleration is not working and preventing this from working properly, then call 'acceleration_disable' and it should work.
$fb->blit_copy({
'x' => 20,
'y' => 20,
'width' => 30,
'height' => 30,
'x_dest' => 200,
'y_dest' => 200
});acceleration_disable
Disables all hardware acceleration. Only needed if blit_copy is not working.
blit_read
Reads in a square portion of screen data at x,y,width,height, and returns a hash reference with information about the block, including the raw data as a string.
my $blit_data = $fb->blit_read({
'x' => 30,
'y' => 50,
'width' => 100,
'height' => 100
});Returns:
{
'x' => original X position,
'y' => original Y position,
'width' => width,
'height' => height,
'image' => string of image data for the block
}blit_write
Writes a previously read block of screen data at x,y,width,height.
It takes a hash reference. It draws in the current drawing mode. Note, the "Mask" modes are slower.
$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_off
Turns off clipping, and resets the clipping values to the full size of the screen. It is the same as clip_reset.
$fb->clip_off();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
});monochrome
Removes all color information from an image, and leaves everything in greyscale.
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'.
Note, 'y' is the baseline position, not the top left of the bounding box. This is a change from before!!!
This is best called twice, first in bounding box mode, and then in normal mode.
Bounding box mode gets the actual values needed to display the text.
my $bounding_box = $fb->ttf_print({
'x' => 20,
'y' => 100, # baseline position
'height' => 16,
'color' => 'FFFF00', # Yellow
'text' => 'Hello World!',
'font_path' => '/usr/share/fonts/truetype',
'face' => 'Arial.ttf',
'bounding_box' => 1,
'center' => $fb->{'CENTER_X'},
'antialias' => 1
});
$fb->ttf_print($bounding_box);Here's a shortcut:
$fb->ttf_print(
$fb->ttf_print({
'x' => 20,
'y' => 100, # baseline position
'height' => 16,
'color' => 'FFFF00', # Yellow
'text' => 'Hello World!',
'font_path' => '/usr/share/fonts/truetype',
'face' => 'Arial.ttf',
'bounding_box' => 1,
'center' => $fb->{'CENTER_X'},
'antialias' => 1
})
);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], and "draws" it in the current drawing mode.
If 'width' and/or 'height' is given, the image is resized. If only 'width' or 'height' is given, but not both, then the sizing is automatically proportional.
$fb->load_image(
{
'x' => 20,
'y' => 20,
'width' => 1920, # optional
'height' => 1080, # optional
'file' => 'boing.jpg' # Needs full path
}
);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. There is only one parameter, 'color' and it must contain a bit encoded 24 bit string. It returns 'color' converted to an encoded 16 bit string.
RGBA_to_16
Converts 32 bit color values to 16 bit color values. There is only one parameter, 'color' and it must contain a bit encoded 32 bit string. It returns 'color' converted to an encoded 16 bit string.
RGB_to_RGBA
Converts 24 bit color to 32 bit color
Converts 24 bit color values to 32 bit color values. There is only one parameter, 'color' and it must contain a bit encoded 24 bit string. It returns 'color' converted to an encoded 32 bit string with a maximized alpha channel.
USAGE HINTS
PERL OPTIMIZATION
This module is highly CPU dependent. So the more optimized your Perl installation is, the faster it will run.
THREADS
The module can NOT have separate threads calling the same object. You WILL crash. However, you can instantiate an object for each thread to use, and it will work just fine!
See the "examples" directory for "threadstest.pl" as an example of a threading script that uses this module. Just add the number of threads you want it to use to the command line when you run it.
head2 FORKS
I have never tested with forks. Do at your own risk, but follow the same rules as in threads, and it may work.
BLITTING
Use blit_read and blit_write to save portions of the screen instead of redrawing everything. It will speed up response tremendously.
SPRITES
Someone asked me about sprites. Well, that's what blitting is for. You'll have to do your own collision detection.
HORIZONTAL "MAGIC"
Horizontal lines and filled boxes draw very fast. Learn to exploit them.
PIXEL SIZE
Pixel sizes over 1 utilize a filled "box" or "circle" (negative numbers for circle) to do the drawing. This is why the larger the "pixel", the slower the draw.
MAKING WINDOWS
So, you want to be able to manage some sort of windows...
You just instantiate a new instance of the module per "Window" and give it its own clipping region. This region is your drawing space for your window.
It is up to you to actually decorate (draw) the windows.
Perhaps in the future I may add windowing ability, but not right now, as it can be pretty involved (especially redraw tracking and event managing).
Nothing is preventing you from writing your own window handler.
RUNNING IN MICROSOFT WINDOWS
It doesn't work natively, (other than in emulation mode) and never will. However...
You can run Linux inside VirtualBox and it works fine. Put it in full screen mode, and voila, it's "running in Windows" in an indirect kinda sorta way. Make sure you install the VirtualBox extensions, as it has the correct video driver for framebuffer access. It's as close as you'll ever get to get it running in MS Windows. Seriously... EVER.
This isn't a design choice nor preference. It's simply because of the fact MS Windows does not allow file mapping of the display, nor variable memory mapping of the display. Both techniques this module uses to achieve its magic. DirectX is more like OpenGL in how it works, and thus defeats the purpose of this module. You're better off with SDL instead, if you want to draw in MS Windows from Perl.
However, if someone knows how to access the framebuffer in MS Windows, and be able to do it reasonable from within Perl, then send me instructions on how to do it, and I'll do my best to get it to work.
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 5.01 (August 03, 2015)
THANKS
My thanks go out to those using this module and submitting helpful patches and suggestions for improvement:
Troy Beisigl Markus Maier