Graphics-Framebuffer

*********************************************************************
** Note, this module does NOT work (natively) in Microsoft Windows **
*********************************************************************

PREREQUISITES

This module REQUIRES access to the video framebuffer, usually "/dev/fb0".
You must be using a video device and driver that exposes this device to
software.  Video cards with their proprietary drivers are not likely to work.
However, most open-sourced drivers, seem to work fine.  VirtualBox drivers
work too.

*** ATTENTION CPAN TESTERS!  Read the above again and again until it sinks in.

I highly recommend you install the system (or package) version of the "Imager"
library, as it is already pre-compiled with all the needed C libraries for it
to work with this module.  In Yum (RedHat) and Aptitude (Debian/Ubuntu) this
module is called "libimager-perl".  However, if you desire to install it
yourself, please do it manually, and not via CPAN.  When you do it manually,
you can see the missing C libraries it is looking for in the "Makefile.PL"
process and stop it there.  You can then install these libraries until it no
longer says something is missing.  You see, it just turns off functionality if
it can't find a library, instead of stop.  Libraries usually missing are those
for GIF, JPEG, TrueType and FreeType fonts, among others.  These are necessary
not optional.

If you want to use the acceleration features (a module "suggestion" not
"requirement"), then the "build-essential" tools need to be installed. This is
generally a C compiler, linker, and standard C libraries (usually gcc variety).
The module "Inline::C", which this module uses, requires it.  Also, the
package "kernel-headers".  If you are using a 16 display (LCD panel for
example), then I HIGHLY recommend you make sure this is done and acceleration
is used.

INSTALLATION

You SHOULD install this module from the console, not X-Windows.

To install this module, run the following commands:

    perl Build.PL
    ./Build
    ./Build test
    ./Build install
    
OR...

	perl Makefile.PL
    make
    make test
	make install

NOTE:  The install step may require sudo (root access).

FURTHER TEST SCRIPTS

To test the installation properly.  Log into the text console (not X).
Go to the 'examples' directory and run 'threadstest.pl' or 'primitives.pl'.
They basically call most of the features of the module.  'threadstest.pl'
demonstrates how to use threads with this module.  You can pass a number in on
the command line to the "threadstest.pl" script, and it will use that many
threads.  The default is the number of cores you have.

The script 'threadstest.pl' requires 'Sys::CPU'.  It is not listed as a
prerequisite for this module (as it isn't), but if you want to run this
one script, then this is a required module.

COMPATIBILITY vs. SPEED

This module, suprisingly, runs on a variety of hardware with accessible
framebuffer devices.  The only limitation is CPU power.

Some lower clocked ARM devices may be too slow for practical use of all of the
methods in this module, but the best way to find out is to run
'examples/primitives.pl' to see which are fast enough to use.

Here's what I have tested this module on:

Raspberry PI2   - Tollerable, I did 16 bit mode testing and coding on this
                - machine.  Using a Perlbrew custom compiled Perl helps a bit.
                - The Raspberry PI (and RP2) are configured, by default, to be
                - in 16 bit graphics mode.  This is not the best mode if you
                - are going to be loading images or rendering TrueType text,
                - as color space conversions can take a long time.  Overall,
                - 32 bit mode works best on this machine, especially for image
                - loading and text rendering.  This can, however, be minimized
                - using the C acceleration features.

Odroid XU3/XU4  - Surprisingly fast.  All methods plenty fast enough for heavy
                - use.  Works great with threads too, 8 of them (when done
                - properly).  Most coding for this module is done on this
                - machine at 1920x1080x32.  This is fast enough for full
                - screen (1920 x 1080 or less) animations at 30 fps.  If your
                - resolution is lower, then your FPS rating will be higher.

Atom 1.60 GHz   - Decent, not nearly as fast as the Odroid XU3/4.  Works good
with NVidia     - with threads too (when done properly).  Great for normal
Nouveau driver  - graphical apps and static displayed output.

2.6 GHz MacBook - Blazingly fast. Most primitives draw nearly instantly.
with VirtualBox -

Windows 10 PC   - Holy cow!  No, seriously, this sucker is fast!  I wonder how
with VirtualBox - much faster if it were running Linux natively?  Especially
4GHz 6 core CPU - since I noticed that VirtualBox is very inefficient with
NVidia 660 Ti   - threads (What's up with that?).

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc Graphics::Framebuffer

    or

    man Graphics::Framebuffer

You can also look for information at:

    RT, CPAN's request tracker (report bugs here)
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Graphics-Framebuffer

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/Graphics-Framebuffer

    CPAN Ratings
        http://cpanratings.perl.org/d/Graphics-Framebuffer

    Search CPAN
        http://search.cpan.org/dist/Graphics-Framebuffer/

    YouTube
        https://youtu.be/4Yzs55Wpr7E


LICENSE AND COPYRIGHT

Copyright (C) 2013-2015 Richard Kelsch

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.