GNU Info
(xaos.info)driver
Driver API description
======================
To port sucessfully XaoS to some platform you need:
* ANSI C compatible optimizing compiler. Note that optimizing
compiler is really required, since XaoS is coded to be good target
for optimizations and don't have any routines coded in assembly,
so if you will use some bad compiler, you should receive more than
ten times slower result. Also note that some compilers has serious
problems with compiling XaoS -- like most of DOS compilers (Watcom
C, Borland C, Microsoft C etc...), plan9 compiler also has serious
problms with `formulas.c' . They generate incorrect code or crash
during compilation. I highly recomend to use GNU C compiler.
* Fast way to avoid division by zero/owerflow and other floating
point exception. XaoS is curefully coded to not to crash in this
case, but don't have any tests to avoid such situation and expect
random result in such case. Many plantforms provide way to switch
coprocesor into mode, where 1/0 is evaulated into Inf etc. I there
is no such way, try to use some kind of signal handler that will
ignore such exceptions. This way should be slow, so if you really
must use it, please contact me and we shall discuss speed
issues/add some tests into most freqvent exceptions in XaoS. If
your platform don't provide any such way, contact me too and I
will have to introduce plenty of tests as ifdef, wich shlould
greatly polute code and redce speed :(.
* Text or graphics output device. If you have only text output
device, you may use AA driver, wich renders fractals into high
quality ASCII art. In this case you might skip this section,
download AA-lib (http://www.ta.jcu.cz/aa) and read porting section
of AAlib manual. Graphics device must one of:
* 8bits per pixel with user definable palette `C256'
* 8bits per pixel with static palette `FIXEDCOLOR'
* 8bits per pixel with static grayscale `GRAYSCALE'
* 16bits per pixel with 5 bits per each color, Red first, Green
last `REALCOLOR'
* 16bits per pixel with 5 bits per green and blue, 6 for green,
red first `HICOLOR'
* 24bits per pixel with 8 bits per each color, Red first
`TRUECOLOR24'
* 24bits per pixel with 8 bits per each color, Red first
`TRUECOLOR24'
* 32bits per pixel with highest 8 bit unused, otherwise like
previous `TRUECOLOR'
* 32bits per pixel with highest 8 bit unused, otherwise like
previous at little edian machine `TRUECOLORMI'
* 1bits per pixe, zero is black, most significant bit first,
lines are aligned `MBITMAP'
* 1bits per pixe, zero is black, most significant bit last,
lines are aligned `LBITMAP'
* 1bits per pixe, zero is white, most significant bit first,
lines are aligned `MIBITMAP'
* 1bits per pixe, zero is white, most significant bit last,
lines are aligned `LIBITMAP'
Please contact me if you have different kind of device. Some modes
(like missordered truecolor modes) should be added really easily
if required. Note that mono/16 colors devices will be probably
never supported internally by XaoS, since I expect they will be
slower than 8bpp, so XaoS will internally work in 8bpp and then
image should be converted. Contact me if you want to write such
convertor.
* Some way to save images. By default XaoS uses pnglib, wich is
ported to many platforms, but there is still many other. If your
system has some standard image format, wich is easier to handle
than .png, contact me and I will show you, how to add such support
to XaoS.
* Stdio compatible library (this is problem at Mac or BeOS)
Ugly interface is designed to make writing of new drivers as easy as
possible. You need to write just few functions to fill following table:
(use file `ui_template' for starting of writing new driver from scrath)
struct ui_driver {
char *name;
int (*init)(void); /*initializing function. returns 0 if fail*/
void (*getsize)(int *,int *); /*get current size..in full-screen versions
i.e svga and dos asks user for it*/
void (*processevents)(int,int *,int *,int *,int *);
/*processevents..calls ui_resize,ui_key
also returns positions of mouse..
waits for event if first parameter is
1*/
void (*getmouse)(int *,int *,int *);
/*returns current mouse positions*/
void (*uninit)(); /*called before exit*/
int (*set_color)(int,int,int,int);
/*alloc palette color and returns number*/
int (*set_range)(ui_palette *palette,int start,int end)
/*Set palette range*/
void (*print)(int,int,char *);/*prints text*/
void (*display)(); /*displays bitmap*/
int (*alloc_buffers)(char **buffer1,char **buffer2);/*makes buffers*/
void (*free_buffers)(char *buffer1,char *buffer2);/*frees buffers*/
void (*flip_buffers)(void); /*prints text*/
void (*clrscr)(void); /*Clear screen*/
void (*mousetype) (int type); /*Change mouse cursor*/
void (*driveropt) (void); /*Driver depended actions*/
void (*flush) (void); /*Flush current state to screen*/
int textwidth; /*width of text*/
int textheight; /*height of text*/
char **help; /*help text*/
int helpsize; /*size of help in lines*/
struct params *params; /*command line parameters*/
int flags;
float width,height;
int maxwidth,maxheight;
int imagetype;
int palettestart,paletteend,maxentries;
};
Functions
---------
Ui uses following functions to communicate with driver:
- Function: init
function that initializes driver and returns 1 if success and 0 if
fail
- Function: getsize (INT *WIDTH,INT *HEIGHT)
returns size of screen(window) x and y
- Function: processevents (INT WAIT, INT *X,INT *Y, INT *BUTTONMASK,
INT &KEYS)
gets new keyboard/mouse events. parameters:
WAIT
if 1 function can wait for next event otherwise just lookup if
something comed. This is usefull on multitasked os
where xaos does not eats unnecesaru cpi.
*X,*Y
here returns current positions of mouse
*B
returns mask of `BUTTON1',`BUTTON2',`BUTTON3' for mouse
buttons
*K
returns mask for cursor keys
`1' left `2' right `4' up `8'
down function also calls `ui_key'(ASCII
character) and ui_resize if required
note in case of problems freeing/allocating inside processevents
you may call `ui_call_resize' that calls resize later outside
this function
- Function: uninit
Unitialises driver -- called before exit.
- Function: set_range(UI_PALETTE *PALETTE, INT START, INT END)
This is an preffered way to set palette (second way is `set_color')
when `imagetype' is `UI_C256' (256 color with palette) one of this
two functions is required. In truecolor modes they are unused. In
case direct access to palette is possible at your platform, define
this one. Function is expected to set all color cells between
START to END to colors defined in PALETTE. `Ui_palette' is array
of UI_RGB. `Palette[0]' is color for entry number START. `Ui_rgb'
is an array of `char'. `Palette[0][0]' is red field of entry
number START, `Palette[0][1]' is green and `Palette[0][2]' is
blue. `0' means black and `255' means full intensity. Use `NULL'
if your driver don't support this call.
- Function: set_color (INT R,INT G,INT B,INT INIT)
This is an secondary way, that should be used at platforms w/o
direct palette access (like X11 or static color schemes). It
receives RGB value of color, and returns index of color cell
with this color or -1 if no more color cells available. An INIT
parameter is set to 1, when first entry of palette is allocated,
`set_color' is expected to free all color entries previously
allocated. Use `NULL' if your driver don't support this call
- Function: print (INT `x',INT `y', CHAR *`text')
prints text to screen at possition x/y
- Function: display (VOID)
displays current buffer to screen
- Function: alloc_buffers (CHAR **BUFFER1,CHAR **BUFFER2)
allocs two buffers that can hold screen size bitmap. Also sets
current buffer to buffer1. Since version 2.1 returns scanline
size in bytes(usually width) and 0 if fail. This is usefull on
systems, that allocated bitmap bigger than
window/screen(dividable by 4 or so)
- Function: free_buffers(CHAR *BUFFER1,CHAR *BUFFER2)
frees allocated buffers
- Function: flip_buffer (VOID)
flips buffers -- set current buffer to other one
- Function: flush (VOID)
This function should be used by drivers with buffered output to
flush output buffers. Other driver should set it to NULL.
- Function: rotate_palette (INT DIRRECTION)
function used for palette rotating. It is not required. Set to
NULL if it is unimplemented in your driver.
When rotating is on this function is periodicaly called with
direction attribute. It must rotate all colors
1-number_of_allocated direction steps forward except first one.
This should be implemented also using cmap array in
zoom_context that contains correct rgb values.
So you may use ui_getcontext to get zoom_context and then set
context->numcolors colors in array cmap.
- Function: mousetype (INT TYPE)
This function is used to change mouse cursor. It receives
following values:
`NORMALMOUSE'
This mouse is usually displayed at screen, when UI waits for
user commands
`WAITMOUSE'
This mouse is displayed when UI is busy(should be famous wait
clocks) or you may use mouse defined in ui_dos --
mandelbrot set
`REPLAYMOUSE'
This mouse is displayed during replay. Should be none at
fullscreen drivers, since blinking mouse cursor during
replay looks ugly. At windowed system disabling mouse
looks ugly, so it should be some funny cursor.
You should use NULL if your driver don't support this.
- Function: clrscr (VOID)
This function is
- Function: driveropt (VOID)
This is an optional function (should be set to NULL) that should
be used for various driver depended actions. You should use
ui_menu call (see uinew.c for examples of usage) to make some
driver depended menu.
Other information
-----------------
Also some additional variables are used to inform ui about driver.
All this values can be changed by init functions in case they are
unknown before.
TEXTHEIGHT,TEXTWIDTH
width and height of your font
PALETTESTART,PALETTEEND
First and last palette entry, that should be changed. This you
should use to avoid changing of entries reserved for window
system, text, mouse etc.
MAXENTRIES;
Number of allocatable entries. Normally should be
PALETTESTART-PALETTEEND
IMAGETYPE
defines type of image. Should be one of following values:
`UI_C256'
clasical 256 color with palette scheme used by most older
graphics adapters. You should use it also for staticcolor
schemes but they are not supported well in current
version.
`UI_TRUECOLOR'
32bpp truecolor mode
`UI_TRUECOLOR24'
24bpp truecolor mode.
`UI_HICOLOR'
16bpp hicolor mode (65536 colors)
`UI_REALCOLOR'
16bpp realcolor mode (32768 colors)
FOLLOWING PART IS NOT REQUIRED TO MAKE FIRST VERSION OF DRIVER
WORKING. so you may skip to REGISTERING DRIVER for first read and
return here later.
HELP
help text. This text is displayed at the end of ui' help. So you
can put your copyright there and additional informations about
driver.
HELPSIZE
number of lines of help
PARAMS
Using this you may define command line options for you driver.
They are defined using params structure like:
static struct params params[]={
{"-mode",P_NUMBER,&defmode,
"Select graphics mode(same number as in interactive menu)"},
{NULL,0,NULL,NULL} /*this is MUST be last option field*/
};
every line is one parameters. List ends with `{NULL,0,NULL,NULL}'.
First filed is option name. Second field is type of parameter:
`P_SWITCH'
no parameter - variable is just set to 1 if option
`P_NUMBER'
integer number
`P_STRING'
string
`P_FLOAT'
floating point number (variable is float) Third is
pointer to variable that is changed if option is set. It is for
example `int*' for `P_NUMBER' or `P_SWITCH' and so on.. Last
one is help text. Displayed by `ui -h'
WIDTH,HEIGHT
see FLAGS. May be set to `0.0, 0.0' for the begining
MAXWIDTH,MAXHEIGHT
see FLAGS. May be set to 0,0 for the begining
FLAGS
This variable says more about your driver. You may start with
value 0. But for final version it is recomeded to read
following section curefully.
Flags are uppercase constants and should be set by following way:
`ASYNC_PALETTE | PALETTE_ROTATION'
following switches are supported:
`RANDOM_PALETTE_SIZE'
random size of palette. This is used in X where palette is
shared between programs. By default xaos allocates all
available colors up to 256. This is not very nice to
other aplications in X. So randomsize causes that just
some random number of colors(between 8-256) are allocated.
Also when this variable is off XaoS expects that allways same
number of colors is available.
`UPDATE_AFTER_RESIZE'
recalculate and redraw screen even if its size is not changed.
In case that resize precodure destruys data in buffers
Palette rotation options:
Palette rotation should be implemented by various ways. You
may define following values to let xaos know about
features/limitations of your implementetion:
`ROTATE_INSIDE_CALCULATION'
call rotate routing inside calculation loop too? (vbuff
should include incorrect data)
`PALETTE_REDISPLAYS'
If you rotate_palette function displays buffers(like in
truecolor modes. Set this to 1 and ui will handle this more
effectivly) Screen/window size informations
Xaos needs to know exact size of displayed images. This is required
for random dot stereograms and also for keeping fractals in
their shape (do not make them wide on 640x200 resolution etc.)
So minimally one of the following values should be defined.
(they are sorted in order I preffer them)
`SCREENSIZE'
values width/height specifies exact size of screen/window in
centimeters
`PIXELSIZE'
values width/height specifies exact size of one pixel in
centimeters This is better for windowed enviroments
where window size is often changed
`FULLSCREEN'
driver runs fullscreen. XaoS automatically uses default
screen size (29.0cm x 21.5cm)
`RESOLUTION'
driver does not know exact screen size. But knows resolution
used. (it is in variables width/height) XaoS
automatically calculates pixel width
using:29.0cm/maxwidth and height: 21.5/maxheight
Of course default width and height can be changed by command line
options. You may also use combinations like:
`SCREENSIZE | FULLSCREEN'
the best for fullscreen drivers
`PIXELSIZE | RESOLUTION'
the best for windowed drivers
`FULLSCREEN'
for fullscreen drivers than have no idea about screen size...
do not forget to set WIDTH, HEIGHT, MAXWIDTH,
MAXHEIGHT fields if required.
Registering driver
------------------
Than just register driver to `driver.c' and you may compile :) You
may use `ui_template.c' as driver template..
You may also look at xthreads library description if you are porting
XaoS to some SMP platofrm.
Please let me know if you want to start code some driver.
automatically generated by info2www version 1.2.2.9