Welcome to EZFB!

Thank you for your interest in this project. I hope you find it useful and
enjoyable.

This is version 11.00 !!!

You will need to build your Linux kernel with frame buffer support.
(Hint: [*] Prompt for development and/or incomplete code/drivers)

Please install fbset by Geert Uytterhoeven. Read about what it does and know
the limitations of your monitor! You might ruin a low resolution monitor
by not knowing how to use this program.

You must be root to run applications built on EZFB.

EZFB is polymorphic, object oriented C. All of the functions are written to
adapt to the video capability at run-time. So, knowing how to use fbset to set
your video card to the highest resolution your monitor will support is to your
benefit. Plus 132 characters on one line at a bash prompt is pretty neat
(1600x1200 pixel terminal).

If you only have one video card in your computer, an active session of EZFB
will take over the display and not allow you to see the terminal. So a good
way to develop applications with EZFB is from a telnet session on another
computer. The API has 4 levels of messaging that indicate what it is doing
during the run of the program. All of these messages will appear in the
terminal that the program was initiated from. If that happens to be the local
terminal connected to /dev/fb0, you won't be able to see them. An EZFB
program issued from any terminal will control the video card(s) and monitor(s)
local to the machine, by number ie: /dev/fb0, /dev/fb1, /dev/fb2, etc...

If you don't have another computer / monitor and you still want to see the
messages, redirect stdio and stderr to a file like this:

./my_ezfb_program >& ezfb_messages

Then read the file, "ezfb_messages" after the process terminates.

Look in ezfb_macros.h for the different types of messages that can be enabled
or disabled from there.

All of the API code starts with ezfb_. The example programs start with x_.
Issue the make command from within the directory where these files were
un-tar-ed. You will have 8 executables:

./demo ./grab ./jl ./lines ./multi ./show ./tell ./tsc

///////////////////////////////////////////////////////////////////////
FILES:

readme.txt ~ this file

Makefile ~ A human written make file for this project

ezfb.h ~ This is the only thing that needs to be #included in your C/C++ program.

ezfb_includes.h ~ #includes all of the system headers that this API needs.

ezfb_macros.h ~ Defines every macro used in the API.
                Here's where you set the function tracing levels.

ezfb_types.h ~ Defines structures used in EZFB.

ezfb_device.h ~ Controls the video device and the system that it is part of.
ezfb_device.c

ezfb_pixels.h ~ Puts and gets pixels. Draws lines, rays, rectangles.
ezfb_pixels.c

ezfb_tty.h ~ Controls the terminal.
ezfb_tty.c

ezfb_bmp.h ~ Provides a common file format interface to and from the display
ezfb_bmp.c

ezfb_colors.h ~ Contains all of the routines that are specific to controlling
ezfb_colors.c   palettes and generating colors.

ezfb_fonts.h ~ Defines bitmapped font and functions for drawing text
ezfb_fonts.c   into the frame buffer.

x_demo.c
./demo [/dev/fbN]
Let it run all the way through with no arguments and it will show you what
your frame buffer can do. You will also have some new files in the bmp
directory. Issuing demo with a device name; ie: /dev/fb1 will cause the
program to attempt to open that device and run the demo there.

x_show.c
./show [/path/bitmap.bmp][/dev/fbN]
Will display the specified bitmap in the center of the screen. No argument
shows a default bitmap. Hit ESC to terminate the program. In release 9.03
of the project, I added set_ezfb_xy_virtual and set_ezfb_xy_offsets
functions and these functions may be tested with this demonstration. This
application will attempt to make the virtual screen twice as wide and twice
as high as the visible screen and set the x and y offsets so that the visible
screen is in the center of the virtual screen. The arrow keys should move the
visible screen area around in the virtual screen area. The backspace key sets
the offsets to zero.

x_tell.c
./tell [/dev/fbN][xxx]
Dump the current configuration of the frame buffer device to the terminal.
Any argument beyond the frame buffer device name will cause the color palette
data to be dumped as well.

x_black.c
./black [/dev/fbN]
Open frame buffer without saving the contents of video memory. Load utility
palette. Set every pixel to black and exit, leaving the screen black. This
utility is designed to clear the screen, especially usefull for video cards
other than /dev/fb0, the console.

x_grab.c
./grab [/path/bitmap.bmp]
Make a bitmap of the contents of the screen, even if it is in the control of
another process! The bitmap will be in the same directory as this application
and will be called grab.bmp, unless you specifically name another
path/filename.bmp as an argument.

./tsc
This is the reason I wrote EZFB. I used to work for a company that dealt
with tiny LCD screens with touch panels on them. (arm-Linux) I don't do that
anymore! I have no way to test this program since major revisions have been
made to the code. If you find this useful, please let me know.
Try --help as an argument.

x_jl.c
./jl [/dev/fbN][xxx]
The Screen Shredder! This is a complete waist of time. You have been warned.
No arguments to this program runs it in the automatic mode. Hit any key to
exit. It might have to finish a palette cycling routine, but it will terminate
eventually. Any arguments puts it into the interactive mode. Use the keyboard
to shred the screen! 'X' to exit. I wrote the guts of this program back in
1995, when I first started programming in C and had just gotten into Linux.
Back then I used svga.lib.

x_lines.c
./lines
This program demonstrates the vector drawing function fb_ray(...). It draws
thousands of rays in a smooth rotation of every color in the palette emanating
from the center of the screen and then cycles the palette until the user hits
any key. It saves the picture on the screen as bmp/lines.bmp and terminates.

x_multi.c
./multi
This program tests the system, looking for any and all valid frame buffer
devices. It opens all of them and fills them with random rectangles.
Hit any key to terminate.

If you have any comments, questions or suggestions, please return to the
Website where you found this code or Email me directly at james@akrobiz.com.
Please be specific in the subject of your Email. I use TMDA so you will need
to reply to its responce. If all else fails, call me! 330 762-7137.
I live in Akron, Ohio, USA about 50 miles south of Lake Erie, on Planet Earth.

                                                 James Lehman 1/18/2005