diff options
Diffstat (limited to 'doc/xaosdev.info')
| -rw-r--r-- | doc/xaosdev.info | 2862 |
1 files changed, 2862 insertions, 0 deletions
diff --git a/doc/xaosdev.info b/doc/xaosdev.info new file mode 100644 index 0000000..57b5d82 --- /dev/null +++ b/doc/xaosdev.info @@ -0,0 +1,2862 @@ +This is Info file xaosdev.info, produced by Makeinfo version 1.68 from +the input file xaosdev.texinfo. + +INFO-DIR-SECTION Graphics +START-INFO-DIR-ENTRY +* XaoS: (xaosdev). The fast real-time interactive fractal zoomer + (developers documentation +END-INFO-DIR-ENTRY + + (C) 1997 Jan Hubicka + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + +File: xaosdev.info, Node: Top, Prev: (dir), Up: (dir) + +XaoS 3.1 +******** + + An real-time interactive fractal zoomer + Hacker's guide + May 14, 1998 + + This manual contains documentation for those who are interested in +studying and improving XaoS sources or using them in other programs. +It includes description of algorithm and documentation of those parts +of XaoS I think they should be useful for someone. + +* Menu: + +* design:: Overview of the XaoS design +* driver:: Driver API description +* gui-driver:: Writing user interface driver +* eui:: Writing an external user interface +* ui-helper:: UI helper library +* xthreads:: XaoS thread library +* filters:: Filters +* algorithm:: Algorithm description +* timerlib:: The timer library +* registry:: XaoS function registry +* index:: Function command and variable index + + +File: xaosdev.info, Node: design, Next: driver, Prev: Top, Up: Top + +Overview of the XaoS design +*************************** + + Whole sources of XaoS are designed into several "libraries" (some of +them are not really libraries, but added into other's, but should be +separated easily). + + Understanding to the main philosophy should help you to navigate in +the sources. I also expect that many of the lower level stuff should +be useful in the other projects, since it is designed to be fairly +generic. + + So here is an overview from the lowest level stuff to the highest. + +Palette and image library +========================= + + Sources are in directory `src/filter'. The aim of palette library is +to provide relatively abstract interface to the various visuals and +hide differences in the hardware and driver implementation. Fixedcolor, +pseudocolor, grayscale and truecolor visuals should be handled in the +almost same way. + + It provides the structure `palette', which contains actual palette. +You might allocate new colors here (you give RGB value and +corresponding pixel is returned), interpolate colors where possible, +cycle colors and so on. Every palette also consist from the two +parts--the preallocated color cells and the actual palette. This lets +for example to GUI possibility to allocate statically colors for its +texts and dialogs, while rest of palette is under control of different +parts of XaoS. + + This library also contain set of functions to allocate different +palettes used by other parts. I expected that different parts of XaoS +should use same palette. Nothing similar happened yet, but functions +are kept here. + + The image library is built at the top of palette library. It extends +functionality for handling actual image data. Each image is represented +by one or two frame-buffers (it is useful for double-buffering). One +frame-buffer is called current and other old. They should be flipped by +special function. Program can draw into both of them. + + Frame-buffers are hold as the set of pointers to the scan-lines. +This brings better flexibility, because tricks like sub-windows, or +flipped bitmaps are possible. Also speeds up, since you should avoid +one multiplication. + + The last significant information image structure hold is of course +bpp depth. It is counted in bytes, and should be 0-4. Where 0 is used +for 1bit bitmaps. + +Filter library +============== + + Source are available in `src/filter'. This library controls the +process of creation of the image. It handles an queue of the filters, +where each filter should modify the image. There are two special filter +at the beginning and end of queue. The first filter is usually the +actual fractal engine which creates image, while the terminal filter is +usually user interface helper library. + +Xthread library +=============== + + This library provides interface to various multi-threading libraries +(currently the BeOS, plan9 and POSIX implementations are available). It +allows to run various function paraelly and some synchronization +primitives (semaphores). It is simple, but has all the functionality +required for the XaoS engine. + +Fractal library +=============== + + Source are available in `src/engine/', headers in `fractal.h'. This +library contains the actual fractal calculation routines. It operates +with fractal context, which contains informations like current formula, +seed for julia, palette etc. + + Functions for calculating the various fractal types and various +coloring modes are available here. + +Zooming engine and other filters. +================================= + + Source are available in `src/engine/'. This is the actual zooming +engine filter. It is done in fairly independent way at fractal library, +so it should be possibly used for zooming other stuff. (it was already +used for zooming large scale images containing maps of Hungary). + + All other filter has their special file, where is implementation and +structure containing all functions exported from the filter to user +interface. They are registered in the file `ui_helper'. One other +terminal filter is implemented--Julia morpher. Other filters adds +special effects (such as motion blur), or does conversions (such as +rotation, dithering etc.) + +Timer library +============= + + This library provides many of very useful timing primitives. Such as +timers, etc. Currently it is used by some other programs too. + +xio library +=========== + + This library aims to provide united interface to file-system. Some +strange systems (such as MacOS) has file-system API done in much +different way than in UNIX. They don't have names in string, and uses +special structures etc. + +xshl library +============ + + Xshl stands for XaoS simple hypertext library. It contains fairly +universal engine parsing an xshl language. It is similar to HTML with +some additions and many restrictions. It should render this texts for +the proportional/non-proportional fonts and various sizes. + +help library +============ + + it is built at the top of xshl and xio libraries. It should read +help files, wick contains an chapters. Parse chapter with given keyword +etc. + +xmenu library +============= + + This is the XaoS function registry. All functions from UI-Helper +library are registered in the registry. From this registry the menus, +dialogs, command line options and scripting language are built. + +Catalog library +=============== + + This is library for handling an message catalogs. It should read +catalog and convert the keyword into actual message. + +PNG library +=========== + + This library provides the function for saving an image from Image +library to the file (in PNG format). Other formats should be added as +well if required. + +UI-helper library +================= + + This library controls all the low-level stuff and provides an high +level interface to it. It has functions for playing animations, +zooming/UN-zooming and such. It heavily uses all the described +libraries. It don't implement functions for handling menus and such, +but makes great help for such implementations, because of the function +registry database. + +Ugly interface +============== + + This is currently the only real user interface for XaoS (there is +also an second, wich is used for rendering animations, but it is not +user interface, how users expect it). It is built at the top of +UI-helper library and provides functions for drawing menus, dialogs and +such. It has drivers for many platforms, and it should be easily +ported to the others. + + In the future, it should be quite easily to extended to let drivers +specify their own menu/dialog handling code, so it should be possible +to give it an "native" look of given platform. + + It has also an function, where an GUI drawing routines are disabled. +Function registry database is transfered trough pipe to external +program, wick should build the menus and act as external user +interface. It then back sends an commands in the scripting language +representing things, that user done. So it is an another way, how to +give native look to ugly interface. + + Ugly interface has also one serious limitation--for the historical +reasons it is coded to handle just one window (rest of XaoS probably +can do multiple windows--untested). So in windowed environments it is +impossible to open multiple menus with fractals. At the other hand, +this limitation is not so important, once external GUI enter the role. +They should just start multiple XaoS engines. This will bring extra +robustness, multitasking and some other advantages, so it is the +proffered way. Thats why I don't plan to remove this limitation yet. + + +File: xaosdev.info, Node: driver, Next: gui-driver, Prev: design, Up: Top + +Driver API description +********************** + + To port successfully 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...), has serious problems. They + generate incorrect code or crash during compilation. I highly + recommend to use GNU C compiler. Even some versions of GNU C has + problems. Please read `compilers.txt' for more information. + + * Fast way to avoid division by zero/overflow and other floating + point exception. XaoS is carefully 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 platforms provide way to switch + coprocessor into mode, where 1/0 is evaluated into Inf etc. If + there is no such way, try to use some kind of signal handler that + will ignore such exceptions. + + The "normal" solution--add ifs to avoid division by zero is almost + impossible. The division is quite easy to check. But other + cases--overflows are much worse. So I don't think it is possible + to avoid all crashes just by adding ifs. + + XaoS don't depend at IEEE arithmetic. Result in such cases should + me mostly undefined. XaoS usually works well with compiler's + switches for inexact math enabled (such as `-ffast-math' in GNU). + But no guarantees. For example at Alphas this is not true--since + they usually generates exceptions then. Also `-mno-ieee-fp' at + Intel don't work. This is due to gcc bug. Gcc in some cases reverse + the condition when this switch is enabled. I've made patch to fix this + problem and hope that it will get to egcs or gcc soon. + + * Text or graphics output device. If you have only text output + device, you may use AA driver, which renders fractals into high + quality ASCII art. In this case you might skip this chapter, + download AA-lib (http://www.ta.jcu.cz/aa) and read porting chapter + of AAlib manual. Graphics device must one of: + + * 8bits per pixel with user definable palette `C256', static + palette `FIXEDCOLOR', or static grayscale `GRAYSCALE' + + * 16bits per pixel with arbitrary bits per each color + `TRUECOLOR' + + * 24bits per pixel with 8 bits per each color, arbitrary order + `TRUECOLOR24' + + * 32bits per pixel with arbitrary order of colors, where each + colors fit to exactly one byte `TRUECOLOR' + + * 1bits per pixel bitmap with both orders (Least or Most + significant bit first) + + Please contact me if you have different kind of device. Some modes + (like miss-ordered truecolor modes) should be added really easily + if required. Note that mono/4/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 + converter. (For bitmap there already exists--see `dither.c'. + + * Some way to save images. By default XaoS uses `pnglib', which is + ported to many platforms, but there is still many others. If your + system has some standard image format, which is easier to handle + than `.png', contact me and I will show you, how to add such + support to XaoS (see `png.c'). + + * Stdio compatible library (this is problem at Mac or BeOS). XaoS + has the abstract layer at the top of stdio, so it should use other + input/output libraries too. You might write just another + implementation if it's library called `xio'. See `xio.h'. + + 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 (*mousetype) (int type); /*Change mouse cursor*/ + void (*flush) (void); /*Flush current state to screen*/ + int textwidth; /*width of text*/ + int textheight; /*height of text*/ + struct params *params; /*command line parameters*/ + int flags; + float width,height; + int maxwidth,maxheight; + int imagetype; + int palettestart,paletteend,maxentries; + int rmask, gmask, bmask; + struct gui_driver gui_driver; + }; + +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 came. This is useful on multi-tasked os + where xaos does not eats unnecesaru CPU. + + *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. For special keys use + `UIKEY_UP', `UIKEY_DOWN', etc. See `ui.h' for complete lists + of this constants. + + 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 position x/y. This function is a bit + archaistic (XaoS now uses in the most cases its own functions + drawing directly to the buffer), but in some + cases--initialization messages or calculation, functions are + unusable, so we still need this primitive. In the `C256' mode + you might rely, that first allocated color is always black and + second is white. + + - 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 scan-line + size in bytes(usually width) and 0 if fail. This is useful 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: 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. + +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. + +RMASK, GMASK, BMASK + This fields are used in truecolor modes to specify, where each + color is defined + +MAXENTRIES; + Number of allocatable entries. Normally should be + PALETTESTART-PALETTEEND + +IMAGETYPE + defines type of image. Should be one of following values: + `UI_C256' + classical 256 color with palette scheme used by most older + graphics adapters. You should use it also for + static-color schemes but they are not supported well in + current version. + + `UI_TRUECOLOR' + 32bpp truecolor mode + + `UI_TRUECOLOR24' + 24bpp truecolor mode. + + `UI_TRUECOLOR16' + 16bpp truecolor mode + + 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. + +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 beginning + +MAXWIDTH,MAXHEIGHT + see FLAGS. May be set to 0,0 for the beginning + +FLAGS + This variable says more about your driver. You may start with + value 0. But for final version it is recommended to read + following chapter carefully. + + Flags are uppercase constants and should be set by following way: + + `ASYNC_PALETTE | RANDOM_PALETTE_SIZE' + + 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 applications 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 allays same + number of colors is available. + + `UPDATE_AFTER_RESIZE' + recalculate and redraw screen even if its size is not changed. + In case that resize procedure destroys data in buffers + + `RESIZE_COMMAND' + Some drivers (mainly the fullscreen ones) may in the function + `get_size' ask user for the size and color depth. It + should be nice to let user change this parameter at + runtime. I.E force XaoS to reinitialize his images. This is + done by `ui_resize' call. This call in windowed drivers + is called by the external event. But in fullscreen + drivers you need key/menu item for this. You might add + this function directly into XaoS's function registry (see + for example the GGI driver)--it is usefull mainly when you + want to make some size selection dialog in the standard + way, or let XaoS add his default one. And this is done by + this flag. See for example SVGAlib or DOG driver. + Screen/window size informations: + + Xaos needs to know exact size of displayed images. This is required + for random dot stereo-grams 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 prefer 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 environments + 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. + +GUI_DRIVER + See next section for description. + +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 platform. + + Please let me know if you want to start code some driver. + + +File: xaosdev.info, Node: gui-driver, Next: eui, Prev: driver, Up: Top + +Writting GUI driver +******************* + + XaoS have builtin GUI. Many operating systems have native gui +toolkits and XaoS default GUI might look strange there. To avoid this +problem, you might write external gui program (see eui section) or +write mappings of XaoS GUI functions. The advantage of external gui +process in multitasking. XaoS is not thread safe and GUI must be +synchronous with calculation. Also ugly interface code currently don't +support multiple windows (this should be solved in future). This +solution is suitable mainly for those systems, where cooperation of two +programs sharing one window should be problem (like on Windows). + + To write gui driver you need to fill following structure: + struct gui_driver + { + void (*setrootmenu)(struct uih_context *c, char *name); + void (*enabledisable)(struct uih_context *c, char *name); + void (*menu)(struct uih_context *c, char *name); + void (*dialog)(struct uih_context *c, char *name); + void (*help)(struct uih_context *c, char *name); + }; + + All function have `uih_context' parameter. You don't need to worry +about it's contents. Just pass it to the called functions that require +it. This parameter is for multiple window support, that is not +implemented yet. + + The `setrootmenu' function expected to draw root menu according to +the menu called `name'. To get menu fields you might use following +piece of code: + #include <ui.h> + #include <xmenu.h> + + .... + + int i; + menuitem *item; + for (i = 0; (item = menu_item (name, i)) != NULL; i++) + { + if (item->type == MENU_SUBMENU) { + /* This field is submenu. You might call here + function to construct submenu. item->shortname contains + name for submenu */ + } + /* add menu field here. + + You might check flags here: + item->flags&MENUFLAG_CHECKBOX + field have beckbox + item->flags&MENUFLAG_RADIO + field is part of radio button group. In current implementation + there is one radio button group per menu. + + in both cases you might call: menu_enabled(uih, item) to see + if item is checked or not. + + item->name contains field's text + + item->key contains hotkey (one letter string in current + implementation) + } + Once field is selected, call function `ui_menuactivate(item, NULL)' +where `item' is pointer to `menuitem' record of selected field. + + Function `enabledisable' is called when checkbox or radiobutton +state is changed. The `name' parameter match to `item->shortname' of +changed field. So you need to browse all created menus, compare +`item->shortname' and in case it match, call `menu_enabled' to obtain +new state. For radiobuttons only enable events are noticed. Your code +is expected to automatically disable all other radiobuttons in the same +submenu. + + function `menu' works in similar way to `setrootmenu' but displays +popup menu. + + Function `dialog' is called for dialogs. The function should look +like: + menuitem *item = menu_findcommand(name); + menudialog *dialog = menu_getdialog(uih, item); + int i; + for(i=0; dialog[i].question; i++) + { + /* Construct dialog, where left side contains labels with + dialog[i].question. Right side contains input entities based on the + dialog[i].type. Dialog[i].type is one of the following: + + DIALOG_INT: integer value input. The default value is: dialog[i].defint + DIALOG_FLOAT: floating point input value (long double, where availble + exact). Default value is dialog: dialog[i].deffloat + DIALOG_COORD: complex value floating point input (two floats), default + values are dialog[i].deffloat and dialog[i].deffloat2 + DIALOG_STRING: string input. default value is dialog[i].defstr + DIALOG_IFILE: input file + DIALOG_OFILE: output file + default mask is dialog[i].defstr + DIALOG_CHOICE: choice between various strings. + retype dialog[i].defstr to char ** to get pointer to NULL terminated + array of the choices. + } + Once dialog is filled by user, gui_driver is expected to allocate +array of union `dialogparam' `dialogparam': + dialogparam *p = calloc (sizeof (*p), nitems); + fill selected values. `p[i].dint' is used to pass integer value, or +number of DIALOG_CHOICE selection, `p[i].number' is used for floating +point number, `p[i].dstring' for strings and filenames, +`p[i].dcoord[0]' and `p[i].dcoord[1]' for complex values. + + The string values are expected to be in separate malloced chunks. +Once array is filled, call `ui_menuactivate(item, p)'. + + The function `help' is used to display help about given topic. To +implement it you might eighter convert XaoS help file to some native +format, or use xshl library to render help page for you. To render xshl +page use: + #include <xshl.h> + xshl_line *lines; + int getwidth (void *data, int flags, char *text) + { + return width of text with given flags + flags is mask of the following: + XSHL_BIG - large text + XSHL_EMPH - emphatized text + XSHL_MONOSPACE - monospaced text (typewriter) + XSHL_LINK - line (should be underlined or so) + XSHL_WHITE + XSHL_RED + XSHL_BLACK - color of text (not very meaningfull here) + XSHL_RIGHTALIGN + XSHL_CENTERALIGN - alignment of the text + + } + lines = help_make (name, getwidth, textheight, largetextheight); + if (lines == NULL) + lines = help_make ("main", getwidth, textheight, largetextheight); + Now you might use `lines' to draw the help. It is pointer to the +arraw of structures: + struct xshl_line { + int y; + struct xshl_item *first; + }; + `y' is possition of the line from beggining of text and first is +pointer to the blocks of texts on the line. Last line contains NULL +pointer in the first section. + + `first' is linked list of the structures: + struct xshl_item { + struct xshl_context c; + char *text; + int x; + int width; + struct xshl_item *next; + }; + + you might draw text `text' on the possition `x' (and `y' from the +line record) using style described by `xshl_context': + struct xshl_context { + int flags; + char *linktext; + }; + `flags' have same meaning as in `getwidth' section. `linktext' is +name of the next help page in case field have XSHL_LINK atribute. + + As an example of `gui_driver' see win32 driver code. + + +File: xaosdev.info, Node: eui, Next: ui-helper, Prev: gui-driver, Up: Top + +Writting an external user interface +*********************************** + + This part describes, how to make an external user interface--it is +the separate program, which makes an window with all menus and dialogs. +It uses XaoS engine for calculating the fractal as separate process. +This design brings many advantages--the external GUI implementation +should have an "native look" for given platform and should contain many +extensions, such as multiple windows etc. Also all calculation are done +in the multitasking and user interface is usable even when engine is +busy. + + The X window provides a way, when program draws into other's +window--"master" program creates window and sub-window, where he wants +to have fractal, then calls engine with `-windowid' NUMBER_OF_WINDOW +parameters. It instead of creating new window uses specified window. +Most famous example of such cooperation is probably +ghostscript/ghostview. + + Other windowed environments probably provides similar way for +cooperation. At others it should be implemented using shared memory, so +it should work at most platforms, I expect. + + Of course, you might also design UI as separate button box in +another window, like most of animation players, or Imagemagick have. In +fact external GUI should be very similar to Imagemagick style. + +basic concept +============= + + The UI implementation has function to disable it's GUI functions. +Because of the function registry, all it's menus and dialogs are +described in the fairly simple database. This database is mapped also +to the scripting language similar to scheme. So the external UI +implementation just translate the actions into this scripting language +and sends it trough pipe. + + This commands should be created automatically from the database, as +well as menus and dialogs, so UI don't need to have special code for +various XaoS features. At the beginning it should use XaoS' command +`(print_menus)' to force him to send information about database, then +build menus using this information. + + For this you need just some equivalent to UNIX pipes, so again I +expect it is doable at most platforms. + +starting XaoS as slave process +============================== + + One of the first thinks, engine needs to do is to initialize XaoS in +right mode to work as slave process. For this you need to do several +thinks: + + * Open the pipe + + * Disable builtin GUI + + * Read menu hierarchy (this is optional--GUI can also have all menus + coded into it. But it is not recommended, since it will make + problems with future adding new features) + + Opening pipe is done via `-pipe' option. It takes one parameter, +which is name of FIFO you want use. If you specify "`-'", XaoS will +read input from stdin. + + To disable XaoS GUI use option `-nogui'. This will disable all menus, +dialogs and help text. + + To read menu hiearchy just add `-print_menus' parameter and then +parse XaoS's output. This will print the whole hierarchy. In case you +are building menus at the time, they are selected, you might prefer +usage of the command `print_menu'. It prints just one menu without it's +sub-menus, so it's output should be directly used for building it. It +takes one string parameter, which is name of menu you want to print. To +print root menu use `"root"'. Option should look like this: +`-print_menu root'. + + Under X Window you need also specify the `-windowid'. Also the +`-shared' is quite recommended. Otherwise in pseudocolor visuals XaoS +will create it's own colormap, wich will most probably collide with +UI's colormap and XaoS or UI will have false colors. If you have any +idea, how to avoid this, let me know. + + You might also let user to specify some extra parameters from the +command line. You should simple add the to the end of command line. The +`-nogui' and `-print_menus' commands must be first for the simple +reason: XaoS parses it's command line in the early initialization +stages. Some commands (like `-print_menus') should be processed at this +time, while others (like `-loadpos' needs to have working engine. This +commands are queued and processed later, once engine is initialized. +In case some such command is before `-print_menus' XaoS will decide to +keep same order of commands, so it will queue `-print_menus' too. This +will case, that menus will be printed much later and startup will be +slower. + + So the proper calling sequence for the user interface under X should +look like: + + xaos -nogui -print_menus -windowid <id> -share -pipe - [OTHER OPTIONS] + +Parsing the menu structure +========================== + + The structure is printed menu by menu. Each menu contains an header, +some entries and `endmenu'. Whole listing from `print_menus' is +terminated by `endmenus'. + + The header starts with `menu' and then contains an identifier of menu +and full name. Such as: + + menu "fractal" "Fractal" + + Then each entry has its own line. It starts by type, which should be +`submenu' or `menuentry'. + + `submenu' has similar format to header--fullname of menu and +identifier. + + `menuentry' adds next few fields. It has an type of entry, which +should be `normal', `radio' or `checkbox'. `radio' and `checkbox' are +followed by `on' or `off' specifying whether it is enabled or disabled. +The radio-buttons don't have explicit information about groups they +belongs to. For now I just expect, that each menu contains just one +such group, so it is clear. + + Then set of flags should follow. Currently two flags are defined. +`dialog', wich specifies, that function has dialog, and +`dialogatdisable'. By default, dialog for check-boxed functions are +displayed just in case they are enabled. The second flag reverses this +behaviour. It is now used for `mandlebrot' function, which behaves in +this style. When you disable it, user is prompted for the Julia seed. + + So specification should look like this: + + menu fractal "Fractal" + submenu "formulae" "mformula" + submenu "Incoloring mode" "mincoloring" + submenu "Outcoloring mode" "moutcoloring" + submenu "Plane" "mplane" + submenu "Palette" "palette" + menuentry "Mandelbrot mode" "uimandelbrot" checkbox off dialogatdisable dialog + menuentry "Perturbation" "uiperturbation" checkbox off dialog + menuentry "View" "uiview" normal dialog + menuentry "Reset to defaults" "initstate" normal + endmenu + +Activating functions and dialogs +================================ + + Once the menu structure is built and user selects some item, it +should be activated. It is done by simple command: `(NAME)'. Once "`)'" +is sent, command is executed by XaoS. + + Check-boxed functions has one extra parameter--`#t' to enable them +and `#f' to disable. So if you want enable item `autopilot' send: +`autopilot #t' + + Radio-buttons don't have any such special parameter--because +disabling radio-button is nonsense. + + In case, item has flag dialog enabled, engine expects that UI will +make dialog first, ask user of values and then call function with +parameters. UI needs first to know, what parameters function expect. +It is done by sending command `(print_dialog "NAME")'. XaoS replies +with dialog specification very similar to menu specification. + + It has header `dialog' followed by the name of function. Then one +dialog entry per line is sent. it is started by `dialogentry' followed +by question UI should display. The is type, which should be one of the +following: +`integer' + Integer number such as `123' + +`float' + Floating point number such as `123.123' + +`string' + String such as `"ahoj"' + +`keyword' + String such as `'ahoj'. The keywords are mostly similar to string, + except they can not contain space. They are used for example for + specifying formula type. Strings are used for printing texts etc. + +`inputfile' + +`outputfile' + Here UI should display file selection dialogs. With `outputfile' + it is also good idea to check, whether file exist and in this case + make some overwriting dialog too. + +`onoff' + Boolean value (`#f', or `#t') + +`complex' + Complex value--two floating point numbers such as `123.123 123.123' + +`choice' + Choice between some keywords. Those keywords are send after + `choice' in enclosed the `{' `}'. Last information at the line is +the default value in the same format as examples above. For files, the +default value is in format `"[PREFIX]*[EXTENSION]"'. + + Some examples: + + customdialog "uiview" + dialogentry "center:" complex 0.000000 0.000000 + dialogentry "Radius:" float 0.000000 + dialogentry "Angle:" float 0.000000 + enddialog + + dialog "load" + dialogentry "Filename:" inputfile "fract*.xpf" + enddialog + + customdialog "color" + dialogentry "Color" choice {white black red }white + enddialog + + To activate function, send command which contain function name, +possible `#t'/`#f' in check-boxes and parameters in the same order as +in dialog, same format as in examples, separated by the space. Such as: + + (uiview 0 0 0.5 0) + (load "text.xpf") + (color 'white) + +Synchronization +=============== + + In some cases, XaoS can change radio-box and check-box values. (like +when user pressed a key, or loaded some file). So all changes are sent +to GUI, wich should inform about this. They are sent to standard output +in following format: + + checkbox "name" on/off + radio "name" on/off + + So your GUI should parse this and change it's menus when necessary. + + Also XaoS's menus can contain more distinct trees. In some cases +(like when animation replay is active) root of menu structure should +change. The XaoS sends command: + + root "name" + + Also user can press keys, which normally displayed menus, dialogs or +help. Then XaoS sends commands: + + menu "name" + dialog "name" + help "topic" + + All this commands should be taken into account by GUI, or should be +ignored. + +help +==== + + XaoS's help is in the simple hypertext language. In order to +simplify it's parsing I've made an xshl and help libraries. So making +of help window should be quite easy. Just call help function: + + - Function: struct xshl_line *help_make (char *COMMAND, int GETWIDTH + (void *, int FLAGS, char *TEXT), int WIDTH, int SMALLHEIGHT, + int BIGHEIGHT); + and you will receive of listings of text with positions, where to +print into window. + + `command' parameter is topic of help. `getwidth' function is +function, wich returns width of given text. `width' is width of window, +`smallheight' is height of small font and `bigheight' is height of big +font. + + Please ask me for more details if necessary. + + And thats all. Good luck with coding. + + +File: xaosdev.info, Node: ui-helper, Next: xthreads, Prev: eui, Up: Top + +UI-helper library +***************** + + UI helper library takes care to all XaoS' engine functions and +features and gives the higher level API, which is quite easy to +understand. If you want to write completely new user interface +(replacement for the ugly interface--not just new bindings for native +menus or external user interfaces) or you want to use XaoS engine in +your program as an library, you will probably want to use this library. + + It's API has many calls and features. This section gives just brief +overview of it's calls. Please ask me about details. + +initialization +============== + + To initialize ui helper library, you need to prepare an palette and +image. Palette is created using palette library calls `createpalette'. +Creating truecolor palette should look like this: + + struct palette *pal = createpalette (0, 0, TRUECOLOR, 0, 0, NULL, + NULL, NULL, NULL); + + For details about creating palettes see `ui.c' or ask me. + + To create image call: + + struct *image img = create_image_mem (width, height, 2, pal, + pixelwidth, pixelheight); + + This creates image in the memory. If you want to create it in your +own buffers, you might use `create_image_cont' or `create_image' calls. +Again see `ui.c'. + + Then it is time to fire up main library: + + struct uih_context *uih = uih_mkcontext (0, img, passfunc, + NULL, NULL); + + The `passfunc' is called when engine is calculating. It might process +events and display process information. It should look like this: + + static int + ui_passfunc (struct uih_context *c, int display, char *text, float percent) + { + /*process events */ + if (uih->display) + { + uih_drawwindows (uih); + /*display */ + } + if (display) + { + if (percent) + sprintf (str, "%s %3.2f%% ", text, (double) percent); + else + sprintf (str, "%s ", text); + /*display it */ + } + } + It might set `uih->interrupt', if it wants to interrupt current +calculation. + + You also might load the catalog file in order to make tutorials +working: + + uih_loadcatalog (uih, "english"); + + Since this ui_helper library is fully functional and you might enter +the main loop. + +main loop +========= + + UI helper library does an timing primitives. So it expect an +standard form of the main loop. It asks the program to display changed +image when necessary. Library also use timerlib for it's timing. So +read section about this library, since you might use it for your +purposes too. + + Main loop should look like this: + + while (1) + { + if (uih->display) + { + uih_prepare_image (uih); + uih_drawwindows(uih); + /*display current image buffer*/ + } + uih_update (uih, mousex, mousey, buttons); + if ((time = tl_process_group (syncgroup, NULL)) != -1 && + !uih->inanimation) { + /*relax given time in usec - wait of events etc..*/ + } + /*and repeat*/ + } + +calling functions +================= + + UI helper library has many functions declared in `ui_helper.h' for +various actions. There is too much of them to describe, but their names +are quite informative, so I hope you will not have problems. + + You might also use XaoS function registry, which does all this stuff +for you. You will just draw menus and dialogs based at this registry +and automatically all features will be available. So if you are writing +an ordinary user interface, this is the preffered way. + + Note that `ui_helper' library is not reentrant, so you can't call +most of this function from the `passfunc'. If you are using registry, +activating function handles this automatically and queues functions +when necessary. To process them you need to flush queue in the main +loop as follows: + + static void + processbuffer (void) + { + menuitem *item; + dialogparam *d; + if (uih->incalculation) + return; + while ((item = menu_delqueue (&d)) != NULL) + { + menu_menuactivate (item, d); + } + } + +closing library +=============== + + This is done using: + + uih_freecontext (uih); + + One implementation of user interface at the top is ugly interface. +See dirrectory `src/ui'. Another, much simpler is `render.c', which does +animation rendering. + + +File: xaosdev.info, Node: xthreads, Next: filters, Prev: ui-helper, Up: Top + +XaoS thread library +******************* + + This description should be useful for those, who want to port XaoS +into multiprocessor platforms and those, who want to implement some +filter or other relatively computational expensive code. Note that +thread library should be mapped into nothread calls, in case host does +not allows multi-threading or it is not SMP architecture (since this +library is used only to distribute calculation into other CPUs) + + XaoS thread library is simple map of few functions required by XaoS +to system library for threads. + + It has following variables: + + - Variable: ethreads + This is set to 1 in case that threads are enabled + + - Variable: nthreads + Number of threads + + It and following calls: + + - Function: void xth_init (int THREADS) + This function initializes threading library (starts threads, sets + ETHREAD to 1 and NTHREADS to n. THREADS parameter should be set to + 0--auto-detection or number of threads users wants. In case threads + is set to 1, threading library is disabled and following functions + are mapped into those nothread_ equivalents defined in `xthread.h'. + + Note that threads are not identical--there is main thread (one + that called xth_init) that communicates with drivers, controls + calculation etc. and other tasks that are waiting to orders from + main task. They also can't use functions from xthread library. + + - Function: void xth_uninit (void) + This function UN-initialize thread library--kills child threads, + sets ETHREAD to 0 and NTHREADS to 1. + + - Function: void xth_function (xfunction *FUNCTION, void *data, int + RANGE) + This function is used in case, engine wants to perform some + operation at image in parael. It is expected to wait until all + threads are ready and start FUNCTION at all threads including + control one with following parameters: DATA--this parameter is + same as DATA passed to xth_function, TASKINFO--pointer to structure + taskinfo, that is platform depended (defined in `xthread.h') but + must have at least field `n', that holds number of thread (control + thread has 0 and other numbers in range 1 - NTHREADS). Next two + parameters is range of image, function is expected to do action. + Xth_function is expected to divided RANGE into NTHREADS equal + pieces and pass always start of piece and start of next piece + (RANGE in case of last one). Function does not wait for other + threads at the end and returns immediately to main thread after + FUNCTION returns. + + This function is called approx. 5-10 times per frame + + - Function: void xth_sync (void) + This functions waits until all threads are ready for next order + from main task. + + This function is called approx 5-10 times per frame + + - Function: void xth_bgjob (xfunction *FUNCTION, void *DATA) + This function is expected to behave as follows: look if there is + any thread waiting for orders, if so, ask him to call FUNCTION + with similar conventions as in xth_function except that range + parameters are set to 0. Otherwise it starts function in normally + (at foreground). + + This function is called once per frame. + + - Function: void xth_nthread (struct taskinfo *S) + This function should be used to determine number of current + thread. Do not use `taskinfo->n' instead since in case threads are + disabled, it should be defined to 0 and that allows optimizer to + perform better optimizations. This function should be called by + all threads. + + - Function: void xth_lock (int N) + + - Function: void xth_unlock (int N) + Lock/unlock lock number N. At least `MAXSEMAPHORS' locks must be + available. + + Note that locks are used always for very short fragments of code + so they needs to be fast. So spin-locks are maybe better than + Dijskra semaphores. Untested. They are called once per calculated + line/row during zoom and once per approx 10 pixels during + calculation of new image. + + - Function: void xth_sleep (int N, int L) + It is expected to atomically unlock lock L and sleep in queue N. + At least `MAXCONDS' queues must be available. After it is waked + up, lock L again. This mechanism is used by calculation of new + image algorithm, but it is designed to minimize its calls, so I + expect they should be called once or twice. + + - Function: void xth_wakeup (int N) + Wake up some thread from queue N. Lock used by sleep calls is + locked in this cases. Function should also wake up all threads if + such operation is not supported by host API. With luck, this + function should not be called at all. It should be called by new + image calculation routines in case queue is empty. This happens in + case of 50 threads but happens rarely at two or eight threads + according to my tests. + + - Function: void xth_wakeall (int N) + Similar to wakeup but wake up all threads. + + +File: xaosdev.info, Node: filters, Next: algorithm, Prev: xthreads, Up: Top + +Filters +******* + + This is a brief description of filter system used internally by XaoS. +Filters in XaoS provides an object oriented interface to every part of +XaoS engine. Main filters are: User interface implemented in ui_helper.c +and zooming engine implemented in zoom.c. Filters are connected into an +queue--at the beginning there is just two filters here(zoom and ui) but +later additional filters should be inserted into the middle of queue +like an stereo-gram generation etc. The queue supports operations like +remove filter, add filter and initialize. + + In the calculation every filter should use data calculated by filter +lower in the queue. Data are stored into image. So for example +stereo-gram filter should use fractal generated by zooming engine and +create an stereo-gram. + + This makes XaoS's code more flexible and makes easy future +enhancements like different zooming engine, image rotation, other +special effects, plug-ins and some other funny stuff since interface of +each such part is well defined and each filter has quite good control +over his child. So stereo-gram filter should change palette, force +zooming engine to change depth, width and height of calculated image to +fit his needs and so on. + + This document describes mainly creating of filter like stereo-gram +generator i.e. filter placed into middle of queue since I don't expect +there will be many people creating "terminal" filters (zooming +engines/user interface layer) note that different user interface is +possible since user interface layer is not the real user interface just +set of high level functions that should be called by main application +like set_view. So in case you want to use XaoS as an calculation engine +in your program this document is probably not for you. + + Each filter is defined by filter_action structures as follows: + struct filteraction { + char *name; + char *shortname; + int flags; + struct filter *(*getinstance)(struct filteraction *a); + void (*destroyinstance)(struct filter *f); + int (*doit)(struct filter *f,int flags,int time); + int (*requirement)(struct filter *f,struct requirements *r); + int (*initialize)(struct filter *f,struct initdata *i); + void (*convertup)(struct filter *f,int *x,int *y); + void (*convertdown)(struct filter *f,int *x,int *y); + void (*removefilter)(struct filter *f); + }; + This structure describes static filter's parameters (like its name) +and basic set of methods required for communication with resto of XaoS. +The name field describes filter's name like "An random dot stereo-gram +generator". Name is displayed by ugly interface in filter's menu. So it +is expected to be descriptive and shorter than 30 characters. The short +name is one word long name for filter like "stereogram". This name is +used by save files, possibly by command line parameters. Simply +everywhere where user should need to write it and writing long +descriptive name should be just wasting of time and disk space. + + Flags field is kept for future enhancements and is expected to be 0 +for now. + +Creating / destroying of instance +================================= + + Functions getinstance and destroyinstance are equivalents to +constructor and destructor in OOP. Getinstance is expected to create +and fill following structure: + + struct filter { + struct filter *next,*previous; + struct queue *queue; + struct filteraction *action; + struct image *image,*childimage; + struct requirements req; + struct fractal_context *fractalc; + void *data; + char *name; + int flags; + void (*wait_function) (struct filter *f); + /*stuff for wait_function*/ + int pos,max,incalculation,readyforinterrupt,interrupt; + char *pass; + }; + Altrought this structure seems to be long and complex, most of +fields are unused at this time and rest of them are filled +automatically by function: + + - Function: struct filter * createfilter (struct filteraction *FA); + That should be used to create instance. Only possibly interesting + field is data. It's pointer reserved for filter's internal use. So + it should be pointer to filter's internal variables if required. + Following is example implementation of get-instance with + allocating of such additional structure. In case nothing similar + is required you should use directly createfilter at getinstance's + place. + + static struct filter *getinstance(struct filteraction *a) + { + struct filter *f = createfilter(a); /*create filter structure*/ + struct stereogramdata *i=calloc(sizeof(*i),1); + /*allocate internal variables*/ + /*initialize your variables here*/ + f->data=i; /*add pointer to internal data*/ + return (f); + } + + The destroyinstance is expected to free memory used by filter +structure and all internal data of filter. To free filter structure use +normal free(filter); So implementation of such function should look +like: + static void destroyinstance(struct filter *f) + { + destroyinheredimage(f); + free(f->data); + free(f); + } + The meaning of destroyinheredimage will be described later. + +Initialization +============== + + During initialization phaste each filter says to his parent what kind +of images it supports (this should depend on images supported by his +child), parent chooses best supported image format for his purposes and +gives it to the child. Initialization is done in two pases. + + First pass start by lowest filter in the queue and each filter +passes to his parents requirement structure. + + Second pass starts by the highest filter and each filter passes to +child an image and some other stuff. Then calculation should begin. + + Queue needs to be reinitialized after creating, resizing, +adding/removing of filter and similar operations. + + First pass is implemented using require function. This function is +expected to take care at child's requirements it received as parameter, +fill requirements structure and call require function of his parent +filter. + struct requirements { + int nimages; + int supportedmask; + int flags; + }; + The nimages field should be set to 1 or 2. In case it is 2, parent +filter must pass image with two buffers. Note that in case it is 1, +parent should pass image with two buffers too. + + Supported mask is mask of supported image types by filter. Image +types are following: +`C256' + An normal 8bpp image with palette + +`TRUECOLOR24' + An 24bpp truecolor image with 8bits for each color. + +`TRUECOLOR16' + An 16bpp truecolor image + +`TRUECOLOR' + An 32bpp truecolor image with 8bits for each color. + +`LARGEITER' + An 16bpp image but w/o colors. It is expected to hold number of + iterations it should be also tought as 16bpp grayscale image + +`SMALLITER' + Similar to `LARGEITER' but 8bpp + + In case you don't worry about palettes, allocations of colors and +you do just some operation with bitmap, so you worry just about depth +of image you should use mask of following: `MASK1BPP' for 8 bit images, +`MASK2BPP' for 16bit and so on. + + The latest field of requirements structure is flags. It mask from +following constants: + +`IMAGEDATA' + in case your filter requires data from previous frame untouched. + In case this is not set, filters should reuse your image and + change it. But some filters like and motion blur or zooming + engine requires data from previous frame to construct new, so + this flag should be set there is no more flags supported at the +moment. Function require should also save child's require structure +into filter->req for later use by initialize pass. So you should look +like: + static int requirement(struct filter *f,struct requirements *r) + { + f->req=*r; /*Save an child's requirements*/ + r->nimages=1; /*Just one image is required*/ + r->flags&=~IMAGEDATA;/*unset the imagedata field*/ + r->supportedmask=C256|TRUECOLOR|HICOLOR|REALCOLOR; + /*mask of all supported image types*/ + return (f->next->action->requirement(f->next, r)); + /*call parent*/ + } + Next pass is main initialization. It goes in opposite order(from +parent to child) and child's infers some stuff from parent like images +etc... The initialize structure receives an initdata structure: + struct initdata { + void (*wait_function) (struct filter *f); + struct image *image; + struct fractal_context *fractalc; + int flags; + }; + an wait_function is function called by filter during calculation that +lets the parent filters(usually user interface layer) to inform user +how calculation continues. Image is an image expected to be filled by +image in calculation phaste. Fractalc is pointer to structure that will +contain information about fractal during calculation(like formula type +etc...) Flags is mask of following constants: +`DATALOST' + this is set in case, that data in image was lost(image was cleared + or resized or freshly allocated). Filters that uses data from + previous frames should take care to this flag. Zooming engine for + example recalculates whole image since pixels from previous frame + was lost. Note that data should be lost also in case, filter + receives different image that in previous initialization since + some filter behind was removed. An inhering process is done +using function: + + - Function: void inhermisc (struct filter *F,struct initdata *I); + This function sets fields in filter structure like as fractalc or + wait_func. Inhering of image is quite complex, since new image + needs to be prepared for child. In order to save memory it is + highly recommended to use same image or at least same memory for + data when passing to child. But this is not allays possible. + Following function implements heuristic to do this: + + - Function: int inherimage (struct filter *F,struct initdata *DATA, + int FLAGS, int WIDTH, int HEIGHT, struct palette *PALETTE, + float PIXELWIDTH, float PIXELHEIGHT) + You should call this function in your initialize pass. It fills + image and childimage in filter structure, prepares initdata for + child and creates image for child. Note that it should fail in + some cases and return 0. In this case filter is expected to + interrupt initialization and return 0 too. + + An FLAGS parameter is mask of following constants: + `IMAGEDATA' + in case your filter requires data from previous frame + + `TOUCHDATA' + In case your filter touches data in output image. This is + very usual but there is some filters (like interlace or + subwindow that don't) + + `NEWIMAGE' + Set in case your filter can not deal with shared images + (images that have input data in same memory are as output) + WIDTH and HEIGHT should be set to 0 in case you want same + width/height as in parent image or width and height of image you + want to pass to child. PALETTE is palette of image you want to + pass. Set to `NULL' if palette should be inhered from parent's + image (usual). PIXELWIDTH and PIXELHEIGHT specifies physical size + of pixel in centimeters. If set to 0 they are inhered from + parent's image. + + In case you use inherimage mechanism you also must call +destroyinheredimage in destroyinstance function and updateinheredimage +at the beginning of calculate function. + + Example implementation: + static int initialize(struct filter *f,struct initdata *i) + {struct stereogramdata *s=f->data; + inhermisc(f,i); + if(!inherimage(f,i,TOUCHIMAGE,0,0,NULL,0,0) return 0; + /*initialize here*/ + return(f->previous->action->initialize(f->previous,i)); + } + Also note that fractal context hold pointer to fractal palette. In +case You don't change image palette everything is OK. But in case +child's image differs from parents image, there should be two +behaviors--fractal's palette is child one (this should be common for +example in conversion filters ( 8bpp to truecolor etc)) or fractal's +palette is parent's one (like in edge detection filter). By default +fractal's palette is kept to parent's one. This should be changed by +setfractalpalette call. It has two parameters--filter structure and +palette. When you pass as palette child's palette, fractal's palette +will be changed to child. In case you pass NULL. Changing of palette +will be disabled (like in motion blur filter in 8bpp mode). Note that +this is changed just in case you still have access to fractal palette. +Some parent should redirect palette before. Than this function does +nothing. + +Caluclation +=========== + + Main calculation is done using doit function. It is expected to call +child's calculation function when required and apply filter at output. +It receives flags. Only flag in `INTERRUPTIBLE' for now. It is mainly +for zooming engine so I do not describe it here. But filter is expected +to pass this flag to child. Next parameter is time in milliseconds that +expired since last doit call. It should be used to calculate speed of +animation. + + Calculation loops returns flags. Flags is mask from following +constants: +`ANIMATION' + in case filter performs some animation and expect that calculation + will be called again soon + +`CHANGED' + in case something changed in output image (usual) + +`INEXACT' + This is enabled by zooming engine in `INTERRUPTIBLE' mode in case + that time exceeded. + + An doit function changes image. Image structure contains following +fields significant for you: +`bytesperpixel' + number of bytes per pixel (image depth) + +`palette' + palette of image. + +`currlines' + array of pointers to beginnings of every scanline of image + +`oldlines' + array of pointers like currlines but for previous image in case + doublebuffering is enabled + +`nimages' + set to 2 in case doublebuffering is active + +`flipimage' + pointer to function that flips oldlines and currlines. + + palette structure contains following significant fields: + +`type' + type of palette/image (`C256', `TRUECOLOR' etc...) + +`size' + number of allocated entries + +`pixels' + array of allocated entries. Conversion table from number of + iteration to pixel value. + +`rgb' + Rgb values for pixels (`NULL' for `TRUECOLOR', `HICOLOR' and + similiar types) + + To make easier writing calculation loops for different depths +`pixel8_t', `pixel16_t' and `pixel32_t' are predefined. You also can +use include system as in edge detection filter, that lets you write +calculation loops just once and use cpixel_t and it will be compiled +for every bitmap depth. See edge detection filter (engine/edge.c and +engine/edged.c) for implementation details. + +Conversion +========== + + Convertup and convertdown functions are used for converting screen +coordinates to position in fractal and back. Convertup is function that +receives coordinates in child's image and is expected to convert them +into coordinates in parents image and call parent's convertup function. + + Convertdown is reversed(from parent to child). + + In case coordinates respond 1:1 you should use convertupgeneric and +convertdowngeneric. In other case implementation should look like: + + static void convertup(struct filter *f,int *x,int *y) + { + *y*=2; + *x*=2; + if(f->next!=NULL) f->next->action->convertup(f->next,x,y); + } + static void convertdown(struct filter *f,int *x,int *y) + { + *y/=2; + *x/=2; + if(f->previous!=NULL) f->previous->action->convertdown(f->previous,x,y); + } + +Removing of filter +================== + + Before filter is removed from queue, removefilter function is called. +It is expected to clean up thinks filter changed. Should be NULL in +most cases. + +Registering of filter +===================== + + Once filteraction structure is filled, filter is done and you should +try to enable it. To enable it in user interface you need to edit +ui/ui_helper.c, add filter into uih_filters structure and increase +uih_nfilters. Note that order of filters in uih_filter is significant, +since same order is kept in filter queue, so you should specify if you +want to be called before/after filter xy. + + Then it is high time to start experimenting. + + Good luck! + + +File: xaosdev.info, Node: algorithm, Next: timerlib, Prev: filters, Up: Top + +Algorithm description +********************* + + The main idea behind XaoS is that it is not required to calculate the +whole image every frame. Most pixels are already calculated in the +previous frames. You usually don't have exactly the pixels you want, +but all within a range lower than a step between pixels are acceptable. +That is why the image flicker a bit and why points do not blink +randomly as in recalculated animations. + + This document describes some of the most important algorithms in XaoS + * Saving Previous Pixels + + * Approximation Algorithm + + * Moving Pixels to New Positions + + * Calculating New Pixels + + * Symmetry + + * Calculation of Mandelbrot Set + + * Dynamic Resolution + + * Autopilot + +Saving Previous Pixels +====================== + + Ideally, all recalculated points should be saved and used for +building successive frames. I could not figure out a practical way to +implement this. To save all frames for half an hour would require 24 Mb +of memory, and searching the saved frames would be more computationally +expensive than recalculating an entirely new frame. + + One way was later used by program Frang. It remembers all pixels as +x,y and value fields and when it builds new image, it draws all pixels +to it and then browses image and fills it by new pixels. Possibly some +rle cache should be used for calculated pixels. Frang actually uses +algorithm, that takes away pixels out of screen, so it behaves exactly +in same way as algorihm described here. At the other hand, this method +seems to require much more memory than XaoS algorithm and drawing +pixels/browsing image cost quite a lot, so algorithm described here +seems to be faster. Since it never requires examining of whole image +and new image is constructed using block move operations. + + For this reason only the last generated frame is used as reference. +This way the memory requirements are proportional to xsize * ysize. It +can be shown that this method is only about 2-5% slower during zooming. +Of course unzooming back to once browsed areas is much slower. + + Because only the previous frame is used, another optimization can be +performed: Imaginary and real parts of the calculated image are not +precise since they are the result of successive iterations of same +algorithm. In order to prevent errors from being distributed to the +following frames their exact coordinates need to be known. +Fortunately, it isn't necessary to save their values since it is known +that all real components in a row and all imaginary components in a +column are equal. Thus, the only things that must be saved are the real +components for every row and the imaginary components for every column. + + This allows for a substantial speed-up in approximation because the +calculation requires less data. Of course, some rows and columns fall +out of the threshold and new ones need to be calculate to fill in the +gaps in the frame. + + Obviously, much less work is done. There are only xsize + ysize +calculations instead of xsize * ysize. So the main loop in XaoS looks +like this: + * Make approximations for rows + + * Make approximations for columns + + * Move old pixels to their new positions + + * Calculate pixels for which there is no good approximation for + their row + + * Calculate pixels for which there is not good approximation for + their column but there is one for their row + +Approximation Algorithm +======================= + +Introduction to problem +----------------------- + + You can see that the approximation algorithm is central to the +implementation of XaoS. If the guess is incorrect the image will look +strange, boundaries will not be smooth and the zoom will flicker. On +the other hand, if it adds more new rows or columns than required, +zooming will become much slower. Also, in the instance of doubling +(i.e., using an old row or column more than once) the resolution will +lower. It is important to keep the increasing imaginary and real +components in the correct order. If a row and column of complex +coordinates follows one with higher coordinate values an improved +approximation can be attained by swapping their values. + + The algorithm needs to be relatively fast. It is only used for xsize ++ ysize values but if its speed is proportional to O(n^2), it can be +slower than a whole recalculation of the image. Speeds of O(n) or O(n * +log(n)) are acceptable. + +Some simple algorithms to solve it +---------------------------------- + + Initially, a very simple algorithm was used: + + Find the old row/column nearest the row/column that needs to be +regenerated. If the difference between them is less than one step +(step = (end - beginning) / resolution) then use it. Otherwise, +recalculate a new one. + + Finding the nearest row/column pair is very simple since it is always +greater or equal to the pair needing to be generated. + + Surprisingly, this simple algorithm has almost all the problems +described above. Doubling was fixed by lowering the limit to step / 2. +This cause a considerable slowdown so the limit was returned to step. +Instead, the algorithm was changed to search for only row/column pairs +that are greater than the previous frame's row/column pairs. This is +the algorithm that was used in version 1.0 + + This algorithm still added to many new rows and columns and did not +generate smooth boundaries. For version 1.1 a heuristic was added that +preferred approximating rows/columns with lower values. This way it did +not occupy possible rows/columns for the next approximation. The result +was a speedup by a magnitude of four. In versions 1.1 to 2.0 many +improvements were made to the heuristic to give it added performance. +The following example tries to explain how complicated the problem is +(O is the old coordinates and X is the values to be approximated): + X1 X2 X3 X4 X5 X6 X7 + O1 O2 O3 O4 O5 O6 O7 O8 + + The normal algorithm will aproximate X1 by O2, X3 by O4 but nothing +more. For the algorithm with threshold step instead of step / 2: + + O2 to X1 + O3 to X2 + O4 to X3 + O5 to X4 + O6 to X5 + O8 to X6 + + But this will fail with X7. The second algorithm which relies on +lower values will do the following: + + O1 to X1 + O3 to X2 + O4 to X3 + O5 to X4 + O6 to X5 + O7 to X6 + O8 to X7 + + O1 to X1 is wrong. And there is many and many other situations that +may occur. But you may see that the normal algorithm will calculate 4 +new rows/columns but the heuristic saves all of these calculations. + +Current algorithms used +----------------------- + + In version 2.1 work on this heuristic was disabled after I discovered +a surprisingly simple algorithm that solves all these problems. First I +decided to define exactly what is best approximation. This should be +done by defining a price for every approximation and choose the +approximation with the lowest price. Prices are defined as such: + + Approximating row/column x by y costs dist(x, y) ^ 2. + + This prefers two smaller approximation errors before a single larger +error and describes my goal quite well. + + The cost for adding a new row/column specifies when it is better to +do a bad approximation and when to add a new row/column. I use (4 * +step) * (4 * step). This means that the approximation is acceptable when +dist(x, y) < 4 * step. Otherwise, adding a new row/column costs less. +Now the best approximation is known. All that is required is a fast +algorithm to do this. Surprisingly, this is possible in linear time +using a relatively simple dynamic algorithm. It uses approximations of +length < n to make a guess at the length of n. It can start by +approximating one row/column and then again for two, three up to +xsize/ysize rows/columns. + + The algorithm starts by calculating prices for all possible new +positions for old row/column 1. Because of the pricing there are +maximally 8 new positions. (Other ones must cost more than adding new +row/column). Of course it is possible that there are no new positions. + + For calculating the price of approximations for row/column 2 I may +use previous one: Try new position n. Calculate the price and add the +best approximation for the previous (row/column 1) one that uses a new +position lower than n(prohibits doubling or swapping). This should be +one of 8 positions or eventually adding of new one and not using +row/column 1 at all. + + The same method can be used for the rest of the rows/columns. At the +end the best price may be found for the last row/column and return by +the way it was calculated. (For this I need the saved "calculated +using" values.) At this step the best approximation has been determined. + + To fill the table, 9 * n steps are required and n steps to backtrack +best approximation. The only problem is that this algorithm is still a +little slow (chiefly because of slow memory access on Intel +architectures). -But with some optimizing it works well. + + This algorithm is almost perfect except that it occasionally adds new +rows/columns to the wrong locations. It does not prefer to add new +rows/columns into holes. But it does not seem that this is the real +problem. The last optimization made was based upon the face that added +rows/columns do not have the exact real and imaginary components +calculated by (beginning + x * step) but lies at the average of left +and right neighbors. This makes the boundaries smooth and distributes +coordinates better. It also has the added benefit of making the input +better for future approximations. + + Another danger during implementation if this algorithm is that +adding new rows/columns into their ideal positions should cause +miss-ordered results, since some rows/columns should be off more that +is distance between them. To avoid this, I use algorithm that always +examine start and end of block of new rows/columns and linearly +interpolates value between them. Special care needs to be at the blocks +that start at the beginning or overs at the end. + + Implementation should be much faster using custom fixedpoint +routines--first recalculate values that 0 means start of image and +65536 means end. Than calculation is much cleaner. Values <0 and +>65536 are of screen, calculation is independent at scale and many +thinks should be recalculated--like tables for calculating price from +distance. Also dividing main loops into many specialized parts and +avoiding filing unnecessary parts of table helps. So current algorithm +in XaoS is about 5 or 6 times faster than first naive implementation. + +Moving Pixels to New Positions +============================== + + Since XaoS is using the approximation algorithm the following table +is filled for every row/column: + * calculate + + * oldpoint + + * position calculate is 1 if the current row/column is new and +needs to be calculated or 0 if no old pixels need to be moved. oldpoint +is a pointer to the old row/column that corresponds to the new one. This +pixel needs to be copied to the new location. position is the real and +imaginary components of the coordinates used for future approximations. +Because almost all points will be moved, the solution seems to be +simple: for every new point look at the row and column table; copy it +if required. + + There is the problem that this minimally needs three memory reads for +every pixel (read calculate, oldpoint and index of old point). This is +too slow, so a small optimization is performed. Instead rewriting the +piece of code in assembly, normal memcpy is used to move blocks of +pixels to their new locations. This minimizes the internal loop and +access can be done more quickly since memcpy is usually optimized for +each architecture. + + Using the row table, a list of blocks to move for every row is +created. With this new table all the pixels can be moved quickly. This +increased the speed of XaoS about four times and made this function so +fast that it is no longer a problem. (In fact, it takes much less +processing than all other parts of XaoS.) + +Calculating New Pixels +====================== + + The above optimizations make XaoS very fast, but another 30% increase +in speed is acquired by using a clever method for calculating the new +pixels. Many methods are known for saving calculations during the +generation of fractal images. The most powerful is boundary detection. +It relies on the fact that the Mandelbrot Set is connected with lakes. +You need only one pixel at the boundary, then traverse the whole set +and then fill the solid area inside. This method saves many +calculations but is too complex for adding just one line. Many claim +that it does not introduce any errors, but this is not true. It is +possible for a connected part of the lake to be so small that it is not +visible in smaller resolutions. In this case, boundary detection misses +the whole area. This algorithm is actually used just for calculating of +new images (i.e. at the startup). + + XaoS uses modification of method known as solid guessing. The pixels +at the boundaries of a rectangle are calculated. If they are all the +same you may assume that this rectangle does not does not contain +anything and fill it. + + This algorithm is further modified to operate on added lines. For +this it is at least as good as boundary detection and produces more +tangible errors. When adding a single line, the upper and lower line +may be examined for the nearest three pixels. If they are all the same +then it is assumed that 9x9 pixels are the same. This disables all +calculations inside solid areas and calculates as many points as +boundary detection. The only possibility of creating a larger error +with this method as opposed to boundary detection is in the instance +that the shape of the set is so sharp that it does not set any of the +tested points but comes from the right (i.e., uncalculated) location. +This situation is not very common. + + Later, rules were added for new rows and columns that crossed each +other. In this instance you can test only four pixels. This situation +is very rare. It is hoped that it does not introduce many errors. + + If multiple blocks of new lines need to be calculated there are not +reference pixels to use for solid guessing. Interlacing does the trick. +By calculating the odd lines without any guessing, the guessing +algorithm is now possible for the remaining uncalculated lines. This +simple trick saves about 30% of the calculation of the main Mandelbrot +image. + + A similar approximation can also be done for the X coordinate. This +makes it possible to improve solid guessing at even pixels because all +surrounding pixels are available, further reducing errors. + +Symmetry +======== + + Many fractals are horizontally or vertically symmetrical. This is +implemented in the approximation code. When there is no good +approximation available, try to mirror the opposite side if the line is +available. + + This method primarily speeds up the initial image. + +Calculation of the Mandelbrot Set +================================= + + Internal Mandelbrot calculation loop is unrolled--it calculates +first 8 iterations using normal method and then it expects that number +of iterations will be probably large so it switches into mode, where it +calculates iterations in block of 8 with one bailout test at the end. +When bailout is received, saved values from previous iterations is +restored and last 8 iterations are recalculated slowly to get exact +values. This helps a lot especially at Pentium, where conditionals in +floating point code is slow. + + Another stuff is periodicity checking. XaoS has both version of +loops--with an without periodicity checks. In most cases it uses +nonperiodicity checking version. Periodicity check version is used just +in case, some inside set pixel has been found during solid guessing +paste around. This is done mainly because periodicity checking version +of loop is significantly slower. + +Dynamic Resolution +================== + + The above optimizations often do not help enough and image +calculation is still too slow. One option was to reduce the framerate, +but a framerate lower than 5 frames per second is unbearable. Another +option is simply to calculate only the details that can be determined +within a time interval. + + Rows/columns not calculated are simple approximated by referencing +the nearest other row/column. The result is an image with larger pixels. +One problem is the fact that the order of calculating the rows/columns +is significant. Previous versions of XaoS simply calculated all rows +from top to bottom and then columns from left to right. Using the +dynamic resolution code with this algorithm would result in distorted +images. This was solved by adding priority to every row/column and +calculating the high priority row/column first. The algorithm for +adding these priorities is as follows: + * Find middle row/column of uncalculated block. Priority is the size + of the block (in floating point coordinates) + + * Start function for left block and right block + + This function produces quite good results. It tends to make same size +rectangles on the whole image and does not depend on resolution. + + Another interesting optimization is that during the zoom it is more +advantageous to calculate rows/columns in the center of the zoom +instead of the borders since these will be in the viewport longer and +the user is usually focusing on center of the zoom anyhow. + + This is done by simply adding to the calculated priority +normal_priority / (abs(newposition - oldposition) / step + 1). This +prefers rows/columns that do not move a great deal. Of course, +unzooming uses the formula reversed. + + The last variable to consider is the time interval for one frame. +Setting it too low makes the calculation slow. Setting it too high +makes the framerate too low. So the amount of time spent in other parts +of the program is calculated and multiplied by 5 to determine the +interval. If time is then lower than 15FPS, 15FPS is used instead, +since slower animations are unacceptable. At the other hand if it is +higher than 35FPS, it is set to 35FPS, since higher framerate is just +wasting of computer resources. When image is not animating, this values +is changed, so framerate is choose between 5FPS and 15FPS. This caused +that images are calculated quickly after zooms stops. + +Autopilot +========= + + Another interesting algorithm controls the autopilot. It is actually +quite simple. Interesting parts are found at the boundaries of the set. +It randomly looks around and zooms to the first area containing both +outside and inside set points. Some fractals (such as the Newton) do +not have points inside the set at all. In this case it selects a point +where many (more than 2) different colors are around. (i.e., It zooms +into noisy areas.) + + In the instance that there are no such areas, the autopilot will +unzoom. Also detects oscillating. + + Current implementation also does detection of out of range numbers +and randomly choosed points are choosed near the old one, to avoid too +often changes of direction. + +SMP support +=========== + + Since version 3.0 XaoS supports SMP. This is done using threads. +Most of XaoS routines should be threaded easily--for example +moveoldpoints just divides image into n equal part and each part is +proceeded by one processor. Only unthreaded part is realloc table +calculation routines. I don't see any way to paraelize it except it +calculates both--x and y approximation at one time (using two +processors). Another interesting algorithm to paraelize is boundary +trace. See comments `btrace.c' for discussion about current +implementation. Only problem of current implementation I see is +possibility, that calculation is divided into too many parts (realloc +tables, move points, calculate, symmetries, dynamic resolution) and +tasks needs to synchronize between each part. So this should be too +slow at real SMP box. + + +File: xaosdev.info, Node: timerlib, Next: registry, Prev: algorithm, Up: Top + +The timer library +***************** + + Timer library is library I did for timing in XaoS. But I found it +useful in many other programs (like demonstrations, games, animation +players and all other stuff that needs to be timed). So you should read +this description and possibly use it in your application and save some +coding time. + + There is many ways how to design of such timed application (game) + + 1. read user input, move badies, display and again this way has one + disadvantage. Speed of game depends on speed of computer. This + was acceptable in old times where only processor was Z80 :) but now + with wide variety of various hardwares such internal loop is + unacceptable + + 2. read user input, measure time since last loop and calculate step + for badies, move badies for set step, display and again. This way + fixes problem with speed. But moving badies just for calculated + step, that should differ a much is quite complex, usually + introduces complex calculation, floating/fixedpoint math and other + unnecesarry stuff that makes program long and introduces many bugs. + + 3. Set the fixed framerate that is high enough to make game smooth + but low enough to do whole internal loop in time. So internal loop + should look like: read user input, move badies, display, measure + time spent in loop an sleep rest of time until next frame. This + is quite popular scheme but has another disadvantage--game can not + be designed to use whole CPU power since on slower computers + internal loop should take longer time that is reserved for one + frame. Game will run slowly again. + + 4. To take away disadvantage of previous method, many games times just + moving of badies and user input. Other stuff like displaying + should be done in rest of time. In DOS games moving and user input + is often at asynchronous interrupt and drawing runs as main loop. + This solves problem in case that drawing of game takes + significantly longer time than moving of badies. This is quite + usual so this scheme works well. + + 5. previous scheme still has one problem--since timer interrupt works + asynchronously, there should happend many race condition, in case + moving takes longer time than time reserved from frame, computer + can crash. So this scheme should be enhanced into synchronous one + with exactly same result but avoiding problem with race condition: + + read user input, measure time spent by loop and calculate how many + simulated frame interrupts activated since last activation, if + zero sleep until simulated interrupt, move badies as many times as + required, display + + this is an combination of 4 and 3 and seems to be most comfortable + way for writing games but since main loop is now quite complex + many games don't do that. + + 6. there is still one small problem. Method 5 expect that moving takes + significantly lower time that displaying. This may not be truth. + Simple work around is to write moving routine, that should move + for x moves by faster way that calling move x times. This is often + possible and makes easy extension to scheme 5. This scheme allows + you to use very large maximal framerate (say 100FPS) and to have + same results as method 2 (that is maximally exact method) + + As you can see, designing of main loop isn't so easy. This is just +very simple example. More advanced application for example should want +to move one set of badies at one framerate and other at different +framerate. This requires two such timings. Another complication is that +there is many different ways to measure time exactly at different +platforms. Under Linux you can measure using gettimeofday but under DOS +this is exact just to 1/18 of second and thats too low for smooth +animation and so on. + + Thats why I decided to design portable easy to use timer library, +that makes easy to implement all described method, combining of them +and much more. During design I taken care at the following thinks: +quality of timing, how easy to use it is, speed, portability and to +minimalize inexpected situations (like race conditions in asynchronous +interrupts and so on) + +The name of game +================ + + Timer library operates with "timers". They should be created, you +should measure time since last reset, pause them or set "handler" and +"interval". But handler is not activated at given interval yet. Since +timer library is not asynchronous, you must activate them. + + For activating is used "groups". You should process group at some +place in your program. Then all timers in group are checked and their +handlers activated if required. When time spent since last activation +is higher than interval, handler is activated more times. Also interval +to next invocation is calculated to keep frequency. Simple scheduling +is performed at handler--handler is activated just once and then all +other timers are checked before it is activated again. You should also +define an multihandler--handler that is activated just once and +receives argument how many intervals has left. + + There is two special groups--`asyncgroup'. Timers in this group are +activated asynchronously like from interrupt. It is not recommended to +use it, since it brings many problems and usually isn't required. Also +it does not work at many platforms. `Syncgroup' is the default group. +Program is expected to process is quite often. In case you don't need +to use more groups, you should use this one. + + Time in timerlib is bit strange, since it does not flow continuously +but jumps. It is updated every time you call `tl_updatetime'. I used +this way in order to minimize context switches but later I found this +scheme very useful, since you should lookup timer, do something and +then reset it and don't wory about time spend between lookup and reset +since it is 0 in case you did not called tl_updatetime. This helps to +keep frequency of timers exact w/o any errors caused by such +situations. At the other hand you need to call tl_updatetime at least +once in your main loop. + + Maybe you don't know why to create more groups, but I found it quite +useful. For example an autopilot in XaoS has such special group--I +need to call it approx. every 1/20 of second but just at one place in +program. Invoking of autopilot when calculation is active should +produce incorrect results, so I have special group for autopilot and +process just at one place where I am sure it is safe. + + Timers should be also emulated. You should stop them and then +control flow of time for given timer. This should be quite useful for +example when you want precalculate animation at given framerate. + + To control group of timers, you might create "emulators". It is just +another time controlled by you. It is useful in cases you want to +emulate fixed framerate (for animation rendering) or such. + +Time functions +============== + + - Function: void tl_update_time (void) + Update time used by timerlib. This must be called at least once in + main loop otherwise time will not flow. See above. + + - Function: void tl_sleep (int TIME) + Sleep given time. Similar to usleep at POSIX. + +Group functions +=============== + + - Function: tl_group* tl_create_group (void) + Allocate and initialize group header. Returns NULL when malloc + fails. + + - Function: void tl_free_group (tl_group *GROUP) + Free memory storage used by group structure + + - Function: int tl_process_group (tl_group *GROUP, int *ACTIVATED) + Process timers in group and activates their handlers. Returns time + until next invocation. Main loop should sleep returned time then. + An ACTIVATED parameter sould be `NULL'. If it is non `NULL', + variable is set to number of activated handlers. + +Timer functions +=============== + + - Function: tl_timer* tl_create_timer (void) + Create timer structure. + + - Function: void tl_free_timer (tl_timer *TIMER) + Free memory storage used by timer structure + + - Function: void tl_reset_timer (tl_timer *TIMER); + Reset timer to current time. (time of last actication of + `tl_update_time') + + - Function: int tl_lookup_timer (tl_timer *TIMER); + Return time since last call of tl_reset_timer or last activation + of handler. + + - Function: void tl_set_interval (tl_timer *TIMER, int INTERVAL); + + - Function: void tl_set_handler (tl_timer *TIMER, void (*HANDLER) + (void *),void *userdata); + + - Function: void tl_set_multihandler (tl_timer *TIMER, void (*HANDLER) + (void *,int),void *userdata); + Handler, multihandler and interval control functions + + - Function: void tl_add_timer (tl_group *GROUP, tl_timer *TIMER) + Add timer to given group. Timer should be added into just one + group. + + - Function: void tl_stop_timer (tl_timer *TIMER) + + - Function: void tl_resume_timer (tl_timer *TIMER) + Stop and resume timer. + + - Function: void tl_slowdown_timer (tl_timer *TIMER,int TIME) + Time in timer is moved back for given time. + +Emulator functions +================== + + - Function: struct timeemulator *tl_create_emulator (void); + This function creates new emulator--you need to create one first + before emulating. + + - Function: void tl_free_emulator (struct timeemulator *T); + Destroy emulator's data + + - Function: void tl_elpased (struct timeemulator *T, int ELPASED); + Move emulated time. + + - Function: void tl_emulate_timer (struct timer *T, struct + timeemulator *E); + Set timer to the emulated mode. Since now all time is controled by + emulator E. All other behavior of timer keeps unchanged. + + - Function: void tl_unemulate_timer (struct timer *T); + Disable emulated mode for the timer. + +Example main loop +================= + + while(1) + { + time=tl_process_group(syncgroup,activated); /*Call game control functions*/ + update_keys(); + if(activated) /*something changed*/ + display(); + else tl_sleep(time); + } + + +File: xaosdev.info, Node: registry, Next: index, Prev: timerlib, Up: Top + +XaoS function registry +********************** + + XaoS has an ui helper library, which provides functionality provided +by user interface. All it's useful functions are registered into +central registry. This registry is used to generate menus and dialogs +as well as command line options or scripting language. So it is very +significant think in XaoS design. + + Not only those who want hack XaoS ui-helper layer needs to know +this, but also authors of drivers should use this to add new driver +depended functions into XaoS's menu. Also external user interface is +based at this. Main idea behind external user interfaces (currently +one for TCL/Tk and Gtk is under development) is following: XaoS +transfers it's registry to interface (using simple description +language). User interface starts XaoS in it's window and builds menus +and dialogs based at this registry. Then once user select some +function, it creates an command for scripting language and sends it back +to XaoS' engine. + + So knowledge of this part is essential for many developers. Please +take care for this part. + + The implementation of registry is in file `xmenu.c', header is +`xmenu.h'. Mainly for historical reasons it speaks about menus and +dialogs. (It was designed for the GUI at the beginning) I am keeping +this terminology, since it is quite clean and easy to understand +instead of talking in some cryptic abstract term. + +Function description +==================== + + To add function into database, you need write it's description into +menuitem structure. It has following prototype: + + typedef struct menuitem + { + char *menuname; + char *key; + char *name; + char *shortname; + int type; + int flags; + void (*function) (); + int iparam; + void *pparam; + int (*control) (struct uih_context *); + menudialog *(*dialog) (struct uih_context *); + } + menuitem; + + - Variable: menuname + Name of menu (or category) function belongs in. The root of all + categories is called `"root"'. XaoS alternativly uses an + `"animroot"' when animation replay is active. If you are adding an + function, it is better to add it into some subcategory like as + `"ui"' (it will be placed into UI menu then) or create an new + category for your functions if needed. It will appear as submenu + in main menu in the UI. + + - Variable: key + Ascii code of hotkey to activate this function. Use `NULL' if none. + + - Variable: name + Longer name of functions used in the menu entry, or `xaos --help' + listing + + - Variable: shortname + One-word name of function used in command language and references + to function. + + - Variable: type + type of function--this is not return type. Type should be one of + following constants: + `MENU_SUBMENU' + An submenu. This is not real function, but name for submenu. + You might fill the KEY, NAME, SHORTNAME functions. An name + of this new submenu is placed in the field PPARAM. + + `MENU_NOPARAM' + An normal function without any parameters. When actived, + function FUNCTION with just an pointer to `uih_context' + will be called. + + `MENU_INT' + This should be used to simplify entering of more similar + functions (handled by just one universal function in the c + code). This function is handled in same way as + `MENU_NOPARAM', but also in one integer parameters taken + from `iparam' is passed. + + `MENU_STRING' + Similar to `MENU_INT' but uses string instead of integer. + + `MENU_DIALOG' + If you function needs some paramters, use dialog structure to + describe them. In scripting language your function will + have parameters then, in user interface dialog will be + displayed. PPARAM must then point to array of dialog + entries. Witting them will be described later. If your + function has just one parameter described in dialog + structure, it will be called in normal c way--if you want + string parameter, one pointer pointing to string (in + addition to `uih_context') will be passed to the functions. + + In case of multiple parameters are requested, it is + impossible to call function in c way without special + wrapper for each such case. So it will receive pointer to + array of `dialogparam' unions, wich contains one entry for + each parameter. `dialogparam' is declared as follows: + typedef union + { + char *dstring; + int dint; + number_t number; + number_t dcoord[2]; + xio_path dpath; + void *dummy; + } + dialogparam; + + `MENU_CDIALOG' + In some cases, it is useful to add some context specific + default values to the dialog structure. In this case you + might use this type instead. In this case function DIALOG + is called first, and it is expected to return pointer to + correct dialog structure. Dialog structure must lie in + static storage (since it is not freed) and always must have + the same fields, just differ in the default values. + Also this function must work correctly even in the case + pointer to `uih_context' is `NULL', since it is often + called in the initialization stages (parameter parsing + etc.) + + - Variable: flags + Flags are used to set additional information about function: + `MENUFLAG_CHECKBOX' + Some features act like check-box--i.e. by one calling of + function they are enabled, second call disables this. In menu + it is useful to add an check-box for this function indicating + whether feature is on or off. + + And thats exactly what this flag does :). You need also + define the function CONTROL wich return's `1' when enabled + and `0' when disabled. In order to let external GUI's work + correctly you need also call `uih_updatemenus("name")' every + time state of this function changes. + + In the scripting language this adds an first parameter, wich + if `#t' or `#f'. Engine then calls function just when it is + necessary. For `#t' dialog is requested, with `#f' function + is called just as `NOPARAM'. I.e. dialog is displayed just + when enabling feature. + + `MENUFLAG_DIALOGATDISABLE' + In checkbox display dialog when this feature is disabled + instead when enabled. + + `MENUFLAG_RADIO' + Other features act like radio-button. Control function in + this case receives same parameter as defined for `MENU_INT' + or `MENU_STRING' types and is expected to return `1' when + enabled. You also need to call `uih_updatemenus' when + changed. No special parameter is added in the scripting + language. + + `MENUFLAG_INTERRUPT' + Interrupt current calculation when this function called (it + is used by functions with causes recalculation of screen) + + `MENUFLAG_INCALC' + By default XaoS queues functions and calls later when they + are activated in caluclation. This flag disables this feature. + + `MENUFLAG_ATSTARTUP' + By default XaoS queues functions and calls later when they + are activated as command line parameters (in time engine is + not fully initialized yet). This flag disables this feature. + + `MENUFLAG_NOMENU' + Function will not be visible in the menu + + `MENUFLAG_NOPLAY' + Function will not be available as command in scripts + + `MENUFLAG_NOOPTION' + Function will not be available as command line option + +Initializing menuitem structure as static variable +================================================== + + In most case menuitems should be wrote as static variables. Because +contents of this structure should change in future, please use one of +macros defined in `xmenu.h'. They provides cleaner and easier to extend +way to define this entries. + + For example to define `MENU_NOPARAM' function use following macro: + + - Function: MENUNOP (MENUNAME, KEY, NAME, SHORTNAME, FLAGS, FUNCTION) + Similar macros exist for the other types too. They ends for `CB' or +`RB' for check-boxed or radio-boxes functions. See `menu.c' for large +example of definitions. They should look like this: + + static menuitem menuitems[] = /*XaoS menu specifications */ + { + SUBMENU ("", NULL, "Root menu", "root"), + SUBMENU ("", NULL, "Replay only commands", "plc"), + MENUNOP ("comm", NULL, "print menus specifications of all menus", + "print_menus", MENUFLAG_NOMENU|MENUFLAG_NOPLAY|MENUFLAG_ATSTARTUP, + uih_printallmenus), + ... + +Dialog description +================== + + Dialog description is similar to menuitem. It is array of following +structures: + typedef struct dialog + { + char *question; + int type; + int defint; + char *defstr; + number_t deffloat; + number_t deffloat2; + } + menudialog; + It is terminated by QUESTION pointer set to `NULL'. + + The QUESTION contains string ui should display when is asking for +this field. + + TYPE should be one of following values: `DIALOG_INT', +`DIALOG_FLOAT', `DIALOG_STRING', `DIALOG_KEYSTRING' (the difference +between string and keystring is, that in scripting language string is +passed as `"hello"', but keystring is passed as scheme keyword as +`'hello'), `DIALOG_IFILE' (input file), `DIALOG_OFILE', `DIALOG_CHOICE' +(choice between different keystrings), `DIALOG_ONOFF' (boolean +parameter), `DIALOG_COORD' (two floats--complex number) + + Set to corresponding DEF* field for default value. In case of files +use string in the format `"[PREFIX]*[EXTENSION]"'. For type +`DIALOG_CHOICE' set DEFSTR to pointer to array of strings terminated by +`NULL' entry. + + To write dialog structures again use macros defined in `xmenu.h' +like: + DIALOGSTR(question,default) + The definition should look like: + + static menudialog uih_viewdialog[] = + { + DIALOGCOORD ("center:", 0, 0), + DIALOGFLOAT ("Radius:", 1), + DIALOGFLOAT ("Angle:", 0), + {NULL} + }; + +Modifying registry +================== + + - Function: void menu_add (menuitem *ITEM, int N); + Add array of N items to the database. + + - Function: void menu_delete (menuitem *ITEMS, int N); + Remove array of N items from database. + +Querying registry +================= + + - Function: menuitem* menu_findkey (char *KEY, char *ROOT); + Find item for given key. ROOT is menu where to start (submenus are + searched recursively) + + - Function: menuitem* menu_findcommand (char *NAME); + Find item for given short name + + - Function: char* menu_fullname (char *MENU); + Long name for the short name of menu + + - Function: menuitem* menu_item (char *MENU, int N); + Nth entry of the MENU. Return `NULL' if no more entries available. + + - Function: int menu_enabled (menuitem *ITEM, struct uih_context *C); + Check whether given item is activated (for check-boxed and + radio-boxed functions) + + - Function: int menu_havedialog (menuitem *ITEM, struct uih_context + *C); + Does this function have dialog? + + - Function: menu_getdialog (CONTEXT, M) + Macro returns pointer to dialog structure. (function must have it, + otherwise garbage is returned). + + - Function: int menu_available (menuitem *ITEM, char *ROOT); + Check whether item is available as one of entries of ROOT (or it's + submenus) + + +File: xaosdev.info, Node: index, Prev: registry, Up: Top + +Index of functions, variables, types and constants +************************************************** + +* Menu: + +* alloc_buffers: driver. +* ANIMATION: filters. +* C256 <1>: filters. +* C256: driver. +* CHANGED: filters. +* createfilter: filters. +* display: driver. +* ethreads: xthreads. +* filter: filters. +* filteraction: filters. +* FIXEDCOLOR <1>: filters. +* FIXEDCOLOR: driver. +* flip_buffer: driver. +* flush: driver. +* free_buffers: driver. +* FULLSCREEN: driver. +* getinstance: filters. +* getsize: driver. +* GRAYSCALE <1>: filters. +* GRAYSCALE: driver. +* image <1>: filters. +* image: design. +* INEXACT: filters. +* inherimage: filters. +* inhermisc: filters. +* init: driver. +* initdata: filters. +* MASK1BPP: filters. +* MAXCONDS: xthreads. +* MAXSEMAPHORS: xthreads. +* menu_add: registry. +* menu_available: registry. +* MENU_CDIALOG: registry. +* menu_delete: registry. +* MENU_DIALOG: registry. +* menu_enabled: registry. +* menu_findcommand: registry. +* menu_findkey: registry. +* menu_fullname: registry. +* menu_getdialog: registry. +* menu_havedialog: registry. +* MENU_INT: registry. +* menu_item: registry. +* MENU_NOPARAM: registry. +* MENU_STRING: registry. +* MENU_SUBMENU: registry. +* menudialog: registry. +* MENUFLAG_ATSTARTUP: registry. +* MENUFLAG_CHECKBOX: registry. +* MENUFLAG_DIALOGATDISABLE: registry. +* MENUFLAG_INCALC: registry. +* MENUFLAG_INTERRUPT: registry. +* MENUFLAG_NOMENU: registry. +* MENUFLAG_NOOPTION: registry. +* MENUFLAG_NOPLAY: registry. +* MENUFLAG_RADIO: registry. +* menuitem: registry. +* MENUNOP: registry. +* mousetype: driver. +* nthreads: xthreads. +* P_FLOAT: driver. +* P_NUMBER: driver. +* P_STRING: driver. +* P_SWITCH: driver. +* palette: design. +* params: driver. +* PIXELSIZE: driver. +* print: driver. +* processevents: driver. +* RANDOM_PALETTE_SIZE: driver. +* requirements: filters. +* RESIZE_COMMAND: driver. +* RESOLUTION: driver. +* SCREENSIZE: driver. +* set_color: driver. +* set_range: driver. +* timeemulator: timerlib. +* tl_add_timer: timerlib. +* tl_create_group: timerlib. +* tl_create_timer: timerlib. +* tl_elpased: timerlib. +* tl_emulate_timer: timerlib. +* tl_free_emulator: timerlib. +* tl_free_group: timerlib. +* tl_free_timer: timerlib. +* tl_lookup_timer: timerlib. +* tl_process_group: timerlib. +* tl_reset_timer: timerlib. +* tl_resume_timer: timerlib. +* tl_set_handler: timerlib. +* tl_set_interval: timerlib. +* tl_set_multihandler: timerlib. +* tl_sleep: timerlib. +* tl_slowdown_timer: timerlib. +* tl_stop_timer: timerlib. +* tl_unemulate_timer: timerlib. +* tl_update_time: timerlib. +* TRUECOLOR <1>: filters. +* TRUECOLOR: driver. +* TRUECOLOR24 <1>: filters. +* TRUECOLOR24: driver. +* TRUECOLOR32 <1>: filters. +* TRUECOLOR32: driver. +* UI_C256: driver. +* ui_driver: driver. +* UI_FIXEDCOLOR: driver. +* UI_GRAYSCALE: driver. +* UI_TRUECOLOR: driver. +* UI_TRUECOLOR24: driver. +* UI_TRUECOLOR32: driver. +* uninit: driver. +* UPDATE_AFTER_RESIZE: driver. +* xshl_line: eui. +* xth_bgjob: xthreads. +* xth_function: xthreads. +* xth_init: xthreads. +* xth_lock: xthreads. +* xth_nthread: xthreads. +* xth_sleep: xthreads. +* xth_sync: xthreads. +* xth_uninit: xthreads. +* xth_unlock: xthreads. +* xth_wakeall: xthreads. +* xth_wakeup: xthreads. + + + +Tag Table: +Node: Top501 +Node: design1475 +Node: driver9067 +Node: gui-driver25868 +Node: eui32613 +Node: ui-helper43320 +Node: xthreads47876 +Node: filters52923 +Node: algorithm69506 +Node: timerlib89511 +Node: registry99566 +Node: index111446 + +End Tag Table |