NAME

fbed - frame buffer editor

SYNOPSIS

fbed [-pH]

DESCRIPTION

fbed is an editor for frame buffer images, designed to facilitate the manipulation of existing images for the preparation of presentation quality graphics. Although it does have the potential to generate fairly complex images, it is meant mainly for touching up existing images; adding titles, captions or other labels; cutting and pasting of one or more images; and reducing images or portions thereof. fbed uses the frame buffer library libfb(3) and therefore is available on all graphics devices which are supported by this package. On start up, the program always attempts to open the default frame buffer. This device is specified by the frame buffer library, and is configurable on a per system basis. Often the user will want to override this default by setting the environment variable FB_FILE (see brlcad(1)). The -H option is for editing 1024x1024 or high resolution (HIRES) images; the default is low resolution, 512x512 (LORES). The frame buffer's state can be toggled back and forth between HIRES and LORES at any time during execution of the program.

The -p option turns on the "pad" flag.

fbed allows function-to-key bindings and macro definition facilities in a fashion similar to some of the more versatile EMACS-style screen editors, such as jove(1).

Cursor Movement

When fbed is running on a graphics device, a cursor will appear on the screen. The position of the cursor points to the current pixel.

Terminal Display

When run interactively, with the standard input attached to a terminal, the screen will be divided into 5 areas: the top line will be referred to as the option line; the second line from the top will be called the header line; the bottom line of the screen will be the status line; the second line from the bottom will by the prompt line; and the rest of the screen is devoted to scrolling text output. The option line contains the current pixel color and paint color, stride and brush size. Colors are expressed as a combination of red, green, and blue intensity values; ranging from 0 to 255. The pixel color refers to the current pixel which is pointed to by the cursor on the graphics device. paint color is used by functions that require a color rather than prompting for it every time. The stride indicates how many pixels the cursor will move per keystroke during key-activated cursor movement. Finally, brush size refers to the size of the square of pixels filled in by the put-pixel command. The header line is displayed in reversed video, and contains the program name and version number as well as the current cursor position. The prompt line is where the user will see prompts when the program requires information. The status line is used to print messages, indicating to the user that an operation is on-going.

Modes of Input

The user interface consists of a list of provided commands, referred to as functions; and user-defined commands, called macros. In general, every key-stroke will immediately be processed (this is often popularly called raw mode input) and therefore, virtually every function or macro is executed by striking a particular key, without having to enter it by hitting RETURN. The key that activates a particular function or macro is said to be bound to that operation.

Many of the functions will require the user to type some additional information or arguments, and a prompt will appear in the lower left corner of the screen. When responding to such prompts, the style of input resembles that of Bourne and C Shell derivatives with in-line EMACS-style editing. This means that the following control keys have special meaning:

key	editing function
^U	erase from start of line to cursor
^R	redraw line as it currently exists
^V	escape special meaning of next character typed
Back Space	move cursor backward one character
Delete	delete character behind cursor
^A	cursor to beginning of line
^B	cursor back one character
^D	delete character under cursor
^E	cursor to end of line
^F	cursor forward one character
^G	abort this function
^K	erase from cursor to end of line
^P	fetch last input typed to this prompt

When attempting to fetch the last input typed, the user should keep in mind that this is specific to the particular function which is doing the prompting and to that particular question being asked by that function. Most of the prompts are intended to appear self-explanatory, but there are a couple of exceptions. The execute-function-or-macro function places the user in the prompted mode of input for the purpose of typing the name of the command. This is useful when the key binding is not known off-hand or a key binding does not exist, but the name of the command is known (or can be guessed at). In any case, it is an alternative to key-activated execution of a function or macro. When entering the prompted mode of command input, a `:' will appear in the bottom left of the terminal screen and the terminal's cursor will appear just ahead of it. Now, all of the above control key functions are in force, and command-completion is implemented as well. At any time while typing the name of the function or macro, the space bar may be hit to attempt command-completion. The command-completion logic will look at what has been typed, and if it represents the beginning of an existing function or macro, the remainder of that name which can be uniquely matched will appear. If there is no match, the portion of the name that has been typed that does not match will be deleted, starting at the end and working back. In other words, the user only needs to type the unambiguous root of the name. If the user has done so, hitting the space bar will show the complete name, or hitting the RETURN key will enter the command. If the RETURN key is struck, and there is no unique match, nothing will happen. Whenever the user is prompted for the name of a function or macro, and there are other functions that prompt for this specifically, then command-completion is provided. Another atypical prompt is generated by the argument-count function, and looks like M-. The cursor will appear right after the hyphen, and the user is expected to type a number (sequence of digits). This sequence of digits must be terminated by a command key-stroke. This number represents an count of how many times to execute the command bound to that final key-stroke. If a digit is bound to a function or macro, it will not be recognized by the argument-count function.

User-defined Macros and Key Bindings

The user may define a macro as a series of key-strokes. This is initiated by executing the start-macro-definition function. The message "Remembering..." will appear on the status line, and the user then types the key-strokes which will represent the macro definition. These key-strokes will be executed as the macro is defined. To end the macro definition, the user executes the stop-macro-definition function. Sometimes, the user will want to defer specifying the answers to prompts when defining a macro, so that he can supply the information when the macro is executed. In order to incorporate this into his macro, the user would type a '@' at the prompt. This will cause the function to fail while the user is defining the macro, but this will hopefully not cause any fatal side-effects. Immediately after defining the macro, or before defining another, the user should enable its execution by giving it a name with the name-keyboard-macro function. If the user desires, he may bind it to a key with the bind-macro-to-key function, or it may be executed by name only.

Another way of customizing the frame buffer editor is to change the binding of keys to functions. This is done by executing either bind-key-to-name or bind-key-to-key. The former will bind a key to either a function or macro by specifying its name, and the latter refers to the function or macro by a key that is currently bound to it.

Both key bindings and macro definitions can be saved in a file using write-macros-to-file and read back with read-macros-from-file. Whenever the frame buffer editor starts up, it looks for a file called .fbed_macros in the user's home directory, and reads it if it exists. A list of functions and macros and their key bindings can be obtained by executing the print-bindings function which is bound to `?' by default. Here is the standard listing:

key	function
^H	move-window-left
space	pick-point
,	decrement-brush-size
<	decrement-step-size
>	increment-step-size
?	print-bindings
A	start-macro-definition
B	bind-macro-to-key
C	shrink-image-by-half
E	clear-framebuffer-memory
F	flip-framebuffer-resolution
^J	move-window-down
^K	move-window-up
^L	move-window-right
Return	reset-view
^R	redraw-tty-screen
^X	execute-function-or-macro
^Z	stop-program
Esc	argument-count

key	function
G	get-current-rectangle
T	replace-pixel-current-rectangle
U	write-macros-to-file
V	fill-bounded-region
W	fill-current-rectangle
X	bind-key-to-key
Y	bind-key-to-name
Z	stop-macro-definition
a	enter-macro-definition
b	set-current-rectangle
c	window-center
H	jump-cursor-left
d	draw-line
f	read-font
g	set-paint-to-current-pixel
h	move-cursor-left
i	zoom-in
j	move-cursor-down
k	move-cursor-up
l	move-cursor-right
m	set-monitor
n	set-tolerance-color-match
J	jump-cursor-down
o	zoom-out
p	set-paint-from-key
q	quit
r	read-framebuffer
s	put-string
t	change-region-color
u	read-macros-from-file
v	draw-rectangle
w	put-pixel
x	set-cursor-y-pos
K	jump-cursor-up
y	set-cursor-x-pos
L	jump-cursor-right
N	name-keyboard-macro
P	put-saved-rectangle
R	read-rle-fle
S	write-rle-file

Macros and functions which are not bound to a key will not be displayed.

HINTS

This program may require a little practice; be sure to save a copy of the input files until you are confident. If you are using the program for the first time, you should start by listing the menu, finding the command for saving your image, and using such command if you don't already have a copy.

FILES

/usr/lib/vfont/*

Berkeley font files

$HOME/.fbed_macros

Startup configuration file

KNOWN BUGS

This program is currently under development.

It is known that aborting the execution of the certain functions will at times display bogus messages like "I seem to have lost my bindings."

There is currently a hard limit of 10 times BUFSIZ (defined in stdio.h) for the length of the macro startup file.

AUTHOR

BRL-CAD Team

COPYRIGHT

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org