From 1030dc837b10a03a02a85d5504cbeec168ce49e2 Mon Sep 17 00:00:00 2001 From: Bernie Innocenti Date: Mon, 03 May 2010 21:53:47 +0000 Subject: Import XaoS r489 (trunk after version 3.5) --- (limited to 'doc') diff --git a/doc/Makefile.in b/doc/Makefile.in new file mode 100644 index 0000000..b5114d2 --- /dev/null +++ b/doc/Makefile.in @@ -0,0 +1,36 @@ +all: doc + +doc: xaos.info dvi ../AUTHORS + +xaos.texinfo: xaos.geninfo ../help/xaos.hlp + ./mktexi + +xaos.info: xaos.texinfo + makeinfo --no-split xaos.texinfo --force + +xaosdev.info: xaosdev.texinfo + makeinfo --no-split xaosdev.texinfo --force + +xaos.dvi: xaos.texinfo + tex xaos.texinfo + texindex xaos.?? + tex xaos.texinfo + +xaosdev.dvi: xaosdev.texinfo + tex xaosdev.texinfo + texindex xaosdev.?? + tex xaosdev.texinfo + +dvi: xaos.dvi xaosdev.dvi + rm -f xaos.aux xaos.cp xaos.fn xaos.ky xaos.log xaos.pg xaos.toc \ + xaos.tp xaos.vr xaosdev.aux xaosdev.cp xaosdev.cps xaosdev.fn \ + xaosdev.fns xaosdev.ilg xaosdev.ind xaosdev.ky xaosdev.kys \ + xaosdev.log xaosdev.pg xaosdev.pgs xaosdev.toc xaosdev.tp \ + xaosdev.tps xaosdev.vr xaosdev.vrs xaos.cps xaos.fns xaos.kys \ + xaos.pgs xaos.tps xaos.vrs + +../AUTHORS: xaos.info + ./mkauthors > ../AUTHORS + +clean: + rm -f xaos.info xaos.texinfo xaos.dvi xaosdev.dvi # ../AUTHORS diff --git a/doc/XaoS.lsm b/doc/XaoS.lsm new file mode 100644 index 0000000..488f6d1 --- /dev/null +++ b/doc/XaoS.lsm @@ -0,0 +1,27 @@ +Begin3 +Title: XaoS - a fast portable real-time interactive fractal zoomer/morpher +Version: 3.4 +Entered-date: Sep 28 2008 + +Description: XaoS is a fast portable real-time interactive fractal zoomer. + It displays the Mandelbrot set (among other escape + time fractals) and allows you to zoom smoothly into the fractal. + Various coloring modes are provided for both the points inside + and outside the selected set. In addition, switching between + Julia and Mandelbrot fractal types is provided. The first + version was a poorly written Mandelbrot viewer by Thomas later + modified by Jan to support high frame-rate zooming. Other + additions were later made including autopilot (for those of + you without driver licenses), palette changing, PNG saving, + and fractal inversion. +Keywords: X11 fractal realtime zoom mandelbrot newton + julia autopilot demo +Author: jh@ucw.cz (Jan Hubicka) + thomas@tivoli.com (Thomas Marsh) +Maintained-by: kovzol@particio.com (Zoltan Kovacs) +Primary-site: xaos.sf.net +Platform: GNU/Linux or any UNIX with X11 and ANSI C compiler, + Microsoft Windows (95, 98, XP), Mac OS X +Copying-policy: GNU GENERAL PUBLIC LICENSE + All rights reserved by the author +End diff --git a/doc/mkauthors b/doc/mkauthors new file mode 100755 index 0000000..3ed729a --- /dev/null +++ b/doc/mkauthors @@ -0,0 +1,13 @@ +#!/bin/sh +echo "AUTHORS +------- + +This file is autogenerated from help/xaos.hlp. +If you add a new feature to XaoS or fix a bug, +please edit help/xaos.hlp and run \"cd doc; make\". + +This list is ordered alphabetically." + +cat -v xaos.info | sed "1,/C Credits/ d;/C.0.1/,\$ d" | \ + sed s/*//g | sed s/"(alphabetically)"/""/ | + sed s/Note// | sed s/"lists::."/""/ | sed s/"\^_"// diff --git a/doc/mktexi b/doc/mktexi new file mode 100755 index 0000000..86a66b6 --- /dev/null +++ b/doc/mktexi @@ -0,0 +1,5 @@ +#!/bin/sh +set -e +echo "Generating xaos.texinfo..." +awk '/##.*##/ {system("sh ../help/conv "$3" "$4" <../help/xaos.hlp ");}; + /.*/ {print $0}' xaos.texinfo diff --git a/doc/texi2rest.py b/doc/texi2rest.py new file mode 100755 index 0000000..58fd5cd --- /dev/null +++ b/doc/texi2rest.py @@ -0,0 +1,593 @@ +#!/usr/bin/python +""" +NAME +==== + +texi2rest - Convert texinfo xml represenation to reStructuredText + +SYNOPSIS +======== + +texi2rest *xmlfile* > *restfile* + +DESCRIPTION +=========== + +``texi2rest`` is based on ``xhtml2rest`` by Antonios Christofides. He +included the following disclaimer for his program, and it applies +equally to mine: far from being a decent and complete program, this is +only something to begin with, which hopefully processes the given UTF-8 +texinfo xml file and produces reStructuredText "source code" in the +standard output. + +Before processing the texinfo file, you must convert it to xml using +the makeinfo command: + + makeinfo --xml *texifile* + + texi2rest *xmlfile* > *restfile* + +LIMITATIONS +=========== + +I am writing this specifically to convert the XaoS project's +documentation. I do not plan to implement full conversion of every +texinfo directive--only the ones used in the documentation I am trying +to convert. Hopefully other interested parties will contribute further +improvements. + + +META +==== + +``texi2rest`` was hacked together by J.B. Langston, +jb-langston@austin.rr.com, based on ``xhtml2rest`` by +Antonios Christofides, anthony@itia.ntua.gr. + +Revision: $Revision: 3753 $ + +The code and this text is hereby placed in the public domain. +""" + +import xml.dom.minidom +import re +import sys +import textwrap +import math +import UserList +import warnings +import codecs + +############################################################################### +# Configuration: these values change the behavior of the conversion + +# Texinfo commands that generate emphasis markup (i.e., *text*) +EMPHASIS_COMMANDS = ('emph', 'i', 'slanted', 'var') + +# Texinfo commands that generate strong markup (i.e., **text**) +STRONG_COMMANDS = ('strong', 'b') + +# Texinfo commands that generate literal markup (i.e.,``text``) +LITERAL_COMMANDS = ('code', 'verb' 'tt') + +# Texinfo commands that map to reST roles of the same name (i.e., :role:`text`) +VERBATIM_COMMANDS = ('dfn', 'file', 'command', 'option', 'kbd', 'samp', 'math') + +# Texinfo commands that map to differnet reStructuredText roles (i.e., :role:`text`) +MAPPED_COMMANDS = { + 'env': 'envvar', + 'key': 'kbd', + 'cite': 'title' +} + +# Texinfo commands that do not generate any markup, but preserve nested text +IGNORED_COMMANDS = ('url', 'sc', 'r', 'sansserif', 'titlefont', 'dmn', 'logo', 'punct') + +# Texinfo commands that are deleted from output, including nested text +DELETED_COMMANDS = () + +# Map of Texinfo section commands to section underline/overline characters +# Single character indicates underline only; double characters indicates overline+underline +SECTION_COMMANDS = { + # level 1 + 'top': '**', + 'chapter': '**', + 'unnumbered': '**', + 'appendix': '**', + # level 2 + 'section': '=', + 'unnumberedsec': '=', + 'appendixsec': '=', + # level 3 + 'subsection': '-', + 'unnumberedsubsec': '-', + 'appendixsubsec': '-', + # level 4 + 'subsubsection': '^', + 'unnumberedsubsubsec': '^', + 'appendixsubsubsec': '^', +} + + +############################################################################### + +############################################################################### +# Global variables. I know. I'm terribly sorry. Please get rid of them. + +# 'unindent' is used by list items. A li list item is always indented, but its +# first line is "unindented" and contains the number or bullet. However, it was +# difficult for the li node to tell its #text contents (which may be deeply +# nested) to use that. So it just places the number or bullet, which must be 4 +# characters, like " 1. ", in "unindent". The first text to be rendered uses +# the unindent and then sets it to empty again. + +unindent = '' +hyperlinks = {} # text-target pairs found in "a href" elements +############################################################################### + +class Ditem: + """A document item; usually a node, but can be a block of text + resulting from processing adjacent inline items. If it is a node, + it is usually the BlockDitem subclass; if it is text, it is + normally a plain Ditem.""" + def __init__(self, text): + self.text = text # Contained text (empty for BlockDitem) + self.type = '' # tag for block node, empty for inline + self.indentlevel = 0 # 0 - unindented; 1 - indented; etc. + def __repr__(self): + return self.__class__.__name__+'("""'+self.text+'""")' + def propagate_indents(self): + "Propagates indent level recursively to children" + pass + def maxwidth(self): + "Width it will occupy if allowed to render on infinite width" + self.remove_white_space() + return len(self.text) + 4*self.indentlevel + def minwidth(self): + "Width it will occupy if wrapped as much as possible" + wordlens = [len(x) for x in self.text.split()] + if wordlens: return max(wordlens) + 4*self.indentlevel + else: return 0 + def format(self, width): + """Returns contents formatted so as not to exceed specified + width, if possible""" + global unindent + if(self.type=='pre'): raise Exception, "What are we doing here?" + self.remove_white_space() + # Quick hack to fix a problem. Do we begin with '* '? + while len(self.text)>=2 and self.text[1]==' ' and self.text[0] in '*-': + # It may be mistaken for a bullet list. Strip it. + self.text = self.text[2:] + if width < self.minwidth(): width = self.minwidth() + # The textwrap module has the nasty habit of breaking at hyphens. So + # we'll do a nasty hack: find a character that does not exist in the + # text, replace all hyphens with that character, ok, you get the point. + hyphensurrogate = '' + for c in '!@#$%^&*~': + if self.text.find(c)<0: + hyphensurrogate = c + break + if not hyphensurrogate: raise Exception, "Houston we have a problem" + text = self.text.replace('-', hyphensurrogate) + wrapper = textwrap.TextWrapper( + initial_indent=((4*self.indentlevel)-len(unindent))*' '+unindent, + subsequent_indent=4*self.indentlevel*' ', + width=width, break_long_words = False) + unindent = '' + text = wrapper.fill(text) + text = text.replace(hyphensurrogate, '-') + return text + def empty(self): + "Returns true if contains nothing" + return not self.text + def remove_white_space(self): + "Removes extra white space" + self.text = re.sub('\s+', ' ', self.text).strip() + def canmerge(self): + "Tells whether it's possible to merge this Ditem with adjacent ones" + return True + def merge(self, aditem): + """If possible, merges aditem, which should be an adjacent Ditem that + comes after this one.""" + if not self.canmerge() or not aditem.canmerge(): return False + if len(self.text)>0 and self.text[-1] == '_' and len(aditem.text)>0 \ + and aditem.text[0] not in """ \n\t:.,!=/|;"'?<>[]{}()""": + # Leave space after link if not followed by punctuation + self.text = self.text + ' ' + aditem.text + else: + self.text = self.text + aditem.text + return True + +class BlockDitem(Ditem): + "A Ditem which contains other Ditems" + def __init__(self, type): + Ditem.__init__(self, '') + self.type = type + self.children = [] # Contained Ditems + def __repr__(self): + return self.__class__.__name__+'("'+self.type+'"); children = '+repr(self.children) + def maxwidth(self): + childmaxwidths = [x.maxwidth() for x in self.children] + return childmaxwidths and max(childmaxwidths) or 0 + def minwidth(self): + childminwidths = [x.minwidth() for x in self.children] + return childminwidths and max(childminwidths) or 0 + def propagate_indents(self): + for x in self.children: + x.indentlevel = self.indentlevel + x.propagate_indents() + def format(self, width): + if width < self.minwidth(): width = self.minwidth() + results = [x.format(width) for x in self.children] + results = [x for x in results if x] + return "\n\n".join(results) + def empty(self): + return not (self.children) + def canmerge(self): + return False + +class PreDitem(Ditem): + "A Ditem representing a literal block" + def maxwidth(self): + return max([len(x) for x in self.text.split('\n')]) + def minwidth(self): + return self.maxwidth() # Literal block; width's given + def remove_white_space(self): + pass + def format(self, width): + result = '::\n\n' + for x in self.text.split('\n'): + result = result + ' ' + x + '\n' + result = result + '..\n\n' + return result + def canmerge(self): + return False + +class HeadingDitem(BlockDitem): + "A Ditem representing an h1, h2, ..., h9" + def __init__(self, type): + BlockDitem.__init__(self, type) + def minwidth(self): + return self.maxwidth() # Headings don't wrap + def format(self, width): + assert(len(self.children)==1) + text = self.children[0].format(32767) + uldict = { + 'chapter': '**', 'section': '=', 'subsection': '-', 'subsubsection': '^', + 'unnumbered': '**', 'unnumberedsec': '=', 'unnumberedsubsec': '-', 'unnumberedsubsubsec': '^', + 'appendix': '**', 'appendixsec': '=', 'appendixsubsec': '-', 'appendixsubsubsec': '^' + } + underliner = uldict[self.type] + if len(underliner) == 2: + return len(text)*underliner[0] + '\n' + text + '\n' + len(text)*underliner[0] + else: + return text + '\n' + len(text)*underliner[0] + +class BlockQuoteDitem(BlockDitem): + "A Ditem representing a blockquote" + def __init__(self, type): + BlockDitem.__init__(self, type) + def propagate_indents(self): + self.indentlevel = self.indentlevel + 1 + BlockDitem.propagate_indents(self) + +class ListDitem(BlockDitem): + "A Ditem representing an ol, ul, or dl" + def __init__(self, type): + BlockDitem.__init__(self, type) + def format(self, width): + # First pass the list type and order to the children + order = 1 + for x in self.children: + if isinstance(x, ListItemDitem): + x.listtype = self.type + x.order = order + order = order+1 + # And then process normally + return BlockDitem.format(self, width) + +class ListItemDitem(BlockDitem): + "A Ditem representing a li, dt, or dd" + def __init__(self, type): + BlockDitem.__init__(self, type) + self.listtype = None + self.order = 0 + def minwidth(self): + if self.type == 'definitionterm': return self.maxwidth() # Don't wrap dt + else: return BlockDitem.minwidth(self) + def propagate_indents(self): + if self.type in ('item', 'definitionitem'): + self.indentlevel = self.indentlevel + 1 + BlockDitem.propagate_indents(self) + def format(self, width): + global unindent + if self.type == 'item' and self.listtype == 'enumerate': + unindent = ('%d. ' % (self.order)).ljust(4) + elif self.type == 'item' and self.listtype == 'itemize': + unindent = '* ' + return BlockDitem.format(self, width) + +class RenderedColumn: + "Width information about a column being rendered" + def __init__(self, minwidth, maxwidth): + self.minwidth = minwidth + self.maxwidth = maxwidth + self.curwidth = maxwidth + self.fixedwidth = 0 + def logwidth(self): + if self.maxwidth==0: return 0 + else: return math.log(self.maxwidth) + def update(self, minwidth, maxwidth): + "Replaces minwidth/maxwidth if greater" + self.minwidth = minwidth>self.minwidth and minwidth or self.minwidth + self.maxwidth = maxwidth>self.maxwidth and maxwidth or self.maxwidth + self.curwidth = self.maxwidth + +class RenderedColumns(UserList.UserList): + "A list of RenderedColumn" + def __init__(self, alist): + self.data = alist + def totalWidth(self): + "Returns total table width" + return reduce(lambda x,y: x+y, [z.curwidth for z in self.data]) \ + + len(self.data) + 1 + def sumLogWidth(self): + "Returns sum of logwidth for nonfixed columns" + return reduce(lambda x,y: x+y, + [x.logwidth()*(1-x.fixedwidth) for x in self.data]) + def distributeWidthDifference(self, width): + "Step 4 of w3m table rendering algorithm" + # Note: The use of math.ceil below is because I'd rather have a + # suboptimal width (a few characters less than requested width) rather + # than go find what to do with rounding. + w = self.totalWidth() - width + assert(w>0) + repeat_distribution = 1 + while repeat_distribution: + repeat_distribution = 0 + for x in self.data: + if x.fixedwidth: continue + if x.curwidth - math.ceil(w*x.logwidth()/self.sumLogWidth()) < \ + x.minwidth: + x.curwidth = x.minwidth + x.fixedwidth = 1 + w = self.totalWidth() - width + repeat_distribution=1 + break + # Now that the we finished finding which columns need to be fixed to + # their minimum width, perform the distribution once again, without + # checking, and actually change remaining column widths + for x in self.data: + if x.fixedwidth: continue + x.curwidth = x.curwidth - math.ceil(w*x.logwidth()/self.sumLogWidth()) + +def tablehrule(colwidths, rule='-'): + "Returns a horizontal table separator for given column widths" + result = '+' + for x in colwidths: + result = result + rule * x + '+' + return result + +class TableDitem(BlockDitem): + def __init__(self, type): + BlockDitem.__init__(self, type) + def format(self, width): + # Uses table rendering algorithm of w3m + # (http://www.w3m.org/story.html), but ignoring width attribute + # Step 1 + columns = RenderedColumns([RenderedColumn(x.minwidth(), + max(x.maxwidth(), 1) # A column can't be smaller than 1 character + ) for x in self.children[0].children]) + for x in self.children: + for i in range(len(columns)): + if (len(x.children)<=i): continue # Skip empty columns + columns[i].update(x.children[i].minwidth(), x.children[i].maxwidth()) + # Step 2 (width attribute) ignored + # Step 3 (already done - list was created with maxwidth) + # Step 4 + if columns.totalWidth() > width: columns.distributeWidthDifference(width) + # OK, column widths are now calculated + colwidths = [int(x.curwidth) for x in columns] + result = tablehrule(colwidths) + '\n' + usedheadbodysep = False + for tr in self.children: + result = result + tr.format(colwidths) + rule = '-' + if not usedheadbodysep and tr.children[0].type == 'th' \ + and tr!=self.children[-1]: + rule = '=' + usedheadbodysep = True + result = result + tablehrule(colwidths, rule) + '\n' + return result + +class TrDitem(BlockDitem): + def __init__(self, type): + BlockDitem.__init__(self, type) + def maxwidth(self): + return reduce(lambda x,y: x+y, + [x.maxwidth() for x in self.children]) + len(self.children) + 1 + def minwidth(self): + return reduce(lambda x,y: x+y, + [x.minwidth() for x in self.children]) + len(self.children) + 1 + def format(self, colwidths): + columns = [] # List of lists of lines + maxlinecount = 0 # Num of lines in vertically largest column + for i in range(len(colwidths)): + if len(self.children)<=i: lines = [ '' ] + else: lines = self.children[i].format(colwidths[i]).split('\n') + lines = [x + ' ' * (colwidths[i]-len(x)) for x in lines] # Pad to col len + maxlinecount = max(maxlinecount, len(lines)) + columns.append(lines) + # Pad vertically + for i in range(len(columns)): + for j in range(maxlinecount-len(columns[i])): + columns[i].append(' ' * colwidths[i]) + result = '' + # Add vertical separators + for i in range(maxlinecount): + result = result + '|' + for j in range(len(columns)): + result = result + columns[j][i] + '|' + result = result + '\n' + return result + +def handleNodeList(nodelist): + "Processes given nodes; merges them if possible; returns ditem list" + ditems = [] + curditem = Ditem('') + for node in nodelist: + aditem = handleNode(node) + if curditem.merge(aditem): continue + ditems.append(curditem) + curditem = aditem + if not curditem.empty(): ditems.append(curditem) + return ditems + +def handleNode(node): + if node.nodeType == node.TEXT_NODE: + return handleText(node) + elif node.nodeName in EMPHASIS_COMMANDS: + return handleEmphasis(node) + elif node.nodeName in STRONG_COMMANDS: + return handleStrong(code) + elif node.nodeName in LITERAL_COMMANDS: + return handleLiteral(node) + elif node.nodeName in VERBATIM_COMMANDS: + return handleVerbatimCommand(node) + elif node.nodeName in MAPPED_COMMANDS: + return handleMappedCommand(node) + elif node.nodeName in IGNORED_COMMANDS: + return handleIgnoredCommand(node) + elif node.nodeName in DELETED_COMMANDS: + return handleDeletedCommand(node) + elif node.hasChildNodes(): + contents = handleNodeList(node.childNodes) + if len(contents) == 1: return contents[0] + if len(contents) == 0: return Ditem('') + result = BlockDitem(node.nodeName) + result.children = contents + return result + return Ditem('') + +def processChildren(node): + if node.hasChildNodes(): + return handleNodeList(node.childNodes) + else: + return () + +def mergeChildren(node): + contents = processChildren(node) + if len(contents)>1: raise Exception('Unexpected block elements') + if contents: return contents[0] + else: return Ditem('') + +def handleEmphasis(node): + result = mergeChildren(node) + result.type = node.nodeName + if result.text: + result.text = '*' + result.text + '*' + return result + +def handleStrong(node): + result = mergeChildren(node) + result.type = node.nodeName + if result.text: + result.text = '**' + result.text + '**' + return result + +def handleLiteral(node): + result = mergeChildren(node) + result.type = node.nodeName + if result.text: + result.text = '``' + result.text + '``' + return result + +def handleVerbatimCommand(node): + result = mergeChildren(node) + result.type = node.nodeName + if result.text: + result.text = ':' + node.nodeName + ':`' + result.text + '`' + return result + +def handleMappedCommand(node): + result = mergeChildren(node) + result.type = node.nodeName + if result.text: + result.text = ':' + MAPPED_COMMANDS[node.nodeName] + ':`' + result.text + '`' + return result + +def handleIgnoredCommand(node): + result = mergeChildren(node) + result.type = node.nodeName + return result + +def handleDeletedCommand(node): + result = '' + result.type = node.nodeName + return result + +def handleText(node): + return Ditem(node.data) + +def handleAnchor(node): + result = mergeChildren(node) + result.type = node.nodeName + result.text = result.text.strip() + if result.text == '': return result + target = node.getAttribute('href').strip() + result.text = re.sub('\s+', ' ', result.text) + result.text = ':ref:`'+result.text+' <'+target+'>`' + return result + +def handleHeading(node): + contents = mergeChildren(node) + if contents.empty(): return contents + result = HeadingDitem(node.parentNode.nodeName) + result.children.append(contents) + return result + +def handleGenericBlock(node): + result = BlockDitem(node.nodeName) + result.children = processChildren(node) + return result + +def handleBlockQuote(node): + result = BlockQuoteDitem(node.nodeName) + result.children = processChildren(node) + return result + +def handleList(node): + result = ListDitem(node.nodeName) + result.children = processChildren(node) + return result + +def handleListItem(node): + result = ListItemDitem(node.nodeName) + result.children = processChildren(node) + return result + +def handleTable(node): + result = TableDitem(node.nodeName) + # Ignore table contents that are not tr + result.children = [x + for x in processChildren(node) if x.type=='tr'] + return result + +def handleTr(node): + result = TrDitem(node.nodeName) + # Ignore tr contents that are not th or td + result.children = [x + for x in processChildren(node) if x.type in ('th', 'td')] + return result + +def handlePre(node): + return PreDitem(mergeChildren(node).text) + +dom1 = xml.dom.minidom.parse(sys.argv[1]) +ditem = handleNode(dom1.getElementsByTagName("texinfo")[0]) +ditem.propagate_indents() +(utf8_encode, utf8_decode, utf8_reader, utf8_writer) = codecs.lookup('utf-8') +outf = utf8_writer(sys.stdout) +outf.write(ditem.format(79) + '\n') +for h in hyperlinks.keys(): + outf.write('\n.. _`' + h + '`:\n ' + hyperlinks[h] + '\n') diff --git a/doc/xaos.6 b/doc/xaos.6 new file mode 100644 index 0000000..59fea28 --- /dev/null +++ b/doc/xaos.6 @@ -0,0 +1,14 @@ +.TH XaoS 6 "22 Feb 2006" "XaoS" "Demos" + +.SH NAME +xaos - Fast interactive real-time fractal zoomer/morpher + +.SH DETAILS +This manual page is obsolete and no longer maintained. +Please read the full documentation running +XaoS. You can start it typing 'xaos'. (Press 'h' 3 +times to get into the help system.) +.P +In addition, +.B xaos --help +should give a detailed list about the command line options. diff --git a/doc/xaos.geninfo b/doc/xaos.geninfo new file mode 100644 index 0000000..42d8d52 --- /dev/null +++ b/doc/xaos.geninfo @@ -0,0 +1,283 @@ +\input texinfo @c -*-texinfo-*- + +@c The original files are xaos.geninfo and xaos.hlp. xaos.texinfo is +@c automatically generated. So make all changes in the orignal files please. +@c To regenerate xaos.texinfo, please run "mktexinfo". + +@c Use A4 paper - If you don't like that, remove the following 3 lines. +@iftex +@afourpaper +@end iftex + +@setfilename xaos.info +@settitle An fast realtime interactive fractal zoomer --- user's manual +@dircategory Graphics +@direntry +* XaoS: (xaos). A fast real-time interactive fractal zoomer +@end direntry + + +@ifinfo +@copyright{} 1996-2008 Jan Hubicka and the XaoS Development Team + +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. + +@end ifinfo + +@c %**end of header + +@set VERSION 3.4 +@set DATE April 17, 2008 + +@titlepage + +@title{XaoS @value{VERSION}} +@subtitle{A fast real-time interactive fractal zoomer --- User's manual} + +@author{Jan Hubi@v cka} +@tex +Dukelsk\'ych bojovn\'\i ku 1944 +@end tex +@* +390 03 T@'abor @* +Czech Republic + +Email: @code{jh@@ucw.cz} + +@value{DATE} + +@page +@vskip 0pt plus 1filll +@vskip 0pt plus 1filll + +@copyright{} 1996-2008 @tex Jan Hubi\v cka and the XaoS Development Team +@end tex + +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. + +@end titlepage + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node Top, Overview, (dir), (dir) + +@ifinfo +@top XaoS @value{VERSION} +@flushright 1.0 +A real-time interactive fractal zoomer +User's manual +@value{DATE} +@end flushright + +This manual contains user documentation about XaoS --- a fast real-time fractal +zoomer. XaoS uses a development model, so sources are freely available. The +file @code{xaosdev.texinfo} in the source documentation contains a hacker's +manual (design overview, algorithm description etc.). +@end ifinfo + +@menu +* Overview:: What does this software do then? +* tutorial:: XaoS tutorial +* controls:: Basic controls +* video:: How to encode video files +* format:: XaoS's file format description +* writehelp:: How to write XaoS help files +* xshl:: XaoS simple hypertext language +* drivers:: Driver specific documentation +* menus:: Functions, menu items and command line parameters +* about:: Credits +* support:: Getting Support +* index:: Function index +@end menu + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node Overview, tutorial, Top, Top + +@chapter Overview +@menu +* Why?:: Why yet another fractal generator? +* What?:: What does this software do then? +@end menu + +@node Why?, What?, Overview, Overview +@section Why yet another fractal generator? + + +We decided to make XaoS, because all fractal browsers we know of take a +long time to calculate each image. You may browse nice images +generated by them but real impressions of fractals --- the self +similarity and infinite zooming into the nice parts of fractals --- +can be seen only in animations. There are many programs available that +make nice animations, but they take a long time to calculate and lots +of space on disk. Most such animations are quite ugly because their +authors can't see them without many hours of calculations. + +A natural question is: is it possible to generate such animations in +real-time? The answer was negative for many years, since the Mandelbrot set is +very computationally expensive. Things are changing. Today's computers +are fast enough to calculate approx. 10.000 of pixels per frame, +which is enough +for a very low resolution animation (100x100). Several programs doing that +are available. But 100x100 animation still looks quite ugly. To make +animation nice you need at least 320x200 pixels. And that is 6 times more! +One possibility is to wait until computers will be fast enough, but +it will take many years, and then 320x200 animations will be obsolete +and everyone will want 1024x768 resolution instead or more. + +We found a special algorithm that saves up to 99.98% of calculations during +zooming by reusing pixels already calculated in previous frames. There were +some programs doing similiar tricks before but we don't know about any able +to do zooming interactively with a speed similar to XaoS. Many other tricks +were later implemented XaoS to achieve yet higher framerates. Now XaoS does +up to 120 frames per second on a 120Mhz pentium in a fullscreen 320x200 +animation, and calculates an average of 160 (0.24%) pixels per frame. This makes +XaoS fast enough to achieve its primary goal, realtime animation, but there +are still many areas that could improve, since more complex fractals, +higher resolutions, or slower computers still bring many problems. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node What?, , Why?, Overview +@comment node-name, next, previous, up +@section What does this software do then? + +XaoS is a realtime interactive fractal zoomer. This means that it lets you +zoom smoothly into any place in the fractal you choose without the many hours +of calculation required by most other fractal generators. It now has many +other features too, like 13 different fractal types, autopilot, special coloring +modes, support for various bit depths (8bpp, truecolor, hicolor and realcolor), +random palette generation, color cycling etc... + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node tutorial, controls, Overview, Top +@c ## chapter tutorial ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node controls, video, tutorial ,Top + +@c ## chapter controls ## + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node video, format, controls ,Top + +@c ## chapter video ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node format, writehelp,video ,Top +@c ## chapter format ## +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node writehelp, xshl,format ,Top +@c ## chapter writehelp ## +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node xshl, drivers,writehelp ,Top +@c ## section xshl ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node drivers, menus,xshl ,Top +@c ## chapter drivers ## + +@menu +* aa:: AA-lib --- high quality ascii art driver +* BeOS:: BeOS drivers +* DGA:: DGA driver +* dos:: DOS driver +* dX-fullscreen:: directX fullscreen driver +* dX-window:: directX windowed driver +* ggi:: GGI driver +* plan9:: plan9 driver +* SVGAlib:: SVGAlib driver +* win32:: Win32 driver +* X11:: X11 driver +@end menu + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node aa, BeOS , ,drivers +@c ## section aa ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node BeOS, DGA , aa ,drivers +@c ## section BeOS ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node DGA, dos , BeOS ,drivers +@c ## section DGA ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node dos, dX-fullscreen , DGA ,drivers +@c ## section dos ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node dX-fullscreen, dX-window , dos ,drivers +@c ## section dX-fullscreen ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node dX-window, ggi , dX-fullscreen ,drivers +@c ## section DX-window ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node ggi, plan9, dX-window ,drivers +@c ## section ggi ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node plan9, SVGAlib, ggi ,drivers +@c ## section plan9 ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node SVGAlib, win32, plan9 ,drivers +@c ## section SVGAlib ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node win32, X11, SVGAlib ,drivers +@c ## section win32 ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node X11, , win32 ,drivers +@c ## section X11 ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node menus, about, drivers,Top + +@c ## menus controls ## +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +@comment node-name, next, previous, up +@node about, support,menus ,Top +@c ## appendix about ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node support, index ,about ,Top +@c ## appendix support ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node index, ,support ,Top +@unnumbered Index of functions + +@printindex fn + + +@contents +@bye diff --git a/doc/xaos.info b/doc/xaos.info new file mode 100644 index 0000000..5676dc2 --- /dev/null +++ b/doc/xaos.info @@ -0,0 +1,3818 @@ +This is xaos.info, produced by makeinfo version 4.11 from xaos.texinfo. + +INFO-DIR-SECTION Graphics +START-INFO-DIR-ENTRY +* XaoS: (xaos). A fast real-time interactive fractal zoomer +END-INFO-DIR-ENTRY + + (C) 1996-2008 Jan Hubicka and the XaoS Development Team + + 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: xaos.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) + +XaoS 3.4 +******** + + A real-time interactive fractal zoomer + User's manual + April 17, 2008 + + This manual contains user documentation about XaoS -- a fast +real-time fractal zoomer. XaoS uses a development model, so sources are +freely available. The file `xaosdev.texinfo' in the source +documentation contains a hacker's manual (design overview, algorithm +description etc.). + +* Menu: + +* Overview:: What does this software do then? +* tutorial:: XaoS tutorial +* controls:: Basic controls +* video:: How to encode video files +* format:: XaoS's file format description +* writehelp:: How to write XaoS help files +* xshl:: XaoS simple hypertext language +* drivers:: Driver specific documentation +* menus:: Functions, menu items and command line parameters +* about:: Credits +* support:: Getting Support +* index:: Function index + + +File: xaos.info, Node: Overview, Next: tutorial, Prev: Top, Up: Top + +1 Overview +********** + +* Menu: + +* Why?:: Why yet another fractal generator? +* What?:: What does this software do then? + + +File: xaos.info, Node: Why?, Next: What?, Prev: Overview, Up: Overview + +1.1 Why yet another fractal generator? +====================================== + +We decided to make XaoS, because all fractal browsers we know of take a +long time to calculate each image. You may browse nice images generated +by them but real impressions of fractals -- the self similarity and +infinite zooming into the nice parts of fractals -- can be seen only in +animations. There are many programs available that make nice +animations, but they take a long time to calculate and lots of space on +disk. Most such animations are quite ugly because their authors can't +see them without many hours of calculations. + + A natural question is: is it possible to generate such animations in +real-time? The answer was negative for many years, since the Mandelbrot +set is very computationally expensive. Things are changing. Today's +computers are fast enough to calculate approx. 10.000 of pixels per +frame, which is enough for a very low resolution animation (100x100). +Several programs doing that are available. But 100x100 animation still +looks quite ugly. To make animation nice you need at least 320x200 +pixels. And that is 6 times more! One possibility is to wait until +computers will be fast enough, but it will take many years, and then +320x200 animations will be obsolete and everyone will want 1024x768 +resolution instead or more. + + We found a special algorithm that saves up to 99.98% of calculations +during zooming by reusing pixels already calculated in previous frames. +There were some programs doing similiar tricks before but we don't know +about any able to do zooming interactively with a speed similar to +XaoS. Many other tricks were later implemented XaoS to achieve yet +higher framerates. Now XaoS does up to 120 frames per second on a +120Mhz pentium in a fullscreen 320x200 animation, and calculates an +average of 160 (0.24%) pixels per frame. This makes XaoS fast enough to +achieve its primary goal, realtime animation, but there are still many +areas that could improve, since more complex fractals, higher +resolutions, or slower computers still bring many problems. + + +File: xaos.info, Node: What?, Prev: Why?, Up: Overview + +1.2 What does this software do then? +==================================== + +XaoS is a realtime interactive fractal zoomer. This means that it lets +you zoom smoothly into any place in the fractal you choose without the +many hours of calculation required by most other fractal generators. It +now has many other features too, like 13 different fractal types, +autopilot, special coloring modes, support for various bit depths +(8bpp, truecolor, hicolor and realcolor), random palette generation, +color cycling etc... + + +File: xaos.info, Node: tutorial, Next: controls, Prev: Overview, Up: Top + +2 XaoS tutorial +*************** + +This is a brief introduction to the basic XaoS features. + +2.1 How to zoom +=============== + +The main advantage of XaoS is that after a few seconds' delay to +calculate the first image, you may choose any point with the mouse and +press the _left_ button. The image will start to zoom smoothly into +the point you choose. You may move the mouse and zoom smoothly into +interesting areas. By pressing the _middle button_ (or _left+right_ +buttons) you may also _move the image_ using "drag & drop" if you +missed an interesting place. _Unzooming_ is also possible by using the +_right button_, but it is much slower because optimizations are not so +effective as for zooming. + + In case you think that the default _speed_ is boring (it is quite +slow, to make XaoS smooth on a slow computer) you may change it by +pressing _arrow up/down_. But faster zooming is more expensive, so if +the speed is too high you will see little but funny colorful blinking +rectangles. + +2.2 Autopilot +============= + +To make XaoS yet more impressive we made a special autopilot that +automatically drives into interesting boundaries of the set. So you can +press `A', play your favorite music, drink coffee and relax. I never +tried this but it should be really relaxing! Many pictures in the XaoS +gallery were discovered using the autopilot. + + The autopilot also has some additional features. It turns back when +the zoomed picture stops being interesting, and is able to spot when +it's zoomed into a really boring part (or has reached the limit of +floating point numbers) and restart zooming from the top. + +2.3 Various fractal formulae +============================ + +XaoS also supports formulae other than the Mandelbrot set. You may +change _formula_ using the _number keys_ or _SHIFT+letters_. + + On keys `1' to `5' are _Mandelbrot sets of various power_. The +"normal" Mandelbrot set is on key `1'. + + On key `6' is a fractal called _Newton_. It is Newton's famous +formula for finding roots. + + On key `7' is the _fourth ordered Newton_ fractal. + + On key `8' is a fractal called _Barnsley_. + + On key `9' is _Barnsley's second_ fractal. + + On key `0' is _Barnsley's third_ fractal. + + With keys `SHIFT-A' you can display a fractal called _octo_. It is a +fractal that Thomas discovered in fractint. + + With keys `SHIFT-B' you can display a fractal called _Phoenix_. It +is a very nice and quite famous fractal. + + With keys `SHIFT-C' you can display a fractal called _Magnet_. This +fractal has quite a complex formula so it is a bit slow. + + With keys `SHIFT-D' you can display the _Magnet2_ fractal. + + The rest of the built-in fractals are accessible through an other +menu, but you can still use the hotkeys. + + On `SHIFT-E' is a fractal called _Triceratops_ found by Arpad. + + On `SHIFT-F' is a fractal called _Catseye_ found by Arpad. This is +more interesting if you change the bailout value. + + On `SHIFT-G' is a fractal called _Mandelbar_. It was in Gnofract4d, +and they found it at: http://mathworld.wolfram.com/MandelbarSet.html + + On `SHIFT-H' is the _Lambda_ fractal. + + On `SHIFT-I' and `SHIFT-J' are the _Manowar_ and _Spider_ fractals, +they were found by users of fractint. (Scott Taylor or Lee Skinner) It +was on http://spanky.triumf.ca/www/fractint/ taylor_skinner_type.html + + The next 3 fractals are famous classic fractals. + + On `SHIFT-K' is the _Sierpinski_ Gasket. You can change its shape +by selecting another Julia seed. (This is for technical reasons.) + + On `SHIFT-L' is the _Sierpinski Carpet._ It's shape can also be +changed by selecting another Julia seed. + + On `SHIFT-M' is the _Koch Snowflake._ + +2.4 Out-coloring modes +====================== + +To make fractals yet more interesting, more coloring modes for points +outside the set are provided. "Classical coloring mode" uses the number +of iterations that the orbit required to escape to (nearly) infinity. +You can change this mode from the _Fractal menu_ or by pressing key `C' +To see more about coloring modes, try the tutorial on Incoloring modes +from the XaoS features overview. + + Those cryptic names for coloring modes are mathematical formulae, +where _iter_ means number of iterations, _real_ means real coordinate +of last orbit, and _imag_ means imaginary coordinate of last orbit. + +2.5 In-coloring mode +==================== + +In-coloring mode is similar to out-coloring, except that it changes how +things inside the set are displayed. This can also be changed from the +_fractal menu_ or by pressing `F'. + + You might also want to see the tutorial on Out-coloring modes from +the XaoS features overview. + +2.6 Planes +========== + +All fractals displayed by XaoS are functions with a complex parameter. +It can be displayed in the normal complex plane, where x is the real +part of the number, and y is the imaginary part; but it can also be +displayed in a number of other planes. You can select the plane to use +from the _Fractal menu_, or by pressing `I'. + + Like the coloring modes, planes have cryptic names. You guessed it, +they're mathematical formulae. Here `mu' means coordinates in the normal +complex plane. If you have coordinates in `1/mu' plane, and you need +coordinates in the a complex plane (to calculate the Mandelbrot set) you +simply use the coordinates as mu. Lambda is another plane that can be +converted to mu using a similar formula. + +*mu* + normal mode. + +*1/mu* + Inversion: infinity goes to 0 and 0 goes to infinity. + +*1/(mu+0.25)* + Similar to inversion, but moves the center outside of the + Mandelbrot set so that it looks parabolic. + +*lambda* + Lambda plane. + +*1/lambda* + Inversion of lambda plane. + +*1/lambda-1* + Inversion with moved center. + +*1/(mu-1.40115)* + A very interesting mode for the Mandelbrot set. It makes small + things big, so you can browse the set's details easily. + +2.7 Mandelbrot/Julia switching +============================== + +Most of the fractals displayed by XaoS (currently all of them) have two +forms: Mandelbrot and Julia. Every point in a Mandelbrot set has its +own Julia set. To see more about this correspondence, try the tutorial +on Julia set from the Introduction to fractals. + + In the Mandelbrot mode, you can get a corresponding Julia by moving +the mouse to an interesting point and pressing `M'. To get back press +`M' again. Some fractals (Barnsley and phoenix) are already in their +Julia versions, because the Mandelbrot ones are boring. But by pressing +`M' in such fractal you should get the Mandelbrot version, and by +choosing another point as the base point and pressing `M' again you +should get a completely different fractal. The most interesting points +for Julia sets are at the boundaries of the Mandelbrot set. Most of the +Julias inside or outside the set are boring. + +2.8 Fast Julia preview mode +=========================== + +Fast Julia mode is a quick way to find a point to use as a base for the +Julia set.. Just press `J' and a small Julia set will be displayed in +the top left corner. Then move the mouse around with button 1 +depressed, and the Julia for the point the mouse is over will be +automatically generated. + +2.9 Palette +=========== + +If you think that the default XaoS colors are ugly or you are just +bored by them you can change it by pressing `P'. XaoS will +automatically generate random palettes. Many of them look ugly, so +press `P' again to get another one until you find one you like. + +2.10 Filters +============ + +Many interesting effects are done by post-calculation filters. *Note +filter::. XaoS has filters that do everything from embossing, through +motion-blurring, right through to turning the fractal into a +stereogram. To enable them use the `filter menu' or press `E'. + +2.11 Palette cycling +==================== + +This is a very old trick that makes the Mandelbrot set a little +flashier. You may enable or disable it using `Y'. In the truecolor +modes you need to enable the palette emulator filter first. This is done +via the `E' key, or from the filter menu. + +2.12 Changing number of iterations +================================== + +To calculate fractals perfectly, you need an infinite number of +iterations. XaoS does just the first few of them, so after lots of +zooming you may get into a place that looks quite boring, and the +boundaries of the set are rounded, without any interesting details. +This can be changed by changing the number of iterations: + + Press and hold `arrow right' and wait until iterations are high +enough. This may slow down calculation much. To reduce number of +iterations press `arrow left'. + +2.13 Changing resolution +======================== + +XaoS usually starts in a low resolution (320x200 or thereabouts) to make +calculations faster. If you have a fast computer or you need to save +bigger `.gif' images, you may change the resolution. This can be done +by pressing `=' in the full screen drivers, or simply by resizing the +XaoS window. + +2.14 Changing driver +==================== + +XaoS usually has more than one driver available. You may change it on +the fly in case you want a different one. For example, XaoS started in +X11 can be switched at runtime to use the AA driver. This can be done +from the UI menu. + + This action is bit dangerous, because XaoS can crash during +initialization if there is some problem with initialization; XaoS tries +to initialize a new driver, and if it fails it attempts to return back +to the original. Sometimes this is impossible, and all XaoS can do is +terminate.. + +2.15 Other features +=================== + +XaoS has many other features, but they don't fit into this tutorial. +Most of them are available from the menu, so you can experiment with +them. You might also want to see the _animated tutorials_ from the +_help menu_, to have an idea what XaoS can do. + + +File: xaos.info, Node: controls, Next: video, Prev: tutorial, Up: Top + +3 Basic controls +**************** + +By default the mouse buttons work in the following way: + +*left* + zoom in + +*right* + zoom out + +*middle* + move fractal in a drag-and-drop fashion + + _Note:_ Since most Macs only have one button mice, these controls +are emulated on Mac OS X using modifier keys. See the help section on +Mac OS X for details. + + This behavior can change. If you enable rotation, the first button +is used for rotating fractals. Also, in fast Julia mode, the first +button is used to change the seed. + + If you don't have a middle button, press both buttons to enable +emulation. + + After few minutes of zooming you will probably exceed the precision +and the fractals will get boring. If you are getting strange big +rectangles on the screen, you probably reached the numeric limit: there +is no way to avoid this except un-zoom back and choose a different +area. It doesn't hurt so much, since you have zoomed approximately 64 +051 194 700 380 384 times, so there are quite a lot of areas to +explore. Algorithms with unlimited precision exist, but they are still +too slow for real-time zooming. + + The other possibility is that you have reached the iteration limit. +The fractal is calculated approximately, and in this case you need to +increase number of iterations used for approximation (and decrease the +speed in the process). This is done from the menu or using the arrow +keys _Left_ and _Right_. + + An _Up_ and _Down_ keys should be used to change zooming speed. Note +that higher speed costs more and image will be blocky. + + This behavior can also change. With palette cycling enabled, _Left_ +and _Right_ keys change cycling speed; in continuous rotation they +change rotation speed. + + All other functions are available from the menu, which (in the +default configuration) are displayed when you move the mouse to the top +of the screen/window. It is useful to learn the shortcut keys, which are +shown in gray next to the menu items they trigger. + + +File: xaos.info, Node: video, Next: format, Prev: controls, Up: Top + +4 How to encode video files from XaoS +************************************* + +To create a video, make and `xaf' file first (the easiest way to do +this is to use the _record_ function in the file menu). Then you need +to render the animation. XaoS can output sequences of ordinary `PNG' +images, that can later be used by a video encoder. + +4.1 Generating image sequences for video +======================================== + +To generate an image sequence, choose _Render Animation_ from the _Misc_ +menu. You can also use the following command on the command line: + + xaos -render [filename] -size 352x240 -antialiasing + -renderframerate 24 -basename [basename] + + _File to render_ (`[filename]') is the name of the `xaf' file, +_Basename_ (`[basename]') is the name used as the base filename for +rendered images. This should also include the path where you want to +save the images. XaoS adds a four digit sequence number and `.png' +extension to this name automatically. + + You might also want to change the resolution. Make sure that the +resolution you choose is supported by the video codec you wish to use. + + The framerate can also be altered. Make sure you choose a framerate +that is supported by the video codec you wish to use. + + _Antialiasing_ (`-antialiasing') is used to produce anti-aliased +images. It takes a much longer time and much more memory to calculate +them, but resulting images are better for video compression and they +result in a much smaller video file. (the same is true of _JPEG +images_) + + On the other hand, the other XaoS rendering option _Always +Recalculate_ (`-alwaysrecalc') (which disables XaoS's zooming +optimizations) is _not recommended_. If that's used, the sequence of +animation then contains quite a lot of extra information, which +increases size of video file, but because of the codec's lossy +compression it is hard to see any difference, so it's not worth it. + +4.2 Rendered files +================== + +Once you start it, XaoS will generate thousands of frames. They take +quite a long time to calculate and save, and consume plenty of disk +space. (e.g. to render part 1 of the tutorial you need about 60MB and +half an hour of time). + + All images are named `[basename]framenum.png'. For example +`intro0001.png' is the first frame of the animation intro. If +consecutive frames are the same, XaoS doesn't save them, so some frames +may be missing. If your encoder can't handle that, you will need to +write a simple script which will fill in the gaps by means of `mv' or +symbolic linking. + + A list of all filenames is saved into the file `[basename].par', +where each line is the name of one frame. The names repeat here if +necessary, so you can use this file to supply filenames to the encoder. + +4.3 Encoding videos +=================== + +Once XaoS has generated the png files for each frame of the animation, +you can use a third-party video encoder to convert the sequence of +images into a video file. We currently recommend the following +encoders, which support a wide variety of video codecs and file formats: +*ffmpeg* + Available from: `http://ffmpeg.mplayerhq.hu/' Instructions: + `http://ffmpeg.mplayerhq.hu/faq.html#SEC12' + +*mencoder* + Part of mplayer, available from: http://www.mplayerhq.hu/ + Instructions: + `http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-enc-images.html' + These are both command line tools. If you prefer a graphical tool, +you may prefer Quicktime Pro from Apple +(http://www.apple.com/quicktime/pro/). However, this software costs +approximately US$30, and the authors of XaoS have no experience with +it. Although QuickTime may be easier to use, the two free encoders +above are just as capable once you learn how to use them. + + Note: we used to recommend Berkeley parallel MPEG encoder to encode +the generated png files into MPEG videos. We have kept the instructions +mainly for historic purposes. + + +File: xaos.info, Node: format, Next: writehelp, Prev: video, Up: Top + +5 XaoS's file format +******************** + +This section describes the format used by XaoS for animations, +configuration files and saved positions. All these files have a common +format, designed to be easily readable, to allow manual editing of +files and easy conversion by other programs. + + I also taken care to make it easily extensible for future versions +of XaoS so I hope there will not be many incompatibilities between +various XaoS versions. + + The format is a simple set of commands executed sequentially. XaoS +does not provide any variables/cycles as usual scripting languages do, +but future extension to full-blown Scheme should be easy since the +format uses Scheme-like syntax. The syntax of every command is: + + `(command_name '_[param1] [param2]_`)' + + where parameters are optional and separated by whitespace (an +arbitrary number of spaces, tabs and newlines). The parameters can have +the following types: + +*integer* + number w/o decimal point (`123') + +*float* + floating point number in decimal notation with optional exponent + (`1.23E2') + +*keyword* + text started by quote `''. It is used to pass various string + constants like formula name (`'mandel') Quote is required for + scheme compatibility + +*string* + Text inside double quotes. The only parameter that should contain + whitespace + +*boolean* + `#t' for true or `#f' for false + + There is a complete description of all XaoS functions (with some +examples) and an index of functions in the XaoS registry. *Note +menus::. You may particularly want to read about the animation +functions. *Note animf::. Also, the following functions are significant: + +*load* + This function loads and interprets a file. It works similarly to + `#include' in C. + +*initstate* + Available in version 3.0 and above, this function resets XaoS's + state to default values. This command should be at the beginning + of each animation file, since otherwise some stuff previously + enabled by user could cause unexpected effects. State is not reset + by default before playing animations since it would make it + impossible to write macros. Current versions don't really need + macros, but in future versions, when the Scheme programming + language will be available, this should be a much more interesting + subject. + +*usleep* + This function waits for a selected amount of time(in usec) before + processing the next command. The screen is recalculated and + displayed at the beginning of the sleep if necessary. The + remaining time is spent by waiting, calculating if necessary, or + performing any animation you entered via animation commands. + +*wait* + Waits until the animation or image rendering is complete. Do not + call this function when zoom, or continuous rotation is active + otherwise deadlock happens. It is a good idea to call it + immediately before text subtitles are displayed, since it looks + ugly when they are displayed over a blocky unfinished fractal. + Because the degree of blockiness at a given instant is a function + of your machine speed, it may look nice for you but ugly for + others with slower machines. Also you should call this after an + animation is performed, before the switch to another fractal + happens; since the switch involves calculation, the screen is + stopped for a while and an unfinished fractal there looks ugly. + You should also call it, when you want to do something as soon as + possible. + + Example: + + ;configure everything for the first frame + (inistate) + (palette 1 1163254293 0) ;custom palette + (cycling #t) ;enable cycling + (cyclingspeed 7) + (maxiter 276) ;higher number of iterations + (range 3) ;default range for solid guessing + (usleep 1000000) ;second frame starts here + (moveview -1.8101154154614007889 -8.2687205907162041209E-05) + ;just move the image + (usleep 1000000) ;third frame + (morphview -1.8101154154614007889 -8.2687205907162041209E-05 + 6.277210971069452361E-10 6.2772109785334669875E-10) + ;10 seconds of zooming into selected + rectangle + (usleep 100000000) + + The best way to learn XaoS command language is probably to read +position files and modify them. For example, to create zooming +animation from the original file: + + (initstate) + (defaultpalette 0) + (formula 'mandel) + (view -1.64128273713 -5.50393226816E-05 9.69332308848E-08 + 9.69332308834E-08) + + Just change the `view' command to `morphview', and add `usleep': + + (initstate) + (defaultpalette 0) + (formula 'mandel) + (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 + 9.69332308834E-08) + (usleep 10000000) + + The following code produces Julia morphing in the real axis: + + (initstate) + (fastjulia #t) + (juliaseed -2 0) + (morphjulia 2 0) + (usleep 2000000) + + And following is the "rotozooming" animation: + + (initstate) + (fastrotate #t) + (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 + 9.69332308834E-08) + (morphangle 300) + (usleep 10000000) + (wait) + (fastrotate #f) + +6 XaoS gallery +************** + +I plan to make a gallery of animations and position files on the XaoS +home-page, so please send any nice animations and images you created +using XaoS to the mailing list or upload them to our website. + + +File: xaos.info, Node: writehelp, Next: xshl, Prev: format, Up: Top + +7 How to write XaoS help files +****************************** + +XaoS help is stored in the file `help/xaos.hlp'. It is divided into +parts, each part being started by a _keyword_. In the help file +keywords are written as `%keyword' + + If you are writing documentation about some command in the XaoS +function registry, use the same keyword as the name of the command in +order to make context sensitive help work. + + +File: xaos.info, Node: xshl, Next: drivers, Prev: writehelp, Up: Top + +7.1 xshl +======== + +_Xshl_ stands for _XaoS simple hypertext language_. It uses similar +tags to HTML. It is simpler and more restrictive in order to make it +easy to parse using various scripts. In C code you can use the library +present in `src/util/xshl.c' to parse it. + + The following tags are supported: + +*head* + make headings (should be at the beginning of the page, at least) + +*emph* + emphasize + +*tt* + Use non proportional font + +*br* + Break line + +*p* + Next paragraph + +*dl* + Definition list + +*dt* + Definition tag (should be used only inside a definition list) + +*dd* + Definition description (should be used only inside a definition + list) + +*center* + align to center + +*right* + align to right + +*red* + change color to red (should not be used in help files) + +*black* + change color to black (should not be used in help files) + +*white* + change color to white (should not be used in help files) + +*a name* + link to other help page + +*tutor name* + activate tutorial + +*notex* + Ignore this in texinfo manuals + + +File: xaos.info, Node: drivers, Next: menus, Prev: xshl, Up: Top + +8 Platform-specific documentation +********************************* + +XaoS is portable and works on many different platforms. Since not all +platforms are exactly the same, there are some differences between the +behavior of XaoS on different platforms. Here is documentation about +each specific port. + +* Menu: + +* aa:: AA-lib --- high quality ascii art driver +* BeOS:: BeOS drivers +* DGA:: DGA driver +* dos:: DOS driver +* dX-fullscreen:: directX fullscreen driver +* dX-window:: directX windowed driver +* ggi:: GGI driver +* plan9:: plan9 driver +* SVGAlib:: SVGAlib driver +* win32:: Win32 driver +* X11:: X11 driver + + +File: xaos.info, Node: aa, Next: BeOS, Up: drivers + +8.1 AA-lib driver +================= + +The AA driver is currently the most advanced and portable driver for +XaoS. It is based on AAlib--a high quality ASCII-art library developed +by the AA-project. (see `http://aa-project.sf.net') + + It is a fully featured XaoS driver for text mode displays. It +supports 256 colors and the mouse where possible. + + It also has some extended features available from the UI menu: + +*Attributes* + AA-lib may use character attributes to improve image quality. By + default it uses normal, dim and bold characters where possible, + but you can also enable different attributes like reversed or bold + font characters. You may also enable usage of non ansii/reversed + characters if your device supports it. + +*Font* + AA-lib uses a bitmap image of the font to prepare the + approximation table used for ASCII art rendering. This bitmap is + expected to be same as the one used by your device. AAlib performs + detection where possible however some devices (like UNIX text + terminals or MDA) do not support this. AAlib has few font images + compiled in, so in this case you should try to use one of them to + achieve best results. + +*Inversion* + Some devices use inverse video: use this to get correct results on + such devices. + +*Dithering mode* + Dithering is an way to get more exact color in approximations, by + combining more characters; but this method can produce ugly + looking noise on certain images. Use this menu to disable or tune + it. + +*Palette options* + By default AA driver uses the XaoS palette to render images, but + it quite often looks ugly on text displays. Here you can choose a + special text palette instead. Note that with filters enabled, the + results may be rather ugly. This function is available from the + _palette menu_. + +*Save text screen* + The normal save function will generate a PNG image instead of nice + ASCII-art. To save ASCII art use this function instead. It + supports many text file formats like HTML, ANSI, more, etc... It + will also ask you for font and attributes(see above). It is + available from the _file menu_. + + The AA-lib driver also provides the full set of standard AA-lib's +command line options. You may use them to tune parameters like gamma +correction, and so on. See `xaos -help' or the AA-lib documentation +for details. + + The AA driver was written by Jan Hubicka, 1997. + + +File: xaos.info, Node: BeOS, Next: DGA, Prev: aa, Up: drivers + +8.2 BeOS support +================ + +XaoS has pretty advanced support for BeOS R4. It works on both PowerPC +and Intel platforms, supports multithreading, the clipboard, file +dragging, has native look and feel and can work as an image translator +from XaoS files to images. + + The first version of the BeOS driver was written by Jens Kilian and +later extended by Jan Hubicka. + +8.2.1 Installation +------------------ + +You can start the installation script to do everything for you. If you +want something special, read this section. + + In order for XaoS to work you need to keep the executable together +with its data files (`help', `examples', `catalogs' and the `tutorials' +directory) + + When first started, XaoS registers two new mime types called +`image/x-xaos-position' for XaoS Position Files and +`video/x-xaos-animation' for XaoS Animation Files, registers icons for +them and sets itself as default application. + +8.2.2 Available display drivers +------------------------------- + +XaoS supports following drivers: + +*BeOS* + Standard windowed driver using application server + +*DirectWindow* + Driver done using Game Kit's direct window class + +*WindowScreen* + Fullscreen driver. + + By default, XaoS starts in windowed mode and uses the application +server for output. You could change the driver to DirectWindow to use +direct access to video RAM. Note that this mode is slower in most +cases, and not supported by some videocards. + + The BeOS driver by default chooses the most similar bitmap supported +by XaoS to achieve best and fastest results. In the UI menu you can +change this default choice to another one if you wish. Also you can +ask the BeOS and DirectWindow to resize to fullscreen mode. + + XaoS also supports real fullscreen mode using the BWindowScreen API. +To switch XaoS to this driver, use the UI menu. If you want to use this +mode by default, use the `-driver WindowScreen' command line option. + + This driver differs a lot from windowed ones. It use direct access +to the video card, allowing you to change video mode. Also, the 256 +color mode can access the palette, so it is not dithered like the +windowed mode. Because BeOS can't do GUI in fullscreen mode, XaoS uses +its own toolkit. I hope you will feel confortable in it. + +8.2.3 XaoS as translator +------------------------ + +You should be able to open XaoS files in graphics applications such as +ShowImage or ArtPaing. In Preferences you can find the DataTranslations +program, that can be used to set the size, type and DPI of the +resulting image. Also antialiasing can be enabled. + + Note that _translation can take a while_. So be patient and wait for +the result. + + If the translator doesn't work, ensure that you have a link to the +XaoS executable in `/boot/beos/system/add-ons/Translators/'. + + +File: xaos.info, Node: DGA, Next: dos, Prev: BeOS, Up: drivers + +8.3 DGA driver +============== + +This is the driver for DGA (Direct Graphics Architecture) extension +used by XFree86 X servers. It is pretty new so it could be buggy. + + Bugs/limitations: + +*In 8bpp mode, XaoS has problems with the palette with certain window managers* + I don't know why this happens. Just let me know what's wrong, or + use another window manager. + +*Banked modes are not supported.* + I don't have any card to test this with, so it doesn't work in the + current version. + + DGA driver was written by Jan Hubicka, 1999. + + +File: xaos.info, Node: dos, Next: dX-fullscreen, Prev: DGA, Up: drivers + +8.4 DOS driver +============== + +This is a fully featured driver for DJGPP and allegro. It supports +many VGA modes, VESA 1.0--3.0, VBE/AF, S3 and some other cards. + + The following problems may occur: + +*Some DPMI servers may cause problems* + Some DPMI servers like the one from Novell/Dr/Open DOS are buggy. + Use clean DOS instead and XaoS will automatically start `cwsdpmi'. + Under Open Dr DOS use `dpmi off' at command line to disable it. + +*Higher resolutions don't work* + If your videocard has enough memory for the selected resolution, + you most probably have an unsupported videocard. Please use a + VESA BIOS extension on this videocard. (See the note about VESA at + the end of this section.) + +*XaoS needs a coprocessor* + I don't distribute a coprocessor library linked into XaoS because + it is too slow for a real-time zoomer. Coprocessor emulation will + not help, because xaos works in protected mode. + +*XaoS needs mouse driver to be usable* + +*XaoS works slowly in higher resolution* + This could also be caused by Allegro's slow driver or your + videocard's VESA BIOS. You could try some other VESA BIOS + extension instead. Look at the `http://www.talula.demon.co.uk' + for the FreeBE project or Scitech Display Doctor package. (See + the note about VESA at the end of this section.) + +8.4.1 VESA +---------- + +VESA is a standard for using higher resolutions in DOS. Many videocards +have VESA support in the BIOS so you don't need any additional +software, while others need support from a special program. Also some +VESA BIOS implementations are buggy or suboptimal; there are 3 +different versions, version 1.0 is many times slower than 2.0, which +has support for protected mode and linear framebuffers. So if you have +problems with higher resolutions, or some graphics modes are not +available (like 320x200 truecolor), you might try some software package +which emulates VESA. + + The most famous VESA emulating program is Scitech Display Doctor. It +has support for many videocards and is quite reliable. It's +disadvantage is that it is shareware and works for only 30 days. You +might also look on `ftp.simtel.net', where there are many VESA +emulation packages such as `s3vbe' or the new FreeBe project at +`http://www.talula.demon.co.uk' + + DOS driver was written by Jan Hubicka, 1997. + + +File: xaos.info, Node: dX-fullscreen, Next: dX-window, Prev: dos, Up: drivers + +8.5 DirectX fullscreen driver +============================= + +This is da river for Windows 9x and NT. It is new since version 3.1 and +because of some oddities of Windows API and kludges in DirectX it may +be rather unstable. Please report all bugs. In case of problems you +could use the DOS version of XaoS instead. + + This driver allows the Windows port of XaoS to run in full screen +mode. The driver supports 256, 65536 and 16777216 color modes (24bpp +and 32bpp) in all resolutions supported by DirectX. You can change +graphics mode by pressing the `=' key (or by using the UI/Resize menu). +If the selected mode is not supported, the driver will restore the +previous setting. + + Use the `-mode WIDTHxHEIGHTxDEPTH' (like `-mode 640x480x16') command +line option to change graphics mode. + + If you want to start XaoS in DirectX, use the `-driver dX-fullscreen' +option. + + See the Win32 driver documentation for some more Windows releated +information. + + DirectX driver was written by Jan Hubicka, Jan Olderdissen and Pavel +Tzekov, 1999. + + +File: xaos.info, Node: dX-window, Next: ggi, Prev: dX-fullscreen, Up: drivers + + +File: xaos.info, Node: ggi, Next: plan9, Prev: dX-window, Up: drivers + +8.6 GGI driver +============== + +GGI stands for General Graphics Interface. Part of this project is to +develop libggi, a portable graphics library, and XaoS's GGI driver uses +that. It is experimental, since the API of libggi is not stabilized +yet. There are some problems with keyboard handling--the shift key +doesn't work yet. + + Everything else might work well, but there are no guarantees. It is +alpha quality software. + + GGI driver was written by Jan Hubicka, 1998. + + +File: xaos.info, Node: plan9, Next: SVGAlib, Prev: ggi, Up: drivers + +8.7 Plan9 driver +================ + +Plan9 is a very nice small operating system by the authors of Unix at +Bell Labs. It is very incompatible with other operating systems; even +the C compiler and header files are different, but XaoS should work +well there (even on the limited free demo installation without any +POSIX compatibility stuff) + + There are a few limitations: the file selector and image saving +don't work. You can save position files and then later render them on +the other OS, or save screenshots. + + Plan9 terminals also don't provide any way to catch the arrow keys, +so you can't use them. Use the mouse to navigate in the menus. Also, +getting the screen resolution is impossible, so use `-pixelwidth' and +`-pixelheight' instead of `-screenwidth' and `-screenheight'. + + By default XaoS changes the colormap. This will collide with other +colorful programs like Mortha. You can disable this behavior using +`-nopalette' switch, but this will slow down XaoS. + + Plan9 driver was written by Jan Hubicka, 1997. + + +File: xaos.info, Node: SVGAlib, Next: win32, Prev: plan9, Up: drivers + +8.8 SVGAlib driver +================== + +This is a driver for Linux SVGAlib. I really like this driver, because +I much prefer full screen zooming instead of a small 320x320 window in +X11. It was one of the first drivers for XaoS and is fully featured. +The following problems can occur: + +*XaoS doesn't initialize graphics mode* + when started under users other than root SVGAlib requires root + privileges to directly access the hardware. When you really want + to start XaoS as a normal user, enable the suid bit (`chmod +s') + at XaoS executable. note that I take care to disable all security + holes caused by this bit so I believe it is safe. + +*Mouse doesn't work* + +*Screen is blank at higher resolutions* + Both this problems are probably caused by misconfiguration of + SVGAlib. Please configure it in `etc/vga/libvga.cong' or + `/usr/local/lib/libvga.conf' GPM can also cause problems. Try to + kill it before starting XaoS. + +*When I switch console I can't switch back* + This is another typical SVGAlib bug. Try to hold `F' key longer + than `alt'. It helps on my computer. On older SVGAlib there was a + famous "enter bug" that caused a crash after pressing enter. Try + to update to a newer release. + + SVGAlib driver was written by Jan Hubicka, 1997. + + +File: xaos.info, Node: win32, Next: X11, Prev: SVGAlib, Up: drivers + +8.9 Win32 driver +================ + +This is a driver for Windows 9x and NT. It is new since version 3.1 and +because of some oddities of Windows API it may be rather unstable. +Please report all bugs. In case of problems you could use the DOS +version of XaoS instead. + + The driver should work in all bit depths, but 16 color mode is not +natively supported by the XaoS engine. XaoS internally works in 32k +colors and the result is converted to 16 colors by Windows. Because +Windows conversion routines are slow and ugly, the result is slow and +ugly. Please configure your display to another bit depth to "solve" +this problem. + + Use `-size WIDTHxHEIGHT' command line option to change the default +window size. + + This driver also maps to native Windows look and feel. There is a +small problem with combo boxes in dialogs. They are expected to give +you a choice between a few strings. The keyboard controls (changing +choice by arrow keys) work, but mouse selection is broken. If you know +how to solve this bug, please let me know. + + XaoS is a UNIX application and has many command line options. Some +features are not available from the GUI. Because Windows applications +can't have normal output, most of the critical messages are displayed +in message boxes, but some longer messages are omitted. The most +significant omission is the help about command line options that you +can find in `doc/cmdopts.txt'. + + One thing that might be confusing is that animation rendering mode +doesn't display anything, but only renders images. Start the rendering, +and a message box will inform you that XaoS is entering the calculation +loop. Relax and wait for the message box signaling the end of the loop. + + Note that XaoS also supports the DirectX API. + + Win32 driver was written by Jan Hubicka, Jan Olderdissen and Pavel +Tzekov, 1999. + + +File: xaos.info, Node: X11, Prev: win32, Up: drivers + +8.10 X11 driver +=============== + +This was the first driver done for XaoS. It supports many visuals, +shared colormaps and MitSHM extension. + + Bugs/limitations: + +*XaoS makes some X servers too busy* + Sometimes XaoS generates images faster than X can display them. + In this case XaoS responds poorly to the mouse, and other + applications slow down too. This happens especially often on old + R4 servers. Use `-sync' to avoid this problem. Note that `-sync' + does `not' make all communication with X asynchronous; it just + adds one additional XSync call. So the slowdown is not as large + as you might expect. + +*Does not work on all visuals* + This driver supports only 8bpp pseudocolor/grayscales, 15,16,24 + and 32bpp truecolor, 1bpp and 8bpp staticolor visuals. + +*Palette rotating does not work for 8bpp pseudocolor w/o private palette* + + X11 driver was written by Jan Hubicka and Thomas Marsh, 1997. + + +File: xaos.info, Node: menus, Next: about, Prev: drivers, Up: Top + +Függelék: A Menus, functions and command line parameters +********************************************************** + +All XaoS functions are referenced by a central function registry. The +scripting language, menus, dialogs and command line options are built +from this database. This section contains information about all +functions available in this registry. + +* Menu: + +* root:: Root menu +* animroot:: Animation root menu +* plc:: Replay only commands + +* linemenu:: Line drawing functions +* animf:: Animation functions +* time:: Timing functions +* file:: File +* edit:: Edit +* fractal:: Fractal +* calc:: Calculation +* mfilter:: Filters +* ui:: UI +* misc:: Misc +* helpmenu:: Help +* xtextpos:: Horizontal text position +* ytextpos:: Vertical text position +* mformula:: Formulae +* palettemenu:: Palette + + +File: xaos.info, Node: root, Next: animroot, Up: menus + + +File: xaos.info, Node: animroot, Next: plc, Prev: root, Up: menus + +A.1 Animation root menu +======================= + +This menu is displayed at the top of the screen when animation replay +is active. + +* Menu: + +* file:: File +* stopreplay:: Stop replay +* helpmenu:: Help +* ui:: UI + + +File: xaos.info, Node: stopreplay, Up: animroot + +A.1.1 Stop replay +----------------- + +Terminate animation replay. + + _Available as_: menu item + + +File: xaos.info, Node: plc, Next: linemenu, Prev: animroot, Up: menus + +A.2 Replay only commands +======================== + +Some commands, such as timing primitives or animation functions, are +available only in animation files. + +* Menu: + +* linemenu:: Line drawing functions +* animf:: Animation functions +* time:: Timing functions +* load:: Include file + + +File: xaos.info, Node: load, Up: plc + +A.2.1 Include file +------------------ + + -- Function: load file + + This function lets you include another file in your script. It works +similarly to `#include' in C or `load' in Scheme. The file is searched +for in the same directory as the current source file. + + _Available as_: command + + +File: xaos.info, Node: linemenu, Next: animf, Prev: plc, Up: menus + +A.3 Line drawing functions +========================== + +XaoS has support for drawing lines. These functions are available only +in animations and could be used to show some parts of fractals or draw +simple diagrams. See the tutorial "Introduction to fractals" for +examples of this feature. + + Lines can be drawn in _screen_ coordinates, where 0,0 is the top +left corner and 1,1 is bottom right, _scaled_ coordinates, which are +similar, but scaled to keep 0,0--1,1 rectangular, or _Fractal_ +coordinates, to draw a line at an exact position on the screen. + + The color of the line should be specified by the `color' command. +You might draw an arbitrary number of lines and, later, morph them. +Each line is identified by a unique numeric key; the current key can be +set using `linekey'. Commands for changing lines operate on the line +with the current key. (Lines drawn in sequence have consecutive +numbers.) + + For example: + + (color 'red) + (line 'scaled 0.3 0.5 0.7 0.5) + (line 'scaled 0.3 0.5 0.7 0.5) + (line 'scaled 0.3 0.5 0.3 0.5) + (line 'scaled 0.7 0.5 0.7 0.5) + (linekey 0) + (morphline 'scaled 0.3 0.3 0.7 0.3) + (morphline 'scaled 0.3 0.7 0.7 0.7) + (morphline 'scaled 0.3 0.3 0.3 0.7) + (morphline 'scaled 0.7 0.3 0.7 0.7) + (usleep 1000000) + + Creates line morphing to rectangle. + + -- Function: line keyword complex complex + + Draw line between two points. `keyword' specifies type of +coordinates and should be one of the following: ``fractal', ``screen' +or ``scaled'. This function also increases the line key. + + _Available as_: command + + -- Function: morphline keyword complex complex + + Morph current line to given coordinates. `keyword' specifies type +of coordinates and should be one of the following: ``fractal', +``screen' or ``scaled'. The line will start moving at the next timing +command, and reach the final position before the end of it. This +function also increases the line key. + + _Available as_: command + + -- Function: morphlastline keyword complex complex + + This function has the same functionality as morphline, but it doesn't +increase the line key, and touches the line with the previous key. This +is useful when you want to move a just-drawn line--you don't need to +set linekey back. + + _Available as_: command + + -- Function: linekey integer + + Set current line key. + + _Available as_: command + + -- Function: clearline + + Clear current line. This function also increases the line key. + + _Available as_: command + + -- Function: clearlines + + Clear all displayed lines. Lines can also be cleared using the +`clearscreen' or `display' commands available from the Misc menu. *Note +misc::. + + _Available as_: command + + +File: xaos.info, Node: animf, Next: time, Prev: linemenu, Up: menus + +A.4 Animation functions +======================= + +These functions are used to animate fractal state--to zoom, unzoom and +morph various parameters. They should be used only in animation files. +Animations are usually performed for a time selected by an immediately +following timing function. *Note time::. For example: + + (view 0 0 1 1) + (morphview 0 0 2 2) + (usleep 5000000) + + Will do a 5 second long unzooming animation. + +* Menu: + +* animateview:: Animate view +* smoothmorph:: Smooth morphing +* morphview:: Morph view +* morphjulia:: Morph julia +* moveview:: Move view +* morphangle:: Morph angle +* zoom:: Zooming functions + + +File: xaos.info, Node: animateview, Next: smoothmorph, Up: animf + +A.4.1 Animate view +------------------ + + -- Function: animateview float float float float + + This function is almost identical to function `view'. *Note uiview::. +It expects that the view will be changed only slightly, so +recalculation is done with `ANIMATE' priority. This means that dynamic +resolution is used by default. + + Viewport is selected by the center and two radiuses (real and +imaginary). See `view' for more information. + + _Available as_: command + + +File: xaos.info, Node: smoothmorph, Next: morphview, Prev: animateview, Up: animf + +A.4.2 Smooth Morphing +--------------------- + + -- Function: morphview keystring starttime endtime +This function lets you smoothly start and stop morphing. Specify +starttime and stoptime as nonzero, and morphing will speed up and slow +down for that number of usecs. + + The keystring is used to select what morphing you want to control. +It is one of the following: +*'view* + control morphview + +*'angle* + control morphangle + +*'julia* + control morphjulia + +*'line* + control morphline + + +File: xaos.info, Node: morphview, Next: morphjulia, Prev: smoothmorph, Up: animf + +A.4.3 Morph view +---------------- + + -- Function: morphview float float float float +For the time selected by the next `usleep' or other timing function, +the viewpoint is smoothly morphed from the current one to that selected +by `morphview'. + + Viewport is selected by the center and two radiuses (real and +imaginary). See `view' for more information. + + This function can easily be used for creating zooming/unzooming +animations using position files. This is an example position file +generated by XaoS: + + (initstate) + (defaultpalette 0) + (formula 'mandel) + (view -1.64128273713 -5.50393226816E-05 9.69332308848E-08 + 9.69332308834E-08) + + By replacing the `view' command with `morphview' and adding `usleep' +you can create a zooming animation: + + (initstate) + (defaultpalette 0) + (formula 'mandel) + (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 + 9.69332308834E-08) + (usleep 10000000) + + _Available as_: command + + +File: xaos.info, Node: morphjulia, Next: moveview, Prev: morphview, Up: animf + +A.4.4 Morph Julia +----------------- + + -- Function: morphjulia complex +For the time selected by the next `usleep' or other timing function, +the Julia seed is smoothly interpolated from the current one to that +selected by `morphjulia'. By default this will cause recalculation of +the whole screen. To avoid this, use fast Julia mode. *Note +fastjulia::. + + A simple animation morphing Julia seed in the X axis: + + (initstate) + (fastjulia #t) + (juliaseed -2 0) + (morphjulia 2 0) + (usleep 2000000) + + _Available as_: command + + +File: xaos.info, Node: moveview, Next: morphangle, Prev: morphjulia, Up: animf + +A.4.5 Move view +--------------- + + -- Function: moveview complex +Smoothly move the image center to another position. + + _Available as_: command + + +File: xaos.info, Node: morphangle, Next: zoom, Prev: moveview, Up: animf + +A.4.6 Morph angle +----------------- + + -- Function: morphangle float +Smoothly rotate the image to another angle. By default rotation causes +recalculation of the whole screen. To avoid this you need to enable +fast rotate mode. *Note rotate::. Don't forget to disable it later, +since it slows down other animations. + + A simple "rotozooming" animation: + + (initstate) + (fastrotate #t) + (morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 + 9.69332308834E-08) + (morphangle 300) + (usleep 10000000) + (wait) + (fastrotate #f) + + _Available as_: command + + +File: xaos.info, Node: zoom, Prev: morphangle, Up: animf + +A.4.7 Zooming functions +----------------------- + +The functions for zooming/unzooming were created mainly for recording +animations. In manually created animation files, it is easier to use +`morphview'. *Note morphview::. + + -- Function: zoomcenter complex + This function sets the center to zoom in on. The center is given as +a position in fractal coordinates. + + _Available as_: command + + -- Function: zoom + Start zooming to the area specified by `zoomcenter'. + + The speed of zooming should be controlled by the function `speed' or +in a more exact way by `maxstep' and `speedup'. + + -- Function: unzoom + + Start unzooming from the area specified by `zoomcenter'. + + _Available as_: command + + -- Function: stop + Stop zooming or unzooming. + + _Available as_: command + + +File: xaos.info, Node: time, Next: file, Prev: animf, Up: menus + +A.5 Timing functions +==================== + +Timing functions are used to control the animation replay daemon. It +can wait for a given time, or wait until calculation is complete. The +animation functions are controlled by such waiting; animations that are +running while delays start keep running through the delay. + +* Menu: + +* usleep:: Usleep +* textsleep:: Wait for text +* wait:: Wait for complete image + + +File: xaos.info, Node: usleep, Next: textsleep, Up: time + +A.5.1 Usleep +------------ + + -- Function: usleep integer + + This function waits for a given amount of time (in usec) before +processing the next command. The screen is recalculated and displayed +at the beginning of usleep if necessary necessary. The remaining time +is spent in waiting or performing animation. + + _Available as_: command + + +File: xaos.info, Node: textsleep, Next: wait, Prev: usleep, Up: time + +A.5.2 Wait for text +------------------- + + -- Function: textsleep + + This function's behavior is very similar to `usleep', but the time +is calculated from the number of letters currently displayed onscreen. +If you want to wait just long enough for the user to read the subtitle, +use this function. The user can alter the replay speed as desired using +`letterspersec'. *Note letterspersec::. This value can be changed during +replay with the arrow keys. + + _Available as_: command + + +File: xaos.info, Node: wait, Prev: textsleep, Up: time + +A.5.3 Wait for complete image +----------------------------- + + -- Function: wait + + Wait until the image is complete. You should always use this +function after zooming or unzooming when dynamic resolution is in use. +This ensures that the image calculation will be complete so the user +can see the result before the animation continues. It may also be +useful in combination with filters like motion blur. *Note blur::. + + This function deadlocks if used with animation functions; don't do +that. + + _Available as_: command + + +File: xaos.info, Node: file, Next: edit, Prev: time, Up: menus + +A.6 File +======== + +* Menu: + +* loadpos:: Load +* savepos:: Save +* record:: Record +* play:: Replay +* saveimg:: Save image +* loadexample:: Load random example +* savecfg:: Save configuration +* quit:: Quit + + +File: xaos.info, Node: loadpos, Next: savepos, Up: file + +A.6.1 Load XaoS position file +----------------------------- + +Load a XaoS position file (`*.xpf'). See the format description for +more information. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: savepos, Next: record, Prev: loadpos, Up: file + +A.6.2 Save XaoS position file +----------------------------- + + -- Function: savepos file + + Save current state to a XaoS position file (`*.xpf'). This file is +human-readable, and can easily be improved by hand after saving, or +used as a base for animations. See the format description for more +information. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: record, Next: play, Prev: savepos, Up: file + +A.6.3 Record animation +---------------------- + + -- Function: record bool [ file ] + + e Toggle recording to a XaoS animation file (`*.xaf'). This file is +human-readable, and can easily be improved by hand after recording. +See the format description for more information. + + From the scripting language, `(record #t)' enables recording, and +`(record #f)' disables it. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: play, Next: saveimg, Prev: record, Up: file + +A.6.4 Replay animation +---------------------- + +Replay a XaoS animation file (`.xaf'). + + _Available as_: menu item, command line option + + +File: xaos.info, Node: saveimg, Next: loadexample, Prev: play, Up: file + +A.6.5 Save image +---------------- + + -- Function: saveimg file + + Save current state to an image file. This file is in `.png' (portable +network graphics) format, which can be read by many applications +varying from graphics programs all the way to Web browsers. + + This function needs an external library called `libpng'. If the +library wasn't available during compilation, this function is +unavailable too. Please see `INSTALL' for more information about +obtaining libpng and recompiling XaoS. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: loadexample, Next: savecfg, Prev: saveimg, Up: file + +A.6.6 Load random example +------------------------- + + -- Function: loadexample + + Choose random `.xpf' file from the `examples' directory and load it. +You might use it as the starting point for next exploration. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: savecfg, Next: quit, Prev: loadexample, Up: file + +A.6.7 Save configuration +------------------------ + + -- Function: savecfg + + Save current configuration to `~/.xaosrc' (under Unix) or `xaos.cfg' +(under DOS and Windows). XaoS automatically reloads the configuration +from this file when it starts. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: quit, Prev: savecfg, Up: file + +A.6.8 Quit +---------- + + -- Function: quit + + Quit XaoS. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: edit, Next: fractal, Prev: file, Up: menus + +A.7 Edit +======== + +A fairly ordinary Edit menu. + +* Menu: + +* undo:: Undo +* redo:: Redo +* copy:: Copy +* paste:: Paste + + +File: xaos.info, Node: undo, Next: redo, Up: edit + +A.7.1 Undo +---------- + +Undo last operation. `Last operation' is quite hard to define in XaoS +(where changes are continuous), so it might be surprising. I hope it +will do what you want. + + _Available as_: menu item + + +File: xaos.info, Node: redo, Next: copy, Prev: undo, Up: edit + +A.7.2 Redo +---------- + +Redo last undone operation. See undo. *Note undo::. + + _Available as_: menu item + + +File: xaos.info, Node: copy, Next: paste, Prev: redo, Up: edit + +A.7.3 Copy +---------- + +Copy fractal to clipboard. This is a platform-dependent operation that +may not have an analogue on your platform (e.g. there is no concept of +a clipboard under aalib). + + _Available as_: menu item + + +File: xaos.info, Node: paste, Prev: copy, Up: edit + +A.7.4 Paste +----------- + +Paste fractal from clipboard. This is a platform-dependent operation +that may not have an analogue on your platform (e.g. there is no +concept of a clipboard under aalib). + + _Available as_: menu item + + +File: xaos.info, Node: fractal, Next: calc, Prev: edit, Up: menus + +A.8 Fractal +=========== + +This menu contains all functions related to fractal parameters and +display; you can change things like the formula used, coloring modes, +seeds and much else. + +* Menu: + +* formula:: Formula +* mformula:: formulae +* incoloring:: Incoloring mode +* outcoloring:: Outcoloring mode +* plane:: Plane +* palettemenu:: Palette +* uimandelbrot:: Mandelbrot mode +* uiperturbation:: Perturbation +* uiview:: View +* initstate:: Reset to defaults +* tcolor:: True-color coloring modes + + +File: xaos.info, Node: formula, Next: uimandelbrot, Up: fractal + +A.8.1 Formula +------------- + + -- Function: formula keyword + + Set the current fractal formula. `keyword' should be one of the +following: +*'mandel* + Standard Mandelbrot set. *Note mandel::. + +*'mandel3* + Mandelbrot set, power 3. *Note mandel3::. + +*'mandel4* + Mandelbrot set, power 4. + +*'mandel5* + Mandelbrot set, power 5. + +*'mandel6* + Mandelbrot set, power 6. + +*'newton* + Newton's approximation method. *Note newton::. + +*'barnsley* + First Barnsley's formula. *Note barnsley::. + +*'octo* + Fractint's octo. *Note octal::. + +*'phoenix* + Phoenix. *Note phoenix::. + +*'magnet* + Magnet. *Note magnet::. + + _Available as_: command + + +File: xaos.info, Node: uimandelbrot, Next: uiperturbation, Prev: formula, Up: fractal + +A.8.2 Mandelbrot/Julia mode +--------------------------- + +Most fractals rendered by XaoS can be represented as Mandelbrot sets or +Julias. Each point in the Mandelbrot set has its own Julia set. To +learn more about this correspondence, see the tutorial on the Julia set. + + This function switches between Mandelbrot and Julia representations. +When switching to Julia, you need to set the seed--a point selected +from the Mandelbrot set. + + If you run this function from the menu, you are prompted for the +Julia seed as a number. Often, this can be clumsy, and it would be +easier to specify a point with the mouse pointer. If you hit the `M' +key instead of using the menu, the current mouse position is used. + + Good seedpoints lie at the boundaries of the Mandelbrot set; other +seeds usually generate quite a boring fractal. You can also explore +various seeds at high speed using the Fast Julia mode. *Note +fastjulia::. + + Not all fractals have Julias, but XaoS can generate fake Julia sets +for those that do not, which use some Julia-like modification of the +formula; so this function is currently usable for all fractal types. + + _Available as_: menu item + + -- Function: julia bool + + This function is used to enable/disable julia mode in animation +files. + + _Available as_: command line option, command + + -- Function: juliaseed complex + + Select the current julia seed. + + _Available as_: command line option, command + + +File: xaos.info, Node: uiperturbation, Next: uiview, Prev: uimandelbrot, Up: fractal + +A.8.3 Perturbation +------------------ + +Perturbation is a simple trick which changes the point at which orbits +start. Traditionally zero is used, but other values can generate +interesting results too. + + On enabling this function from the menu, you will be asked for a +complex number specifying the perturbation. It is a toggle; selecting +it again resets the perturbation to zero without prompting. + + It can be used to specify a complex number representing a point on +the screen. If you hit the `B' key instead of using the menu, the +current mouse position is used. This too is a toggle, so `B' again will +disable perturbation by setting it to zero. + + This function only has an effect for certain formulae (like the +Mandelbrot set) and only then in Mandelbrot mode. +*Note mandel::. + + _Available as_: menu item + + -- Function: perturbation complex + + This is the scripting-language variation of the perturbation +function. Instead of toggling, you always specify the perturbation to +use. Use 0 0 to disable perturbation. + + _Available as_: command line option, command + + +File: xaos.info, Node: bailout, Next: fastjulia, Prev: maxiter, Up: calc + +A.8.4 Bailout +------------- + +Bailout is the value which is checked for each point of the orbit if +the point is far enough from the complex zero point in the current +iteration. If the point is far enough, then the iteration immediately +stops and the starting point on the screen will be painted with a given +colour, depending on the fractal type and many other settings. + + For the Mandelbrot set this value is 4. Other fractal types usually +have the same bailout value. For most fractals many bailout values give +more or less similar output. E.g., for the second order Mandelbrot set +one can prove that the sequence |z| (z:=z^2+c) tends to infinity if and +only if |z|>2 for some element z of this sequence. In XaoS program, +Bailout value is the square of this 2, i.e. you can change this to any +value greater than 2 for similar results. + + Other fractal types may use other bailout values. The default is 4 +for each types. + + _Available as_: menu item, command line option, command + + -- Function: bailout float + + +File: xaos.info, Node: uiview, Next: initstate, Prev: uiperturbation, Up: fractal + +A.8.5 View +---------- + +Set your current viewpoint in the fractal. This function is useful when +you have found some interesting coordinates somewhere (on a web page, +perhaps) and you want to see that position in XaoS. + + In the dialog you will be asked for the _center_, _radius_ and +_angle_ of the image. + + The center specifies the point which is displayed at the center of +the screen. The radius is the radius of a circle around this point; +XaoS will size the image so that this circle only just fits on the +screen. The angle gives the rotation of the image in degrees. + + People specify fractal coordinates in many ways. Some people use the +coordinates of the upper-left and lower-right visible points, +specifying the coordinates as four numbers x1, y1, x2, y2. To set the +same viewpoint in XaoS, set the real portion of the center to +(x1+x2)/2, the imaginary part of center to (y1+y2)/2, and the radius to +the greater of x2-x1 and y2-y1. + + Other programs use a zoom factor instead of a radius. For these, you +can set the radius to 2/zoom. + + _Available as_: menu item + + -- Function: view float float float float + + This function is used to set the visible area of fractal in +animation files. It doesn't let let you specify the angle, (for that, +see the separate function `angle'), but lets you specify an ellipse +instead of a circle. You can specify both a real and an imaginary +radius, so you have better control over the area that will be visible. +XaoS will size the image so that the ellipse only just fits on the +screen. + + _Available as_: command line option, command + + -- Function: angle float + + Set the rotation angle in degrees. By default this causes +recalculation of the screen. You can enable the fast rotation mode, +which lets you rotate the screen without recalculation; but it slows +down other things, so don't forget to disable it later. + + _Available as_: command line option, command + + +File: xaos.info, Node: initstate, Next: plane, Prev: uiview, Up: fractal + +A.8.6 Reset to defaults +----------------------- + + -- Function: initstate + + This function resets most of XaoS's values to their defaults. It is +useful when you get lost and want to start from the beginning. It +should also be used as the first command of every animation file, to +ensure that the file is always played with the same settings in effect. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: plane, Next: incoloring, Prev: initstate, Up: fractal + +A.8.7 Plane +----------- + + -- Function: plane integer + + All fractals displayed by XaoS are functions with a complex +parameter. They can be be displayed in the normal complex plane where +the `x' coordinate is the real part of the number and the `y' is +imaginary; but they can also be displayed differently: +*mu* + Normal complex plane (default) + +*1/mu* + Inversion--infinity is at 0 and 0 is at infinity. + +*1/(mu+0.25)* + Similar to inversion, but moves the center outside the Mandelbrot + set, so it looks parabolic. + +*lambda plane, 1/lambda, 1/lambda-1* + Lambda plane and its inversion, and with a different center. + +*1/(mu-1.40115)* + A very interesting mode for the Mandelbrot set, this makes small + things large, for easier browsing of the set's details. + The tutorial about planes has some examples. + + In the scripting language, the planes are numbered as follows: + +*0* + mu + +*1* + 1/mu + +*2* + 1/(mu+0.25) + +*3* + lambda + +*4* + 1/lambda + +*5* + 1/(lambda-1) + +*6* + 1/(mu-1.40115) + + _Available as_: command line option, command + + +File: xaos.info, Node: incoloring, Next: outcoloring, Prev: plane, Up: fractal + +A.8.8 Inside coloring mode +-------------------------- + + -- Function: incoloring integer + + Areas inside the set are usually filled in black, but this is only a +convention; you could color them in differently to make the fractal +look more interesting. The only method available to make areas inside +the set visible is to display the value of the latest orbit as the +value of each pixel. + + The tutorial on incoloring has more information and examples. + + XaoS has many different ways to show that value. The cryptic names +of the modes are mathematical formulae, where _real_ means the real +part of the latest orbit, and _imag_ means the imaginary part. _zmag_ +uses the magnitude of the value. The _Decomposition-like_ method uses +the angle of the orbit. Also, truecolor incoloring modes are available, +that display one value in each of the red, blue and green color planes +(or, for some modes, in each of the hue, saturation and value planes). + + In the scripting language, the incoloring mode is specified by one +of the following integers: + +*0* + 0 (default) + +*1* + zmag + +*2* + Decomposition-like + +*3* + real/imag + +*4* + abs(abs(c)-abs(r)) + +*5* + cos(mag) + +*6* + mag*cos(real^2) + +*7* + sin(real^2-imag^2) + +*8* + atan(real*imag*creal*cimag) + +*9* + squares + +*10* + Truecolor. To set exact parameters for truecolor coloring use the + `tcolor' command. + + _Available as_: command line option, command + + +File: xaos.info, Node: outcoloring, Next: tcolor, Prev: incoloring, Up: fractal + +A.8.9 Outside coloring mode +--------------------------- + + -- Function: outcoloring integer + + Outcoloring modes are similar to incoloring modes, but indicate how +to display the areas outside the set instead. As with incoloring modes, +the value of the latest orbit can be used to determine the color of +each pixel, but the default is to use the number of iterations needed +for the value at that point to become recognisably divergent as the +color. + + The tutorial on outcoloring has more information and examples. + + The cryptic names of the modes are mathematical formulae, where +_iter_ means the number of iterations required for the value to become +recognisably divergent, _real_ means the real part of the latest orbit, +and _imag_ means the imaginary part. _binary decomposition_ uses a +different color when the imaginary part of the orbit is lower than +zero, and _smooth_ attempts to remove stripes and discontinuities. +Also, truecolor outcoloring modes are available, that display one value +in each of the red, blue and green color planes (or, for some modes, in +each of the hue, saturation and value planes). + + In the scripting language, the outcoloring mode is specified by one +of the following integers: + +*0* + iter (default) + +*1* + iter+real + +*2* + iter+imag + +*3* + iter+real/imag + +*4* + iter+real+imag+real/imag + +*5* + binary decomposition + +*6* + biomorphs + +*7* + potential + +*8* + color decomposition + +*9* + smooth + +*10* + True-color outcoloring mode. To set exact parameters for truecolor + coloring use `outtcoloring'. *Note tcolor::. + + _Available as_: command line option, command + + +File: xaos.info, Node: tcolor, Prev: outcoloring, Up: fractal + +A.8.10 Truecolor coloring mode +------------------------------ + + -- Function: intcoloring integer + + -- Function: outtcoloring integer + + Truecolor coloring modes are similar to incolor and outcolor +coloring modes; but instead of using a palette, they directly calculate +the red, green and blue components of the color. This lets you display +more parameters at once, and produces interesting and often attractive +results. On 8bpp displays you need to enable the palette emulator +filter first to see anything, amd the quality won't be so good, as far +fewer colors are available per parameter. + + The tutorial on truecolor coloring modes has more information and +examples. + + The cryptic names of the modes are always three mathematical +formulae (one for each color component), where _real_ means the real +part of the latest orbit, and _imag_ means the imaginary part. + + To enable inside/outside truecolor coloring mode in the scripting +language, set `incoloring'/`outcoloring' value to 10 (truecolor coloring +mode) before (or after) calling `intcoloring' or `outtcoloring'. + + In the scripting language, the coloring mode is specified by one of +the following integers: + +*0* + black + +*1* + re*im sin(re^2) angle + +*2* + sin(re) sin(im) sin(square) + +*3* + hsv + +*4* + hsv2 + +*5* + cos(re^c) cos(im^2) cos(square) + +*6* + abs(re^2) abs(im^2) abs(square) + +*7* + re*im re*re im*im + +*8* + abs(im*cim) abs(re*cre) abs(re*cim) + +*9* + abs(re*im-csqr) abs(re^2-csqr) abs(im^2-csqr) + + _Available as_: command line option, command + + +File: xaos.info, Node: calc, Next: mfilter, Prev: fractal, Up: menus + +A.9 Calculation +=============== + +This menu contains functions that control calculation parameters such as +the maximum iteration count and periodicity checking. + +* Menu: + +* range:: Solid guessing +* dynamic:: Dynamic resolution +* periodicity:: Periodicity checking +* maxiter:: Iterations +* bailout:: Bailout +* fastjulia:: Fast Julia mode +* dynamic:: Dynamic resolution +* rotate:: Rotation + + +File: xaos.info, Node: range, Next: periodicity, Up: calc + +A.9.1 Solid guessing range +-------------------------- + + -- Function: range integer + + XaoS has a solid guessing optimization: if all corners of a +rectangle have the same color, it assumes that the whole rectangle is a +solid colored block, and doesn't calculate points inside the rectangle. +This optimization saves lots of calculation, but sometimes introduces +errors. This value alters the maximum size of the rectangle that can be +guessed at one time. The default value is 3; use 0 to disable the +optimization. + + _Available as_: command line option, command + + +File: xaos.info, Node: periodicity, Next: maxiter, Prev: range, Up: calc + +A.9.2 Periodicity checking +-------------------------- + + -- Function: periodicity bool + + Periodicity checking is one way to speed up the calculation. Areas +inside the set always need `maxiter' iterations to determine that the +point is probably inside the set (while it is rare for areas outside to +need anywhere near that much). Often the orbital trajectory falls into a +periodic, repeating cycle; if that can be detected, the calculation can +be stopped early, as there's no way that the orbit can ever leave the +cycle again (hence it cannot diverge, hence the point must be inside +the set). + + Implementating this method efficiently is quite problematic. It +slows down the cases where cycles are not found, because cycle-checking +is quite hard work and has to take place for all points, even those +that don't become cyclic. Because of the inexactness of floating-point +calculations, the cycles are never exact, so you need to use an error +value. Higher error values mean that cycles will be detected sooner, +while lower error values increase the exactness of the calculation. +Higher values can introduce serious errors, especially at the front of +the Mandelbrot set. XaoS detects this automatically and corrects for it +in most cases, but sometimes it might be wrong. Also, other +optimizations in XaoS (such as boundary tracing) don't give this method +much of a chance to run, since areas inside the set are usually not +calculated at all. + + That's why the advantages of this optimization are questionable. You +should probably experiment with enabling and disabling it. Sometimes +XaoS is faster with this enabled, sometimes when disabled. Also, this +method works only when incoloring methods are disabled, and only for +some fractal types (some fractal types, e.g. newton, don't have any +concept of an area `inside the set' at all.) + + The tutorial chapter "Escape time fractals" has more information on +fractal calculation in XaoS, and there is a lengthy section in the +hacker's manual (`xaosdev.texinfo') devoted to the subject. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: maxiter, Next: bailout, Prev: periodicity, Up: calc + +A.9.3 Iterations +---------------- + + -- Function: maxiter integer + + When the fractal set is calculated, a orbital trajectory is examined +for each point. If the orbit diverges to infinity, the point is outside +the set. Otherwise, the point is inside the set. For exact +calculations, you need to know the entire orbital trajectory, which is +infinitely long for areas inside the set, so fractals cannot be +calculated exactly. By default, XaoS calculates at most 170 positions +(iterations) and then gives up; if the point is still inside the +bail-out value, it guesses that the point is inside the set. + + When zoomed into a detailed area, especially one close to the set +boundary, this value could become too low, and the fractal will become +boring. You might try increasing this value if you want to get the +image interesting again; but this necessarily slows down the +calculation at the same time. + + The tutorial chapter "Escape time fractals" has more information on +fractal calculation in XaoS, and there is a lengthy section in the +hacker's manual (`xaosdev.texinfo') devoted to the subject. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: fastjulia, Next: dynamic, Prev: bailout, Up: calc + +A.9.4 Fast Julia mode +--------------------- + + -- Function: fastjulia bool + + By default, changing the seed for the Julia set requires +recalculation of the image (which is quite slow). It's a nice effect to +change the seed smoothly and show the Julia set morphing as the seed +changes. XaoS has a special algorithm which can calculate such +morphings in realtime. It is very inexact, but it is good enough for a +fast preview. + + If you want to select a good seedpoint, enable fast Julia mode and +find a nice place by dragging with the first mouse button depressed; +then change to the Julia mode to see the exact image. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: dynamic, Next: rotate, Prev: fastjulia, Up: calc + +A.10 Dynamic resolution +======================= + + -- Function: fastmode keyword + + XaoS performs many optimizations, but fairly often this is not +enough. In order to keep a high framerate, XaoS automatically lowers +the resolution of the image, increasing it when there is time for more +calculation. This feature is enabled by default when animating, but you +might also like to enable it for new images (which makes the image +`come into focus' when it is recalculated from scratch for whatever +reason), or disable it completely if you don't like it. + + In the scripting languge, the keyword should be one of the following: +*`'never'* + Disable dynamic resolution + +*`'animate'* + Use only for animations (default) + +*`'new'* + Use also for new images + + +File: xaos.info, Node: rotate, Prev: dynamic, Up: calc + +A.11 Image rotation +=================== + +XaoS has support for rotation of the image to any angle. By default, +changing the angle requires recalculation of the whole screen, but when +_fast rotation mode_ is enabled, the angle can be changed smoothly. In +this mode XaoS calculates a larger non-rotated image and rotates it when +needed, so it increases memory requirements and slows XaoS down; hence, +it should be disabled when rotation is not being used. + + The user interface provides two rotation modes--_rotate by mouse_ +which allows the angle to be changed by dragging with the first mouse +button depressed, and _continuous rotation mode_, where the image is +rotated clockwise continuously, and the arrow keys can be used to change +the rotiation speed. + + -- Function: fastrotate bool + + This function is used to enable and disable fast rotation mode. +_Available as_: command line option, command + +A.11.1 Automatic rotation +------------------------- + + -- Function: autorotate bool + + Use this function to enable continuous rotation. In the scripting +language you can also use `morphangle' to get an outwardly similar but +more controllable effect. + + -- Function: rotationspeed float + + Specify the speed of continuous rotation, in degrees per second. +Negative values are allowed and rotate anticlockwise. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: mfilter, Next: ui, Prev: calc, Up: menus + +A.12 Filters +============ + +Filters are a post-calculation effect applied to the resulting image. +They can do things like motion blurring, edge detection, emulation of +palettes or truecolor on displays that can't handle them, and such +things. There is a tutorial chapter about them. + +* Menu: + +* filter:: Filter command +* edge:: Edge detection +* edge2:: Edge detection2 +* starfield:: Starfield +* stereogram:: Random dot stereogram +* interlace:: Interlace filter +* blur:: Motion blur +* emboss:: Emboss +* palettef:: Palette emulator +* anti:: Antialiasing +* truecolor:: Truecolor emulator + + +File: xaos.info, Node: filter, Next: edge, Up: mfilter + +A.12.1 Filter command +--------------------- + + -- Function: filter keyword bool + + This command is used to enable or disable filters. *Note mfilter::. +The _keyword_ specifies the filter to change, and should be one of the +following: + +*`'edge'* + Edge detection + +*`'edge2'* + Edge detection2 + +*`'starfield'* + Starfield + +*`'stereogram'* + Random dot stereogram + +*`'interlace'* + Interlace filter + +*`'blur'* + Motion blur + +*`'emboss'* + Emboss + +*`'palette'* + Palette emulator + +*`'anti'* + Antialiasing + +*`'truecolor'* + Truecolor + + _Available as_: command + + +File: xaos.info, Node: edge, Next: edge2, Prev: filter, Up: mfilter + +A.12.2 Edge detection +--------------------- + +This filter is a standard edge detection algorithm; solid areas are +filled in black. Some fractals look very interesting with this filter +(and some areas of some fractals just look like noise). This version of +the filter produces relatively wide lines, so is useful at higher +resolutions. The filter edge detection2 makes thinner lines, for the +low resolution modes. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: edge2, Next: starfield, Prev: edge, Up: mfilter + +A.12.3 Edge detection2 +---------------------- + +This filter is a standard edge detection algorithm; solid areas are +filled in black. Some fractals look very interesting with this filter +(and some areas of some fractals just look like noise). This version of +the filter produces relatively tight lines, so is useful at lower +resolutions. The filter edge detection makes thinner lines, for the +high resolution modes. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: starfield, Next: stereogram, Prev: edge2, Up: mfilter + +A.12.4 Starfield +---------------- + +The starfield filter generates random stars whose density depends on the +iteration count. Choose your favorite spiral fractal and enable this +filter to get a Grand Design spiral galaxy :) + + _Available as_: menu item, command line option + + +File: xaos.info, Node: stereogram, Next: interlace, Prev: starfield, Up: mfilter + +A.12.5 Random dot stereogram +---------------------------- + +Fractal images are good as a base for random dot stereograms. In case +you don't know what these are, please point your browser to Google or +another search engine and find some articles about such images, because +learning to read such images takes some effort. They make it possible +to generate three dimensional images on a normal monitor without any +additional hardware, by exploiting bugs in the human brain (although +you need two working eyes, and some people never learn to see them; +they can simply ignore this feature). + + XaoS is able to generate these images in animations, so you may use +all normal XaoS functions (except palette changing and palette rotation, +which makes no sense applied to a stereogram). To make the animation yet +more exciting, XaoS emulates "falling" into the set; while you zoom in, +your distance from the set drops and drops--but you never hit it; when +the set reaches the level of your monitor, the distance is changed +again so you are far away. + + To make this work right, XaoS needs to know the _exact size of your +monitor_. Because most platforms have no way to determine this, you +need to use _command line options_ to tune it. If it's not set or is +wrong, the stereograms will probably be impossible to see (if your +monitor is too big or resolution too low), or the images will seem to +be shallow (if your monitor is too small or resolution too high). + + By default XaoS expects my 15" monitor (29.0cm x 21.5 cm). Another +cause of problems is the virtual screen supported by some windowed +environments (like some X servers) that makes a program think that the +resolution is higher than it actually is, and you see only part of this +extra-large screen. + + The worst thing you could possibly do is to run full-screen XaoS in +some graphical windowing system (OS/2 on top of Windows or Wine on top +of Linux, perhaps) where XaoS can't tell the real size of its window at +all. In such cases, it's normally better (not to mention faster) to run +XaoS natively, rather than under such an emulation layer. + + The following command line options are provided to specify sizes: + +*`-screenwidth', `-screenheight'* + Lets you specify the size of your screen in centimeters. Note that + you need to specify the size of the visible image on the monitor, + not the size with edge borders, or the size of the tube. The + simplistic `my monitor is 17", just turn 17" into centimeters' + doesn't work; that 17" is a marketing figure and has only a vague + connection to reality. Get out a ruler and measure it. + +*`-pixelwidth', `-pixelheight'* + Lets you specify the exact size of a single pixel, if XaoS cannot + determine this for itself from your screen size. + + These options are used by some other parts of XaoS as well, so you +should use them even when you don't want to see stereograms. You should +probably write a small starting script (or alias, or shortcut; whatever +your environment uses) that passes the correct parameters to XaoS. + + If the window is _smaller than 8cm in any direction_, you will +probably be unable to see anything; make the window bigger. + + The correct way to see XaoS stereograms is: +*1* + Start XaoS with options specifying the exact size of your screen + or one pixel on it + +*2* + Sit 60cm away from monitor + +*3* + If you use a windowed environment, resize XaoS's window to make it + wider than, say, 15 cm. + +*4* + Enable the filter (by pressing `E') + +*5* + focus on a point far away from the monitor (try to use your own + reflection, if your monitor's not antireflective); the random + blurring should eventually fall into the pattern of a Mandelbrot + set. + +*6* + Carefully use your mouse to zoom into interesting areas (it is + easy to lose concentration when you are not trained; but you can + use the autopilot...) + +*7* + Enjoy animation :) + + If you still can't see the stereograms, it could be that the +fractal, or your eye, is deformed. A deformed fractal can be caused by +your specifying your monitor size wrongly. Visual problems that damage +depth perception, as well as problems like astigmatism, can make it +impossible to see stereograms at all. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: interlace, Next: blur, Prev: stereogram, Up: mfilter + +A.12.6 Interlace filter +----------------------- + +The interlace filter halves the horizontal resolution, and in each +frame alternates between drawing only the even and only the odd lines. +This speeds up the calculation, and in higher resolutions produces a +motion-blur-like effect. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: blur, Next: emboss, Prev: interlace, Up: mfilter + +A.12.7 Motion blur +------------------ + +Motion blur mixes the current frame with previous ones to produce a +motion-blur effect. It might be rather slow in 16bpp truecolor modes. +The best results can probably be seen in 8bpp modes, so you might want +to enable the palette filter first. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: emboss, Next: palettef, Prev: blur, Up: mfilter + +A.12.8 Emboss +------------- + +This is a standard emboss filter, as seen in programs such as the GIMP +or Photoshop. It produces especially nice results with the smooth +outcoloring mode. *Note outcoloring::. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: palettef, Next: anti, Prev: emboss, Up: mfilter + +A.12.9 Palette emulator +----------------------- + +XaoS can work in either palette or truecolor mode. Both modes have +advantages and disadvantages. Palette mode allows effects such as +palette rotation, while truecolor mode allows smoother incoloring and +outcoloring modes and the truecolor coloring modes. If your display is +truecolor, you can enable this filter to get palette emulation (albeit +not as cheaply as in a real paletted mode). + + _Available as_: menu item, command line option + + +File: xaos.info, Node: anti, Next: truecolor, Prev: palettef, Up: mfilter + +A.12.10 Antialiasing +-------------------- + +Antialiasing is a technique to increase image quality by eliminating +jagged edges. XaoS calculates four values for each pixel (on the +subpixel boundaries) and uses the average of them for the pixel value. + + This filter slows XaoS down a _lot_ and greatly increases memory +requirements. It is useful mainly when you want to save images and want +to make them look as nice as possible. Antialiasing also helps a lot +when you want to encode JPEG or MPEG files; they are much shorter if +antialiased (MPEG and JPEG hate jagged edges). + + _Available as_: menu item, command line option + + +File: xaos.info, Node: truecolor, Prev: anti, Up: mfilter + +A.12.11 Truecolor emulator +-------------------------- + +XaoS can work in either palette or truecolor mode. Both modes have +advantages and disadvantages. Palette mode allows effects such as +palette rotation, while truecolor mode allows smoother incoloring and +outcoloring modes and the truecolor coloring modes. If your display is +8bpp, you can enable this filter to get truecolor emulation (but, +obviously, not with as many colors as a real truecolor display). + + More information about filters + + _Available as_: menu item, command line option + + +File: xaos.info, Node: ui, Next: misc, Prev: mfilter, Up: menus + +A.13 UI +======= + +This menu contains functions to control the user interface layer of +XaoS: zooming speed, the autopilot, realtime status information, and so +on. + +* Menu: + +* speed:: Zooming speed +* letterspersec:: Letters per second +* autopilot:: Autopilot +* recalculate:: Recalculate +* interrupt:: Interrupt +* nogui:: Disable XaoS's builtin GUI +* status:: Status +* ministatus:: Ministatus + + +File: xaos.info, Node: speed, Next: letterspersec, Up: ui + +A.13.1 Zooming speed +-------------------- + + -- Function: speed float + + Change zooming speed, where 1 is the default, 2 means twice as fast, +and so on. + + _Available as_: menu item, command line option, command + + In the scripting language you can use the following functions for +better control: + + -- Function: maxstep float + + Selects the zooming/unzooming speed. The parameter specifies how +much of the range will be removed each twentieth of a second; 0 means +nothing, 1 means everything (the parameter obviously has to be less +than 1). Higher values mean faster zooming. + + _Available as_: command + + -- Function: speedup float + When zooming/unzooming, every twentieth of a second the `speedup' +value is added to the current step until `maxstep' is reached. So this +value selects the rate at which zooming stops and starts. Both these +functions are more for internal use of XaoS then for manually written +scripts, but they could come in useful nonetheless. + + _Available as_: command + + +File: xaos.info, Node: letterspersec, Next: autopilot, Prev: speed, Up: ui + +A.13.2 Letters per second +------------------------- + + -- Function: letterspersec integer + + Speed of subtitles for the `textsleep' function. The user can set +this value to suit; it can also be changed with the left and right +arrow keys during animation replay. + + _Available as_: command line option, command + + +File: xaos.info, Node: autopilot, Next: recalculate, Prev: letterspersec, Up: ui + +A.13.3 Autopilot +---------------- + + -- Function: autopilot bool + + To make XaoS yet more impressive, we made a special autopilot mode +that automatically drives into interesting boundaries of the set; you +should press `A', play your favorite music, drink coffee and relax. I +never tried this but it should be really relaxing! Many pictures in the +XaoS gallery were discovered using the autopilot. + + The autopilot also has some additional features. It backtracks if the +zoomed picture is not interesting anymore, and can detect when it's +zoomed into really a boring part of the fractal or reached the limit of +floating point arithmetic on the platform, and restart zooming from the +top. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: recalculate, Next: interrupt, Prev: autopilot, Up: ui + +A.13.4 Recalculate +------------------ + + -- Function: recalculate + + Recalculate current fractal. This should be used when the fractal on +the screen is strange because of error propagation caused by solid +guessing. *Note range::. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: interrupt, Next: nogui, Prev: recalculate, Up: ui + +A.13.5 Interrupt +---------------- + + -- Function: interrupt + + Interrupt current calculation. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: nogui, Next: status, Prev: interrupt, Up: ui + +A.13.6 Disable XaoS's builtin GUI +--------------------------------- + + -- Function: nogui bool + + Disable XaoS menus and dialogs. This function should be used by +external GUI programs; these manipulate XaoS via a pipe, so the +internal GUI should be disabled at the same time. See the hacker's +manual (`xaosdev.texinfo') for more details. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: status, Next: ministatus, Prev: nogui, Up: ui + +A.13.7 Status +------------- + + -- Function: status bool + + Enable/disable status information. This displays some useful +information about the current fractal, such as viewpoint etc. (In +low-resolution modes it also almost completely obscures the current +fractal...) + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: ministatus, Prev: status, Up: ui + +A.13.8 Ministatus +----------------- + + -- Function: ministatus bool + + Enable/disable status line. This contains basic information such as +how much you are zoomed and the framerate. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: misc, Next: helpmenu, Prev: ui, Up: menus + +A.14 Misc +========= + +Miscellaneous functions. + +* Menu: + +* command:: Command +* renderanim:: Render animation +* clearscreen:: Clear screen +* display:: Display fractal +* text:: Display text +* color:: Color +* xtextpos:: Horizontal text position +* ytextpos:: Vertical text position +* textposition:: Text position +* message:: Message + + +File: xaos.info, Node: command, Next: renderanim, Up: misc + +A.14.1 Command +-------------- + +You can invoke all XaoS functions using a simple command language +reminiscent of Scheme. This option lets you run a single command. If +you want to run more than one, you might want to use an XaoS animation +file instead; they are written in the same language. + + _Available as_: menu item + + +File: xaos.info, Node: renderanim, Next: clearscreen, Prev: command, Up: misc + +A.14.2 Render animation +----------------------- + +Render an animation to image files. See How to encode MPEG files for +more information. + + _Available as_: menu item, + + +File: xaos.info, Node: clearscreen, Next: display, Prev: renderanim, Up: misc + +A.14.3 Clear screen +------------------- + + -- Function: clearscreen + + Clear the screen. To display the fractal again, use `display'. *Note +display::. This function is mainly useful in tutorials and similar +animations. + + _Available as_: menu item, command + + +File: xaos.info, Node: display, Next: text, Prev: clearscreen, Up: misc + +A.14.4 Display fractal +---------------------- + + -- Function: display + + Display fractal. This functions reverses the effect of the +`clearscreen', line drawing and text output functions. + + _Available as_: menu item, command + + +File: xaos.info, Node: text, Next: color, Prev: display, Up: misc + +A.14.5 Display text +------------------- + + -- Function: text string + + Display the given text on the screen. This function is mainly useful +in tutorials. Text should be cleared by printing lots of spaces, or +using the `clearscreen' or `display' functions. You +might also want to use the `textposition' function to select the part +of the screen to display the text on. + + To wait for the user to read the text, you can use the `textsleep' +function. + + Example: + + (clearscreen) + (textposition 'center 'middle) + (text "Welcome into my animation") + (textsleep) + (display) + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: color, Next: textposition, Prev: text, Up: misc + +A.14.6 Color +------------ + + -- Function: color keyword + + Change text and line color. _keyword_ should be one of `'white', +`'black' and `'red'. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: textposition, Next: message, Prev: color, Up: misc + +A.14.7 Text position +-------------------- + + -- Function: textposition keyword keyword + + Select text position. The first keyword specifies the horizontal +position, the second the vertical position. The horizontal position +should be one of `'left', `'center', and `'right'. The vertical should +be one of `'top', `'middle', and `'bottom'. + + _Available as_: command line option, command + + +File: xaos.info, Node: message, Prev: textposition, Up: misc + +A.14.8 Message +-------------- + + -- Function: message string + + This function is almost identical to the `text' function, except +that it uses message catalogs in the `catalog' directory to translate +messages into other languages. It should be used only in the +multi-lingual XaoS tutorials. + + _Available as_: command line option, command + + +File: xaos.info, Node: helpmenu, Next: xtextpos, Prev: misc, Up: menus + +A.15 Help +========= + +This menu contains help and tutorials. + + +File: xaos.info, Node: xtextpos, Next: ytextpos, Prev: helpmenu, Up: menus + +A.16 Horizontal text position +============================= + +Select the horizontal position used to display text. *Note text::. It +can be placed at the left, in the center or at the right. + + +File: xaos.info, Node: ytextpos, Next: mformula, Prev: xtextpos, Up: menus + +A.17 Vertical text position +=========================== + +Select the vertical position used to display text. *Note text::. It can +be placed at the top, in the middle or at the bottom of the screen. + + +File: xaos.info, Node: mformula, Next: palettemenu, Prev: ytextpos, Up: menus + +A.18 formulae +============= + +Each escape time fractal has its own formula. XaoS supports the +following formulae: + +* Menu: + +* mandel:: Mandelbrot +* mandel3:: Mandelbrot^3 +* octal:: Octal +* newton:: Newton +* barnsley:: Barnsley1 +* phoenix:: Phoenix +* magnet:: Magnet + + +File: xaos.info, Node: mandel, Next: mandel3, Up: mformula + +A.18.1 Mandelbrot +----------------- + +The Mandelbrot set is the most famous escape time fractal ever. It has +the simple formula z=z^2+c. See the tutorial chapter. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: mandel3, Next: octal, Prev: mandel, Up: mformula + +A.18.2 Mandelbrot^3--Mandelbrot^6 and Mandelbrot^9 +-------------------------------------------------- + +The Mandelbrot^3 fractal is a simple modification of the standard +Mandelbrot set formula, using z=z^3+c instead of z=z^2+c. + + Other derivations of the Mandelbrot set (Mandelbrot^4 and so on) use +even higher powers. See the tutorial chapter. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: octal, Next: newton, Prev: mandel3, Up: mformula + +A.18.3 Octal +------------ + +This is a less well-known fractal that Thomas discovered in Fractint. +It has an interesting shape when displayed in the alternative planes. +*Note plane::. See the tutorial chapter. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: newton, Next: barnsley, Prev: octal, Up: mformula + +A.18.4 Newton +------------- + +This is Newton's approximation method for finding the roots of a +polynomial. It uses the polynomial x^3=1 and counts the number of +iterations needed to reach the approximate value of the root. See the +tutorial chapter. + + This fractal doesn't have Julia sets, but XaoS is able to generate +Julia-like sets which are also very interesting (they are sometimes +called "Nova formulae"). + + _Available as_: menu item, command line option + + +File: xaos.info, Node: barnsley, Next: phoenix, Prev: newton, Up: mformula + +A.18.5 Barnsley1 +---------------- + +This is a formula by Michael Barnsley. It produces very nice +crystalline Julia sets. See the tutorial chapter. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: phoenix, Next: magnet, Prev: barnsley, Up: mformula + +A.18.6 Phoenix +-------------- + +This formula produces very nice Julia sets. See the tutorial chapter. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: magnet, Prev: phoenix, Up: mformula + +A.18.7 Magnet +------------- + +This is a formula that comes from theoretical physics. It is derived +from the study of theoretical lattices in the context of magnetic +renormalization transformations. See the tutorial chapter. + + _Available as_: menu item, command line option + + +File: xaos.info, Node: palettemenu, Prev: mformula, Up: menus + +A.19 Palette +============ + +This menu contains functions to change the palette the fractal is +displayed with. + +* Menu: + +* defpalette:: Default palette +* randompalette:: Random palette +* palette:: Custom palette +* cycling:: Color cycling +* shiftpalette:: Shift palette + + +File: xaos.info, Node: defpalette, Next: randompalette, Up: palettemenu + +A.19.1 Default palette +---------------------- + + -- Function: defaultpalette number + + Create a default palette. In the scripting language, `number' +specifies how much the palette is shifted by. + + Note that changing the palette in truecolor modes forces +recalculation of the whole screen. To avoid this, you can enable the +palette emulation filter first. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: randompalette, Next: palette, Prev: defpalette, Up: palettemenu + +A.19.2 Random palette +--------------------- + + -- Function: randompalette + + Create a random palette. XaoS will automatically pick one of its +palette-generation algorithms and create one. + + Note that changing the palette in truecolor modes forces +recalculation of the whole screen. To avoid this, you can enable the +palette emulation filter first. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: palette, Next: cycling, Prev: randompalette, Up: palettemenu + +A.19.3 Custom palette +--------------------- + + -- Function: palette integer integer integer + + A custom palette lets you re-create some of the random palettes. The +first value specifies the algorithm, which should currently be one of +the following: +*0* + Default palette + +*1* + Black to color gradient + +*2* + Black to color to white gradient + +*3* + Cubistic-like algorithm. + The seed specifies a random seed for the palette; different seeds +generate different palettes. The last value is the amount by which the +palette is shifted. + + Note that changing the palette in the truecolor modes forces +recalculation of the whole screen. To avoid this, you can enable the +palette emulation filter first. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: cycling, Next: shiftpalette, Prev: palette, Up: palettemenu + +A.19.4 Color cycling +-------------------- + + -- Function: cycling bool + + Color cycling is an old and simple effect to animate fractals. The +Mandelbrot set looks particularly nice when color-cycled. On truecolor +displays, color cycling fails to initialize (since those displays don't +have a palette). You can enable palette emulation filter to make it +possible. + + _Available as_: menu item, command line option, command + + In the user interface, colors can also be cycled in the opposite +direction with the "_Reversed color cycling_" function. + + To control the cycling speed, you coan use arrow keys or the "_Color +cycling speed_" function. + + _Available as_: menu item + + -- Function: cyclingspeed integer + + The parameter specifies the number of skips per second. It can be +negative to cycle in the opposite direction. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: shiftpalette, Prev: cycling, Up: palettemenu + +A.19.5 Shift palette +-------------------- + + -- Function: shiftpalette integer + + Shift palette by the specified number of cells. This can be used to +tune the palette's position on the fractal. You can also use the _Shift +one forward_ and _Shift one backward_ functions for fine-tuning. Note +that shifted and rotated palettes could look different on different +displays (because they may have different palette sizes). + + Shifting the palette on truecolor displays causes a recalculation of +the screen. To avoid this, you could use palette emulation filter. +*Note palettef::. + + _Available as_: menu item, command line option, command + + +File: xaos.info, Node: about, Next: support, Prev: menus, Up: Top + +Függelék: B About XaoS +************************ + +Függelék: C Credits +********************* + +(alphabetically) +*Lucio Henrique de Araujo (lucio.matema@gmail.com)* + Brazilian/Portuguese translation + +*Samuel Bizien (samuel@bizien.info)* + Beryl fractal + +*Eric Courteau (ecourteau@cplus.fr)* + francais.cat (translation of tutorials) + +*Jean-Pierre Demailly (Jean-Pierre.Demailly@ujf-grenoble.fr)* + Updates for French translation + +*Radek Doulik (rodo@atrey.karlin.mff.cuni.cz)* + TK interface, windowid patches + +*Martin Dozsa (madsoft@centrum.cz)* + cs.po (Czech translation of menus) + +*Arpad Fekete (Fekete.Arpad.2@stud.u-szeged.hu)* + Some new fractals, and the 'More formulae' menu + +*Zelia Maria Horta Garcia (zeliagarcia@seed.pr.gov.br)* + Brazilian/Portuguese translation + +*Tim Goodwin (tgoodwin@cygnus.co.uk)* + english.cat corrections + +*Ben Hines* + autoconf suggestions, Mac OS X port + +*Jan Hubicka (jh@ucw.cz)* + Zooming routines, ugly interface, palettes, drivers, autopilot, + filters, documentation, tutorials etc. + +*Jens Kilian (jjk@acm.org)* + BeOS driver, deutsch.cat + +*Thomas A. K. Kjaer (takjaer@imv.aau.dk)* + OS/2 ports (320x200 graphics and AA-lib) + +*Zoltan Kovacs (kovzol@math.u-szeged.hu)* + Internationalization, Hungarian translations, finalizing version + 3.1, bug fixes, web design, current maintainer + +*Zsigmond Kovacs (kovzsi@gmail.com)* + Fractal examples + +*J.B. Langston III (jb-langston@austin.rr.com)* + Native Mac OS X port (from version 3.2.2); web redesign; + co-maintainer + +*Andreas Madritsch (amadritsch@datacomm.ch)* + New fractal types, bailout, many fixes + +*Mateusz Malczak (xaos@malczak.info)* + User formula evaluation library + +*Giorgio Marazzi (gmarazzi@vtr.net)* + Improvements and fixes for espanhol.cat + +*Thomas Marsh (thomas.marsh2@gmail.com)* + First zoomer, formulae, planes, X11 driver, inversions, many ideas + +*Dominic Mazzoni (dmazzoni@cs.cmu.edu)* + Macintosh port (version 2.0) + +*David Meleedy* + Grammatical and spelling fixed version of `xaos.6' + +*Paul Nasca (zynaddsubfx@yahoo.com)* + Ministatus improvement + +*Nix (nix@esperi.demon.co.uk)* + Grammatical and spelling fixed version of `xaos.hlp' and other + files + +*Terje Pedersen (terjepe@login.eunet.no)* + Amiga port + +*Cesar Perez (oroz@users.sourceforge.net)* + Spanish translations + +*Fabrice Premel (premelfa@etu.utc.fr)* + Periodicity checking + +*Jan Olderdissen (jan@olderdissen.com)* + Win32 port + +*Ilinca Sitaru (ilinca.sitaru@gmail.com)* + Romanian translation + +*Daniel Skarda* + Fractal examples + +*Andrew Stone (Stone Design - www.stone.com)* + Videator Support, Cocoa improvements, performance mode, bug fixes + +*Marton Torok (marton.torok@gmail.com)* + Small fixes for pipes + +*Pavel Tzekov (paveltz@csoft.bg)* + Win32 support + +*Charles Vidal* + Tcl/Tk interface + +*Tapio K. Vocaldo (taps@rmx.com)* + Macintosh port + +*Tormod Volden* + Fixes for X11 driver to improve compatability with Xorg, + XScreenSaver, Beryl and Compiz + +*Philippe Wautelet (p.wautelet@fractalzone.be)* + Bug fixes for version 3.1.1, French translation, gcc 4.0 fixes + +*Sergio Zanchetta* + Italian translation + +C.0.1 Included Software +----------------------- + +XaoS uses the following libraries. These libraries may be included with +some binary distributions of XaoS. + + _gettext 0.17_ Website: `http://www.gnu.org/software/gettext/' +Copyright (C) 1995-1997, 2000-2007 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later +(http://gnu.org/licenses/gpl.html) This is free software: you are free +to change and redistribute it. There is NO WARRANTY, to the extent +permitted by law. + + _GNU Scientific Library 1.11_ Website: +`http://www.gnu.org/software/gsl/' Copyright (C) 1996, 1997, 1998, +1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 The GSL Team. +License GPLv3+: GNU GPL version 3 or later +(http://gnu.org/licenses/gpl.html) This is free software: you are free +to change and redistribute it. There is NO WARRANTY, to the extent +permitted by law. + + _libpng 1.2.25_ Website: `http://www.libpng.org/pub/png/libpng.html' +Copyright (c) 1998-2008 Glenn Randers-Pehrson Copyright (c) 1996-1997 +Andreas Dilger Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc. + + +File: xaos.info, Node: support, Next: index, Prev: about, Up: Top + +Függelék: D Getting Support +***************************** + +XaoS is a community-supported free software project. There are many ways +to get help, all of which are explained below. + +Függelék: E Home Page +*********************** + +The XaoS homepage is `http://xaos.sf.net'. Check here for the latest +news and information about XaoS and to download the latest versions. + +E.0.1 Discussion Forums +----------------------- + +XaoS has two discussion forums hosted on SourceForge. You can read them +freely, but in order to post, you must to register for a free +SourceForge account. + +*Help* + Provides a place for you to ask for help using XaoS. Other XaoS + users and/or the XaoS developers will answer your questions. + + `http://sourceforge.net/forum/forum.php?forum_id=17768' + +*Open Discussion* + Provides a place to discuss anything related to XaoS or fractals. + You can share tips, your own fractal creations, or any other + fractal-related ideas with other XaoS users. + + `http://sourceforge.net/forum/forum.php?forum_id=17767' + + We welcome you to join these forums and become involved in the XaoS +community. + +E.0.2 Mailing Lists +------------------- + +XaoS currently has three mailing lists hosted on SourceForge. +Unfortunately, there is currently very little traffic on any of them. +Hopefully in the future, we can get more XaoS users and developers +involved in the mailing lists. The lists are as follows: + +*xaos-announce@lists.sourceforge.net* + Low volume list that is used only to announce new releases. + + Subscribe: + `http://lists.sourceforge.net/mailman/listinfo/xaos-announce' + Archive: + `http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-announce' + +*xaos-devel@lists.sourceforge.net* + Developer mailing list, where the developers coordinate and + discuss XaoS development. + + Subscribe: + `http://lists.sourceforge.net/mailman/listinfo/xaos-devel' + Archive: + `http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-devel' + +*xaos-discuss@lists.sourceforge.net* + General discussion list is for XaoS users to share tips and ideas + about XaoS. + + Subscribe: + `http://lists.sourceforge.net/mailman/listinfo/xaos-discuss' + Archive: + `http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-discuss' + + Please feel free to join any or all of these mailing lists and share +your ideas with the developers and other XaoS users. + +E.0.3 Bug Reports +----------------- + +If you think you have found a bug in XaoS, please report it. The +developers will do their best to resolve the bug in a timely manner. + + Bug Tracker: +`http://sourceforge.net/tracker/?atid=105771&group_id=5771' + + Please don't submit duplicate bugs. Browse the existing ones first +to make sure nobody has already reported it. You may add additional +information about a bug by entering a comment on an existing bug. + + If you are not sure if something is a bug, please open a support +request. The developers will try to answer your question and can +convert your support request to a bug if necessary. + + Support Requests: +`http://sourceforge.net/tracker/?atid=205771&group_id=5771' + +E.0.4 Feature Requests +---------------------- + +If you have an idea for a great new feature you'd like to see added to +XaoS, please let us know about it. You can submit a feature request +via SourceForge, and the XaoS developers will do their best to +implement your request in a future version. + + Feature Requests: +`http://sourceforge.net/tracker/?atid=355771&group_id=5771' + + Please don't submit duplicate feature requests. Browse the existing +ones first to make sure nobody has already requested the feature your +want. You may add your vote for a feature by adding a comment to the +existing request. + + +File: xaos.info, Node: index, Prev: support, Up: Top + +Index of functions +****************** + + +* Menu: + +* angle: uiview. (line 43) +* animateview: animateview. (line 7) +* autopilot: autopilot. (line 7) +* autorotate: rotate. (line 28) +* bailout: bailout. (line 26) +* clearline: linemenu. (line 73) +* clearlines: linemenu. (line 79) +* clearscreen: clearscreen. (line 7) +* color: color. (line 7) +* cycling: cycling. (line 7) +* cyclingspeed: cycling. (line 25) +* defaultpalette: defpalette. (line 7) +* display: display. (line 7) +* fastjulia: fastjulia. (line 7) +* fastmode: dynamic. (line 7) +* fastrotate: rotate. (line 20) +* filter: filter. (line 7) +* formula: formula. (line 7) +* incoloring: incoloring. (line 7) +* initstate: initstate. (line 7) +* intcoloring: tcolor. (line 7) +* interrupt: interrupt. (line 7) +* julia: uimandelbrot. (line 31) +* juliaseed: uimandelbrot. (line 38) +* letterspersec: letterspersec. (line 7) +* line: linemenu. (line 40) +* linekey: linemenu. (line 67) +* load: load. (line 7) +* loadexample: loadexample. (line 7) +* maxiter: maxiter. (line 7) +* maxstep: speed. (line 17) +* message: message. (line 7) +* ministatus: ministatus. (line 7) +* morphangle: morphangle. (line 7) +* morphjulia: morphjulia. (line 7) +* morphlastline: linemenu. (line 58) +* morphline: linemenu. (line 48) +* morphview <1>: morphview. (line 7) +* morphview: smoothmorph. (line 7) +* moveview: moveview. (line 7) +* nogui: nogui. (line 7) +* outcoloring: outcoloring. (line 7) +* outtcoloring: tcolor. (line 9) +* palette: palette. (line 7) +* periodicity: periodicity. (line 7) +* perturbation: uiperturbation. (line 26) +* plane: plane. (line 7) +* quit: quit. (line 7) +* randompalette: randompalette. (line 7) +* range: range. (line 7) +* recalculate: recalculate. (line 7) +* record: record. (line 7) +* rotationspeed: rotate. (line 34) +* savecfg: savecfg. (line 7) +* saveimg: saveimg. (line 7) +* savepos: savepos. (line 7) +* shiftpalette: shiftpalette. (line 7) +* speed: speed. (line 7) +* speedup: speed. (line 26) +* status: status. (line 7) +* stop: zoom. (line 29) +* text: text. (line 7) +* textposition: textposition. (line 7) +* textsleep: textsleep. (line 7) +* unzoom: zoom. (line 23) +* usleep: usleep. (line 7) +* view: uiview. (line 31) +* wait: wait. (line 7) +* zoom: zoom. (line 17) +* zoomcenter: zoom. (line 11) + + + +Tag Table: +Node: Top440 +Node: Overview1491 +Node: Why?1688 +Node: What?3850 +Node: tutorial4423 +Node: controls14259 +Node: video16315 +Node: format20282 +Node: writehelp25754 +Node: xshl26241 +Node: drivers27386 +Node: aa28084 +Node: BeOS30601 +Node: DGA33457 +Node: dos34077 +Node: dX-fullscreen36510 +Node: dX-window37637 +Node: ggi37722 +Node: plan938273 +Node: SVGAlib39374 +Node: win3240754 +Node: X1142660 +Node: menus43657 +Node: root44527 +Node: animroot44588 +Node: stopreplay44871 +Node: plc45020 +Node: load45377 +Node: linemenu45710 +Node: animf48485 +Node: animateview49195 +Node: smoothmorph49730 +Node: morphview50314 +Node: morphjulia51377 +Node: moveview52005 +Node: morphangle52236 +Node: zoom52905 +Node: time53743 +Node: usleep54217 +Node: textsleep54618 +Node: wait55175 +Node: file55760 +Node: loadpos56031 +Node: savepos56293 +Node: record56739 +Node: play57242 +Node: saveimg57454 +Node: loadexample58090 +Node: savecfg58446 +Node: quit58833 +Node: edit59010 +Node: undo59200 +Node: redo59473 +Node: copy59648 +Node: paste59940 +Node: fractal60224 +Node: formula60787 +Node: uimandelbrot61519 +Node: uiperturbation63041 +Node: bailout64230 +Node: uiview65327 +Node: initstate67336 +Node: plane67829 +Node: incoloring68996 +Node: outcoloring70522 +Node: tcolor72247 +Node: calc73867 +Node: range74331 +Node: periodicity74958 +Node: maxiter77134 +Node: fastjulia78377 +Node: dynamic79136 +Node: rotate79975 +Node: mfilter81407 +Node: filter82063 +Node: edge82712 +Node: edge283251 +Node: starfield83795 +Node: stereogram84154 +Node: interlace88540 +Node: blur88956 +Node: emboss89371 +Node: palettef89706 +Node: anti90274 +Node: truecolor90981 +Node: ui91592 +Node: speed92053 +Node: letterspersec93116 +Node: autopilot93511 +Node: recalculate94348 +Node: interrupt94723 +Node: nogui94958 +Node: status95432 +Node: ministatus95835 +Node: misc96140 +Node: command96541 +Node: renderanim96927 +Node: clearscreen97180 +Node: display97525 +Node: text97831 +Node: color98571 +Node: textposition98855 +Node: message99325 +Node: helpmenu99732 +Node: xtextpos99871 +Node: ytextpos100144 +Node: mformula100424 +Node: mandel100775 +Node: mandel3101054 +Node: octal101531 +Node: newton101870 +Node: barnsley102414 +Node: phoenix102694 +Node: magnet102930 +Node: palettemenu103272 +Node: defpalette103608 +Node: randompalette104104 +Node: palette104609 +Node: cycling105473 +Node: shiftpalette106452 +Node: about107164 +Node: support111546 +Node: index115382 + +End Tag Table diff --git a/doc/xaos.texinfo b/doc/xaos.texinfo new file mode 100644 index 0000000..fbcc70c --- /dev/null +++ b/doc/xaos.texinfo @@ -0,0 +1,3468 @@ +\input texinfo @c -*-texinfo-*- + +@c The original files are xaos.geninfo and xaos.hlp. xaos.texinfo is +@c automatically generated. So make all changes in the orignal files please. +@c To regenerate xaos.texinfo, please run "mktexinfo". + +@c Use A4 paper - If you don't like that, remove the following 3 lines. +@iftex +@afourpaper +@end iftex + +@setfilename xaos.info +@settitle An fast realtime interactive fractal zoomer --- user's manual +@dircategory Graphics +@direntry +* XaoS: (xaos). A fast real-time interactive fractal zoomer +@end direntry + + +@ifinfo +@copyright{} 1996-2008 Jan Hubicka and the XaoS Development Team + +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. + +@end ifinfo + +@c %**end of header + +@set VERSION 3.4 +@set DATE April 17, 2008 + +@titlepage + +@title{XaoS @value{VERSION}} +@subtitle{A fast real-time interactive fractal zoomer --- User's manual} + +@author{Jan Hubi@v cka} +@tex +Dukelsk\'ych bojovn\'\i ku 1944 +@end tex +@* +390 03 T@'abor @* +Czech Republic + +Email: @code{jh@@ucw.cz} + +@value{DATE} + +@page +@vskip 0pt plus 1filll +@vskip 0pt plus 1filll + +@copyright{} 1996-2008 @tex Jan Hubi\v cka and the XaoS Development Team +@end tex + +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. + +@end titlepage + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node Top, Overview, (dir), (dir) + +@ifinfo +@top XaoS @value{VERSION} +@flushright 1.0 +A real-time interactive fractal zoomer +User's manual +@value{DATE} +@end flushright + +This manual contains user documentation about XaoS --- a fast real-time fractal +zoomer. XaoS uses a development model, so sources are freely available. The +file @code{xaosdev.texinfo} in the source documentation contains a hacker's +manual (design overview, algorithm description etc.). +@end ifinfo + +@menu +* Overview:: What does this software do then? +* tutorial:: XaoS tutorial +* controls:: Basic controls +* video:: How to encode video files +* format:: XaoS's file format description +* writehelp:: How to write XaoS help files +* xshl:: XaoS simple hypertext language +* drivers:: Driver specific documentation +* menus:: Functions, menu items and command line parameters +* about:: Credits +* support:: Getting Support +* index:: Function index +@end menu + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node Overview, tutorial, Top, Top + +@chapter Overview +@menu +* Why?:: Why yet another fractal generator? +* What?:: What does this software do then? +@end menu + +@node Why?, What?, Overview, Overview +@section Why yet another fractal generator? + + +We decided to make XaoS, because all fractal browsers we know of take a +long time to calculate each image. You may browse nice images +generated by them but real impressions of fractals --- the self +similarity and infinite zooming into the nice parts of fractals --- +can be seen only in animations. There are many programs available that +make nice animations, but they take a long time to calculate and lots +of space on disk. Most such animations are quite ugly because their +authors can't see them without many hours of calculations. + +A natural question is: is it possible to generate such animations in +real-time? The answer was negative for many years, since the Mandelbrot set is +very computationally expensive. Things are changing. Today's computers +are fast enough to calculate approx. 10.000 of pixels per frame, +which is enough +for a very low resolution animation (100x100). Several programs doing that +are available. But 100x100 animation still looks quite ugly. To make +animation nice you need at least 320x200 pixels. And that is 6 times more! +One possibility is to wait until computers will be fast enough, but +it will take many years, and then 320x200 animations will be obsolete +and everyone will want 1024x768 resolution instead or more. + +We found a special algorithm that saves up to 99.98% of calculations during +zooming by reusing pixels already calculated in previous frames. There were +some programs doing similiar tricks before but we don't know about any able +to do zooming interactively with a speed similar to XaoS. Many other tricks +were later implemented XaoS to achieve yet higher framerates. Now XaoS does +up to 120 frames per second on a 120Mhz pentium in a fullscreen 320x200 +animation, and calculates an average of 160 (0.24%) pixels per frame. This makes +XaoS fast enough to achieve its primary goal, realtime animation, but there +are still many areas that could improve, since more complex fractals, +higher resolutions, or slower computers still bring many problems. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node What?, , Why?, Overview +@comment node-name, next, previous, up +@section What does this software do then? + +XaoS is a realtime interactive fractal zoomer. This means that it lets you +zoom smoothly into any place in the fractal you choose without the many hours +of calculation required by most other fractal generators. It now has many +other features too, like 13 different fractal types, autopilot, special coloring +modes, support for various bit depths (8bpp, truecolor, hicolor and realcolor), +random palette generation, color cycling etc... + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node tutorial, controls, Overview, Top + +@chapter XaoS tutorial + +This is a brief introduction to the basic XaoS features. + +@section How to zoom +The main advantage of XaoS is that after a few seconds' delay to calculate +the first image, you may choose any point with the mouse and press the @emph{left} button. +The image will start to zoom smoothly into the point you choose. You may move +the mouse and zoom smoothly into interesting areas. By pressing the @emph{middle +button} (or @emph{left+right} buttons) you may also +@emph{move the image} using ``drag & drop'' if you missed an interesting +place. @emph{Unzooming} is also possible by using the @emph{right button}, +but it is much slower because optimizations are not so effective as for zooming. + +In case you think that the default @emph{speed} is boring (it is quite slow, to +make XaoS smooth on a slow computer) you may change it by pressing @emph{arrow +up/down}. But faster zooming is more expensive, so if the speed is too high +you will see little but funny colorful blinking rectangles. + +@section Autopilot + +To make XaoS yet more impressive we made a special autopilot that +automatically drives into interesting boundaries of the set. So you can +press @code{A}, play your favorite music, drink coffee and relax. I never +tried this but it should be really relaxing! Many pictures in the XaoS +gallery were discovered using the autopilot. + +The autopilot also has some additional features. It turns back when the +zoomed picture stops being interesting, and is able to spot when it's zoomed +into a really boring part (or has reached the limit of floating point +numbers) and restart zooming from the top. + +@section Various fractal formulae + +XaoS also supports formulae other than the Mandelbrot set. You may change +@emph{formula} using the @emph{number keys} +or @emph{SHIFT+letters}. + + + +On keys @code{1} to @code{5} are @emph{Mandelbrot sets of various power}. The ``normal'' +Mandelbrot set is on key @code{1}. + +On key @code{6} is a fractal called @emph{Newton}. It is Newton's famous formula for finding roots. + +On key @code{7} is the @emph{fourth ordered Newton} fractal. + +On key @code{8} is a fractal called @emph{Barnsley}. + +On key @code{9} is @emph{Barnsley's second} fractal. + +On key @code{0} is @emph{Barnsley's third} fractal. + +With keys @code{SHIFT-A} you can display a fractal called @emph{octo}. It is a fractal that Thomas +discovered in fractint. + +With keys @code{SHIFT-B} you can display a fractal called @emph{Phoenix}. It is a very nice and quite famous fractal. + +With keys @code{SHIFT-C} you can display a fractal called @emph{Magnet}. This fractal has quite a complex formula so it is +a bit slow. + +With keys @code{SHIFT-D} you can display the @emph{Magnet2} fractal. + +The rest of the built-in fractals are accessible through an other menu, but +you can still use the hotkeys. + +On @code{SHIFT-E} is a fractal called @emph{Triceratops} found by Arpad. + +On @code{SHIFT-F} is a fractal called @emph{Catseye} found by Arpad. +This is more interesting if you change the bailout value. + +On @code{SHIFT-G} is a fractal called @emph{Mandelbar}. It was in +Gnofract4d, and they found it at: +http://mathworld.wolfram.com/MandelbarSet.html + +On @code{SHIFT-H} is the @emph{Lambda} fractal. + +On @code{SHIFT-I} and @code{SHIFT-J} are the @emph{Manowar} +and @emph{Spider} fractals, they were found by users of fractint. +(Scott Taylor or Lee Skinner) +It was on http://spanky.triumf.ca/www/fractint/ +taylor_skinner_type.html + +The next 3 fractals are famous classic fractals. + +On @code{SHIFT-K} is the @emph{Sierpinski} Gasket. +You can change its shape by selecting another Julia seed. +(This is for technical reasons.) + +On @code{SHIFT-L} is the @emph{Sierpinski Carpet.} +It's shape can also be changed by selecting another Julia seed. + +On @code{SHIFT-M} is the @emph{Koch Snowflake.} + + + +@section Out-coloring modes + +To make fractals yet more interesting, more coloring modes for points +outside the set are provided. ``Classical coloring mode'' uses the number of +iterations that the orbit required to escape to (nearly) infinity. You can change this +mode from the @emph{Fractal menu} or by pressing key @code{C} +To see more about coloring modes, try the tutorial on Incoloring modes from the XaoS features overview. + +Those cryptic names for coloring modes are mathematical formulae, where @emph{iter} means number +of iterations, @emph{real} means real coordinate of last orbit, and @emph{imag} means imaginary +coordinate of last orbit. + +@section In-coloring mode + +In-coloring mode is similar to out-coloring, except that it changes how +things inside the set are displayed. This can also be changed from the @emph{fractal +menu} or by pressing @code{F}. + +You might also want to see the tutorial on +Out-coloring modes from the XaoS features overview. + +@section Planes + +All fractals displayed by XaoS are functions with a complex parameter. It +can be displayed in the normal complex plane, where x is the real part of +the number, and y is the imaginary part; but it can also be displayed in +a number of other planes. You can select the plane to use from the +@emph{Fractal menu}, or by pressing @code{I}. + +Like the coloring modes, planes have cryptic names. You guessed it, they're +mathematical formulae. Here @code{mu} means coordinates in the normal +complex plane. If you have coordinates in @code{1/mu} plane, and you need +coordinates in the a complex plane (to calculate the Mandelbrot set) you +simply use the coordinates as mu. Lambda is another plane that can be +converted to mu using a similar formula. + +@table @strong +@item mu +normal mode. + +@item 1/mu +Inversion: infinity goes to 0 and 0 goes to infinity. + +@item 1/(mu+0.25) +Similar to inversion, but moves the center outside of the +Mandelbrot set so that it looks parabolic. + +@item lambda +Lambda plane. + +@item 1/lambda +Inversion of lambda plane. + +@item 1/lambda-1 +Inversion with moved center. + +@item 1/(mu-1.40115) +A very interesting mode for the Mandelbrot set. It makes small things +big, so you can browse the set's details easily. +@end table + + +@section Mandelbrot/Julia switching + +Most of the fractals displayed by XaoS (currently all of them) have two +forms: Mandelbrot and Julia. Every point in a Mandelbrot set has its +own Julia set. To see more about this correspondence, try the tutorial on +Julia set from the Introduction to fractals. + +In the Mandelbrot mode, you can get a corresponding Julia by moving the mouse +to an interesting point and pressing @code{M}. To get back press @code{M} +again. Some fractals (Barnsley and phoenix) are already in their Julia +versions, because the Mandelbrot ones are boring. But by pressing @code{M} +in such fractal you should get the Mandelbrot version, and by choosing another +point as the base point and pressing @code{M} again you should get a +completely different fractal. The most interesting points for Julia sets +are at the boundaries of the Mandelbrot set. Most of the Julias inside or +outside the set are boring. + + +@section Fast Julia preview mode + +Fast Julia mode is a quick way to find a point to use as a base for the Julia +set.. Just press @code{J} and a small Julia set will be displayed in the top +left corner. Then move the mouse around with button 1 depressed, and the Julia +for the point the mouse is over will be automatically generated. + +@section Palette + +If you think that the default XaoS colors are ugly or you are just +bored by them you can change it by pressing @code{P}. XaoS will +automatically generate random palettes. Many of them look ugly, so +press @code{P} again to get another one until you find one you like. + +@section Filters + +Many interesting effects are done by post-calculation filters. @xref{filter}. +XaoS has filters that do everything from embossing, through motion-blurring, +right through to turning the fractal into a stereogram. To enable them use +the @code{filter menu} or press @code{E}. + +@section Palette cycling + +This is a very old trick that makes the Mandelbrot set a little flashier. You +may enable or disable it using @code{Y}. In the truecolor modes you need +to enable the palette emulator filter first. This is done +via the @code{E} key, or from the filter menu. + +@section Changing number of iterations + +To calculate fractals perfectly, you need an infinite number of +iterations. XaoS does just the first few of them, so after lots of zooming +you may get into a place that looks quite boring, and the boundaries of the +set are rounded, without any interesting details. This can be changed by +changing the number of iterations: + +Press and hold @code{arrow right} and wait until iterations are high enough. +This may slow down calculation much. To reduce number of iterations +press @code{arrow left}. + +@section Changing resolution + +XaoS usually starts in a low resolution (320x200 or thereabouts) to make +calculations faster. If you have a fast computer or you need to +save bigger @code{.gif} images, you may change the resolution. This +can be done by pressing @code{=} in the full screen drivers, or simply +by resizing the XaoS window. + +@section Changing driver + +XaoS usually has more than one driver available. You may change it on +the fly in case you want a different one. For example, XaoS started in X11 +can be switched at runtime to use the AA driver. This can be done from the +UI menu. + +This action is bit dangerous, because XaoS can crash during initialization +if there is some problem with initialization; XaoS tries to initialize a new +driver, and if it fails it attempts to return back to the original. Sometimes +this is impossible, and all XaoS can do is terminate.. + +@section Other features +XaoS has many other features, but they don't fit into this tutorial. Most of +them are available from the menu, so you can experiment with them. You might +also want to see the @emph{animated tutorials} from the @emph{help menu}, +to have an idea what XaoS can do. + + +@c ## chapter tutorial ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node controls, video, tutorial ,Top + +@chapter Basic controls +By default the mouse buttons work in the following way: + +@table @strong +@item left +zoom in +@item right +zoom out +@item middle +move fractal in a drag-and-drop fashion +@end table + +@emph{Note:} Since most Macs only have one button mice, these controls +are emulated on Mac OS X using modifier keys. See the help section on +Mac OS X for details. + +This behavior can change. If you enable rotation, the first button is used for rotating +fractals. Also, in fast Julia mode, the first button is used to change the seed. + +If you don't have a middle button, press both buttons to enable +emulation. + +After few minutes of zooming you will probably exceed the precision and the +fractals will get boring. If you are getting strange big rectangles on the screen, +you probably reached the numeric limit: there is no way to avoid this except +un-zoom back and choose a different area. It doesn't hurt so much, since you have +zoomed approximately 64 051 194 700 380 384 times, so there are quite a lot of areas to +explore. Algorithms with unlimited precision exist, but they are still too +slow for real-time zooming. + +The other possibility is that you have reached the iteration limit. The fractal is +calculated approximately, and in this case you need to increase number of +iterations used for approximation (and decrease the speed in the process). +This is done from the menu or using the arrow keys @emph{Left} and @emph{Right}. + +An @emph{Up} and @emph{Down} keys should be used to change zooming +speed. Note that higher speed costs more and image will be blocky. + +This behavior can also change. With palette cycling enabled, @emph{Left} +and @emph{Right} keys change cycling speed; in continuous +rotation they change rotation speed. + +All other functions are available from the menu, which (in the default +configuration) are displayed when you move the mouse to the top of the +screen/window. It is useful to learn the shortcut keys, which are +shown in gray next to the menu items they trigger. + + +@c ## chapter controls ## + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node video, format, controls ,Top + + +@chapter How to encode video files from XaoS + +To create a video, make and @code{xaf} file first (the easiest way to do this is +to use the @emph{record} function in the file menu). Then you need to render +the animation. XaoS can output sequences of ordinary @code{PNG} images, that +can later be used by a video encoder. + +@section Generating image sequences for video + +To generate an image sequence, choose @emph{Render Animation} from the @emph{Misc} +menu. You can also use the following command on the command line: + + +@example +xaos -render [filename] -size 352x240 -antialiasing +-renderframerate 24 -basename [basename] +@end example + + +@emph{File to render} (@code{[filename]}) is the name of the @code{xaf} file, +@emph{Basename} (@code{[basename]}) is the name used as the base filename for rendered images. This should also include the path where you want to save the images. +XaoS adds a four digit sequence number and @code{.png} extension to this name automatically. + +You might also want to change the resolution. Make sure that the resolution +you choose is supported by the video codec you wish to use. + +The framerate can also be altered. Make sure you choose a framerate that is supported by +the video codec you wish to use. + +@emph{Antialiasing} (@code{-antialiasing}) is used to produce anti-aliased images. +It takes a much longer +time and much more memory to calculate them, but resulting images are better +for video compression and they result in a much smaller video file. +(the same is true of @emph{JPEG images}) + +On the other hand, the other XaoS rendering option @emph{Always Recalculate} (@code{-alwaysrecalc}) (which disables +XaoS's zooming optimizations) is @emph{not recommended}. If that's used, the +sequence of animation then contains quite a lot of extra information, which +increases size of video file, but because of the codec's lossy compression it is hard +to see any difference, so it's not worth it. +@section Rendered files +Once you start it, XaoS will generate thousands of frames. They take quite +a long time to calculate and save, and consume plenty of disk space. +(e.g. to render part 1 of the tutorial you need about 60MB and half an hour of time). + +All images are named @code{[basename]framenum.png}. For example @code{intro0001.png} is +the first frame of the animation intro. If consecutive frames are the same, XaoS +doesn't save them, so some frames may be missing. If your encoder can't handle +that, you will need to write a simple script which will fill in the gaps by means +of @code{mv} or symbolic linking. + +A list of all filenames is saved into the file @code{[basename].par}, where each line is +the name of one frame. The names repeat here if necessary, so you can use this +file to supply filenames to the encoder. +@section Encoding videos +Once XaoS has generated the png files for each frame of the animation, you +can use a third-party video encoder to convert the sequence of images into +a video file. We currently recommend the following encoders, which support +a wide variety of video codecs and file formats: +@table @strong +@item ffmpeg +Available from: @code{http://ffmpeg.mplayerhq.hu/} +Instructions: @code{http://ffmpeg.mplayerhq.hu/faq.html#SEC12} +@item mencoder +Part of mplayer, available from: http://www.mplayerhq.hu/ +Instructions: @code{http://www.mplayerhq.hu/DOCS/HTML/en/menc-feat-enc-images.html} +@end table +These are both command line tools. If you prefer a graphical tool, you may +prefer Quicktime Pro from Apple (http://www.apple.com/quicktime/pro/). However, +this software costs approximately US$30, and the authors of XaoS have no +experience with it. Although QuickTime may be easier to use, the two free +encoders above are just as capable once you learn how to use them. + + +Note: we used to recommend Berkeley parallel MPEG encoder to +encode the generated png files into MPEG videos. We have kept +the instructions mainly for historic purposes. + + +@c ## chapter video ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node format, writehelp,video ,Top +@chapter XaoS's file format +This section describes the format used by XaoS for animations, configuration +files and saved positions. All these files have a common format, designed +to be easily readable, to allow manual editing of files and easy conversion by +other programs. + +I also taken care to make it easily extensible for future versions of XaoS +so I hope there will not be many incompatibilities between various XaoS +versions. + +The format is a simple set of commands executed sequentially. XaoS does not provide +any variables/cycles as usual scripting languages do, but future extension to +full-blown Scheme should be easy since the format uses Scheme-like syntax. +The syntax of every command is: + +@code{(command_name }@emph{[param1] [param2]}@code{)} + +where parameters are optional and separated by whitespace (an arbitrary number +of spaces, tabs and newlines). The parameters can have the following types: + +@table @strong +@item integer +number w/o decimal point (@code{123}) +@item float +floating point number in decimal notation with optional exponent (@code{1.23E2}) +@item keyword +text started by quote @code{'}. It is used to pass various string constants +like formula name (@code{'mandel}) Quote is required for scheme compatibility +@item string +Text inside double quotes. The only parameter that should contain whitespace +@item boolean +@code{#t} for true or @code{#f} for false +@end table + +There is a complete description of all XaoS functions (with some examples) and an +index of functions in the XaoS registry. @xref{menus}. You may particularly want +to read about the animation functions. @xref{animf}. Also, the following functions +are significant: + +@table @strong +@item load + +This function loads and interprets a file. It works similarly to @code{#include} +in C. +@item initstate + +Available in version 3.0 and above, this function resets XaoS's state to default +values. This command should be at the beginning of each animation file, +since otherwise some stuff previously enabled by user could cause unexpected +effects. State is not reset by default before playing animations since it would +make it impossible to write macros. Current versions don't really need macros, but +in future versions, when the Scheme programming language will be available, this +should be a much more interesting subject. +@item usleep + +This function waits for a selected amount of time(in usec) before processing the +next command. The screen is recalculated and displayed at the beginning of +the sleep if necessary. The remaining time is spent by waiting, calculating if +necessary, or performing any animation you entered via animation commands. +@item wait + +Waits until the animation or image rendering is complete. Do not call this +function when zoom, or continuous rotation is active otherwise deadlock happens. It is +a good idea to call it immediately before text subtitles are displayed, since it looks +ugly when they are displayed over a blocky unfinished fractal. Because the +degree of blockiness at a given instant is a function of your machine speed, +it may look nice for you but ugly for others with slower machines. Also +you should call this after an animation is performed, before the switch to another +fractal happens; since the switch involves calculation, the screen is stopped +for a while and an unfinished fractal there looks ugly. +You should also call it, when you want to do something as soon as possible. +@end table + +Example: + + +@example +;configure everything for the first frame +(inistate) +(palette 1 1163254293 0) ;custom palette +(cycling #t) ;enable cycling +(cyclingspeed 7) +(maxiter 276) ;higher number of iterations +(range 3) ;default range for solid guessing +(usleep 1000000) ;second frame starts here +(moveview -1.8101154154614007889 -8.2687205907162041209E-05) +;just move the image +(usleep 1000000) ;third frame +(morphview -1.8101154154614007889 -8.2687205907162041209E-05 +6.277210971069452361E-10 6.2772109785334669875E-10) +;10 seconds of zooming into selected +rectangle +(usleep 100000000) +@end example + + +The best way to learn XaoS command language is probably to read position files +and modify them. For example, to create zooming animation from the original +file: + + +@example +(initstate) +(defaultpalette 0) +(formula 'mandel) +(view -1.64128273713 -5.50393226816E-05 9.69332308848E-08 +9.69332308834E-08) +@end example + + +Just change the @code{view} command to @code{morphview}, and add @code{usleep}: + + + +@example +(initstate) +(defaultpalette 0) +(formula 'mandel) +(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 +9.69332308834E-08) +(usleep 10000000) +@end example + + +The following code produces Julia morphing in the real axis: + + +@example +(initstate) +(fastjulia #t) +(juliaseed -2 0) +(morphjulia 2 0) +(usleep 2000000) +@end example + + + +And following is the ``rotozooming'' animation: + + + +@example +(initstate) +(fastrotate #t) +(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 +9.69332308834E-08) +(morphangle 300) +(usleep 10000000) +(wait) +(fastrotate #f) +@end example + + + +@chapter XaoS gallery + +I plan to make a gallery of animations and position files on the XaoS home-page, +so please send any nice animations and images you created using XaoS +to the mailing list or upload them to our website. +@c ## chapter format ## +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node writehelp, xshl,format ,Top +@chapter How to write XaoS help files +XaoS help is stored in the file @code{help/xaos.hlp}. It is divided into parts, +each part being started by a @emph{keyword}. In the help file keywords are +written as @code{%keyword} + +If you are writing documentation about some command in the XaoS function +registry, use the same keyword as the name of the command in order to make +context sensitive help work. + + +@c ## chapter writehelp ## +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node xshl, drivers,writehelp ,Top +@section xshl +@emph{Xshl} stands for @emph{XaoS simple hypertext language}. It +uses similar tags to HTML. It is simpler and more restrictive in order to +make it easy to parse using various scripts. In C code you can use the +library present in @code{src/util/xshl.c} to parse it. + +The following tags are supported: + +@table @strong +@item head +make headings (should be at the beginning of the page, at least) +@item emph +emphasize +@item tt +Use non proportional font +@item br +Break line +@item p +Next paragraph +@item dl +Definition list +@item dt +Definition tag (should be used only inside a definition list) +@item dd +Definition description (should be used only inside a definition list) +@item center +align to center +@item right +align to right +@item red +change color to red (should not be used in help files) +@item black +change color to black (should not be used in help files) +@item white +change color to white (should not be used in help files) +@item a name +link to other help page +@item tutor name +activate tutorial +@item notex +Ignore this in texinfo manuals +@end table + + + +@c ## section xshl ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node drivers, menus,xshl ,Top + +@chapter Platform-specific documentation +XaoS is portable and works on many different platforms. Since not all platforms are +exactly the same, there are some differences between the behavior of XaoS on +different platforms. Here is documentation about each specific port. + +@c ## chapter drivers ## + +@menu +* aa:: AA-lib --- high quality ascii art driver +* BeOS:: BeOS drivers +* DGA:: DGA driver +* dos:: DOS driver +* dX-fullscreen:: directX fullscreen driver +* dX-window:: directX windowed driver +* ggi:: GGI driver +* plan9:: plan9 driver +* SVGAlib:: SVGAlib driver +* win32:: Win32 driver +* X11:: X11 driver +@end menu + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node aa, BeOS , ,drivers + +@section AA-lib driver + +The AA driver is currently the most advanced and portable driver for XaoS. +It is based on AAlib---a high quality ASCII-art library developed by the AA-project. +(see @code{http://aa-project.sf.net}) + +It is a fully featured XaoS driver for text mode displays. It supports 256 colors +and the mouse where possible. + +It also has some extended features available from the UI menu: + +@table @strong +@item Attributes +AA-lib may use character attributes to improve image quality. +By default it uses normal, dim and bold characters where possible, +but you can also enable different attributes like reversed or bold font +characters. You may also enable usage of non ansii/reversed characters if +your device supports it. +@item Font +AA-lib uses a bitmap image of the font to prepare the approximation table +used for ASCII art rendering. This bitmap is expected to be same as the one used +by your device. AAlib performs detection where possible however some devices +(like UNIX text terminals or MDA) do not support this. AAlib has few font +images compiled in, so in this case you should try to use one of them to +achieve best results. +@item Inversion +Some devices use inverse video: use this to get correct results on such devices. +@item Dithering mode +Dithering is an way to get more exact color in approximations, by combining +more characters; but this method can produce ugly looking noise on certain images. +Use this menu to disable or tune it. +@item Palette options +By default AA driver uses the XaoS palette to render images, but it quite often +looks ugly on text displays. Here you can choose a special text palette instead. Note that with +filters enabled, the results may be rather ugly. This function is available from +the @emph{palette menu}. +@item Save text screen +The normal save function will generate a PNG image instead of nice +ASCII-art. To save ASCII art use this function instead. It supports many +text file formats like HTML, ANSI, more, etc... It will also ask you for +font and attributes(see above). It is available from the @emph{file +menu}. +@end table + +The AA-lib driver also provides the full set of standard AA-lib's command line +options. You may use them to tune parameters like gamma correction, and so on. +See @code{xaos -help} or the AA-lib documentation for details. + +The AA driver was written by Jan Hubicka, 1997. + +@c ## section aa ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node BeOS, DGA , aa ,drivers + +@section BeOS support + +XaoS has pretty advanced support for BeOS R4. It works on both PowerPC and +Intel platforms, supports multithreading, the clipboard, file dragging, +has native look and feel and can work as an image translator from XaoS files +to images. + +The first version of the BeOS driver was written by Jens Kilian and later +extended by Jan Hubicka. + +@subsection Installation + +You can start the installation script to do everything for you. If you want +something special, read this section. + +In order for XaoS to work you need to keep the executable together with +its data files (@code{help}, @code{examples}, @code{catalogs} and the @code{tutorials} directory) + +When first started, XaoS registers two new mime types called +@code{image/x-xaos-position} for XaoS Position Files and +@code{video/x-xaos-animation} for XaoS Animation Files, +registers icons for them and sets itself as default application. + +@subsection Available display drivers + +XaoS supports following drivers: + +@table @strong +@item BeOS +Standard windowed driver using application server +@item DirectWindow +Driver done using Game Kit's direct window class +@item WindowScreen +Fullscreen driver. +@end table + +By default, XaoS starts in windowed mode and uses the application server for output. +You could change the driver to DirectWindow to use direct access to video RAM. +Note that this mode is slower in most cases, and not supported by some videocards. + +The BeOS driver by default chooses the most similar bitmap supported by XaoS +to achieve best and fastest results. +In the UI menu you can change this default choice to another one if you wish. +Also you can ask the BeOS and DirectWindow to resize to fullscreen mode. + +XaoS also supports real fullscreen mode using the BWindowScreen API. To switch +XaoS to this driver, use the UI menu. If you want to use this mode by default, +use the @code{-driver WindowScreen} command line option. + +This driver differs a lot from windowed ones. It use direct access to the video +card, allowing you to change video mode. Also, the 256 color mode +can access the palette, so it is not dithered like the windowed mode. +Because BeOS can't do GUI in fullscreen mode, XaoS uses its own toolkit. +I hope you will feel confortable in it. + +@subsection XaoS as translator + +You should be able to open XaoS files in graphics applications +such as ShowImage or ArtPaing. In Preferences you can find the DataTranslations +program, that can be used to set the size, type and DPI of the resulting image. +Also antialiasing can be enabled. + +Note that @emph{translation can take a while}. So be patient and +wait for the result. + +If the translator doesn't work, ensure that you have a link to the XaoS executable +in @code{/boot/beos/system/add-ons/Translators/}. + +@c ## section BeOS ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node DGA, dos , BeOS ,drivers + +@section DGA driver +This is the driver for DGA (Direct Graphics Architecture) extension used by +XFree86 X servers. It is pretty new so it could be buggy. + +Bugs/limitations: + +@table @strong +@item In 8bpp mode, XaoS has problems with the palette with certain window managers +I don't know why this happens. Just let me know what's wrong, or use another +window manager. +@item Banked modes are not supported. +I don't have any card to test this with, so it doesn't work in the current version. +@end table + +DGA driver was written by Jan Hubicka, 1999. + + +@c ## section DGA ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node dos, dX-fullscreen , DGA ,drivers + +@section DOS driver +This is a fully featured driver for DJGPP and allegro. +It supports many VGA modes, VESA 1.0---3.0, VBE/AF, S3 and some other cards. + +The following problems may occur: + +@table @strong +@item Some DPMI servers may cause problems +Some DPMI servers like the one from Novell/Dr/Open DOS are buggy. Use clean DOS +instead and XaoS will automatically start @code{cwsdpmi}. +Under Open Dr DOS use @code{dpmi off} at command line to disable it. +@item Higher resolutions don't work +If your videocard has enough memory for the selected resolution, +you most probably have an unsupported videocard. +Please use a VESA BIOS extension on this videocard. (See the note about VESA +at the end of this section.) +@item XaoS needs a coprocessor +I don't distribute a coprocessor library linked into XaoS because it is too slow for +a real-time zoomer. Coprocessor emulation will not help, because xaos works in protected mode. +@item XaoS needs mouse driver to be usable +@item XaoS works slowly in higher resolution +This could also be caused by Allegro's slow driver or your videocard's VESA BIOS. +You could try some other VESA BIOS extension instead. +Look at the @code{http://www.talula.demon.co.uk} for the FreeBE +project or Scitech Display Doctor package. +(See the note about VESA at the end of this section.) +@end table +@subsection VESA +VESA is a standard for using higher resolutions in DOS. Many videocards have +VESA support in the BIOS so you don't need any additional software, while others +need support from a special program. Also some VESA BIOS implementations are +buggy or suboptimal; there are 3 different versions, version 1.0 is many times +slower than 2.0, which has support for protected mode and linear framebuffers. +So if you have problems with higher resolutions, or some graphics modes are +not available (like 320x200 truecolor), you might try some software package +which emulates VESA. + +The most famous VESA emulating program is Scitech Display Doctor. It has support +for many videocards and is quite reliable. It's disadvantage is that it is +shareware and works for only 30 days. You might also look on +@code{ftp.simtel.net}, where there are many VESA emulation packages such as +@code{s3vbe} or the new FreeBe project at +@code{http://www.talula.demon.co.uk} + +DOS driver was written by Jan Hubicka, 1997. + +@c ## section dos ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node dX-fullscreen, dX-window , dos ,drivers + +@section DirectX fullscreen driver +This is da river for Windows 9x and NT. It is new since version 3.1 and +because of some oddities of Windows API and kludges in DirectX +it may be rather unstable. Please report all bugs. In case +of problems you could use the DOS version of XaoS instead. + +This driver allows the Windows port of XaoS to run in full screen mode. +The driver supports 256, 65536 and 16777216 color modes (24bpp and 32bpp) +in all resolutions supported by DirectX. +You can change graphics mode by pressing the @code{=} key +(or by using the UI/Resize menu). If the selected mode is not supported, +the driver will restore the previous setting. + +Use the @code{-mode WIDTHxHEIGHTxDEPTH} (like @code{-mode 640x480x16}) +command line option to change graphics mode. + +If you want to start XaoS in DirectX, use the @code{-driver dX-fullscreen} +option. + +See the Win32 driver documentation for some more Windows +releated information. + +DirectX driver was written by Jan Hubicka, Jan Olderdissen +and Pavel Tzekov, 1999. + +@c ## section dX-fullscreen ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node dX-window, ggi , dX-fullscreen ,drivers +@c ## section DX-window ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node ggi, plan9, dX-window ,drivers + +@section GGI driver + +GGI stands for General Graphics Interface. Part of this project is to develop +libggi, a portable graphics library, and XaoS's GGI driver uses that. +It is experimental, since the API of libggi is not stabilized yet. +There are some problems with keyboard handling---the shift key doesn't work +yet. + +Everything else might work well, but there are no guarantees. It is alpha quality +software. + +GGI driver was written by Jan Hubicka, 1998. + +@c ## section ggi ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node plan9, SVGAlib, ggi ,drivers + +@section Plan9 driver + +Plan9 is a very nice small operating system by the authors of Unix at Bell Labs. +It is very incompatible with other operating systems; even the C compiler and +header files are different, but XaoS should work well there (even on the +limited free demo installation without any POSIX compatibility stuff) + +There are a few limitations: the file selector and image saving don't work. +You can save position files and then later render them on the other OS, or save +screenshots. + +Plan9 terminals also don't provide any way to catch the arrow keys, so you +can't use them. Use the mouse to navigate in the menus. Also, getting the screen +resolution is impossible, so use @code{-pixelwidth} and @code{-pixelheight} +instead of @code{-screenwidth} and @code{-screenheight}. + +By default XaoS changes the colormap. This will collide with other colorful +programs like Mortha. You can disable this behavior using +@code{-nopalette} switch, but this will slow down XaoS. + +Plan9 driver was written by Jan Hubicka, 1997. + +@c ## section plan9 ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node SVGAlib, win32, plan9 ,drivers + +@section SVGAlib driver + +This is a driver for Linux SVGAlib. I really like this driver, because +I much prefer full screen zooming instead of a small 320x320 window in X11. +It was one of the first drivers for XaoS and is fully featured. +The following problems can occur: + +@table @strong +@item XaoS doesn't initialize graphics mode +when started under users other than root SVGAlib requires root privileges +to directly access the hardware. When you really want to start XaoS as a +normal user, enable the suid bit (@code{chmod +s}) at XaoS executable. +note that I take care to disable all security holes caused by this +bit so I believe it is safe. +@item Mouse doesn't work +@item Screen is blank at higher resolutions +Both this problems are probably caused by misconfiguration of +SVGAlib. Please configure it in @code{etc/vga/libvga.cong} or +@code{/usr/local/lib/libvga.conf} +GPM can also cause problems. Try to kill it before starting XaoS. +@item When I switch console I can't switch back +This is another typical SVGAlib bug. Try to hold @code{F} key longer than @code{alt}. +It helps on my computer. On older SVGAlib there was a famous ``enter bug'' that caused +a crash after pressing enter. Try to update to a newer release. +@end table + +SVGAlib driver was written by Jan Hubicka, 1997. + +@c ## section SVGAlib ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node win32, X11, SVGAlib ,drivers + +@section Win32 driver + +This is a driver for Windows 9x and NT. It is new since version 3.1 and +because of some oddities of Windows API it may be rather unstable. +Please report all bugs. In case of problems you could use the DOS version +of XaoS instead. + +The driver should work in all bit depths, but 16 color mode is not natively +supported by the XaoS engine. XaoS internally works in 32k colors and +the result is converted to 16 colors by Windows. Because Windows +conversion routines are slow and ugly, the result is slow and ugly. +Please configure your display to another bit depth to ``solve'' +this problem. + +Use @code{-size WIDTHxHEIGHT} command line option to change the default +window size. + +This driver also maps to native Windows look and feel. There is a small +problem with combo boxes in dialogs. They are expected to give you a choice +between a few strings. The keyboard controls (changing choice by arrow keys) +work, but mouse selection is broken. If you know how to solve this bug, +please let me know. + +XaoS is a UNIX application and has many command line options. +Some features are not available from the GUI. +Because Windows applications can't have normal output, +most of the critical messages are displayed in message boxes, but +some longer messages are omitted. The most significant omission is the help +about command line options that you can find in @code{doc/cmdopts.txt}. + +One thing that might be confusing is that animation rendering mode doesn't +display anything, but only renders images. Start the rendering, +and a message box will inform you that XaoS is entering the calculation +loop. Relax and wait for the message box signaling the end of the loop. + +Note that XaoS also supports the DirectX API. + +Win32 driver was written by Jan Hubicka, Jan Olderdissen and Pavel Tzekov, 1999. + + +@c ## section win32 ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node X11, , win32 ,drivers + +@section X11 driver +This was the first driver done for XaoS. It supports many visuals, shared +colormaps and MitSHM extension. + +Bugs/limitations: + +@table @strong +@item XaoS makes some X servers too busy +Sometimes XaoS generates images faster than X can display them. +In this case XaoS responds poorly to the mouse, and other applications slow +down too. This happens especially often on old R4 servers. Use @code{-sync} +to avoid this problem. Note that @code{-sync} does @code{not} make all +communication with X asynchronous; it just adds one additional XSync call. +So the slowdown is not as large as you might expect. +@item Does not work on all visuals +This driver supports only 8bpp pseudocolor/grayscales, 15,16,24 and 32bpp truecolor, 1bpp and 8bpp staticolor visuals. +@item Palette rotating does not work for 8bpp pseudocolor w/o private palette +@end table + +X11 driver was written by Jan Hubicka and Thomas Marsh, 1997. + +@c ## section X11 ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node menus, about, drivers,Top + +@appendix Menus, functions and command line parameters +All XaoS functions are referenced by a central function registry. The +scripting language, menus, dialogs and command line options are built +from this database. This section contains information about all functions +available in this registry. +@menu +* root:: Root menu +* animroot:: Animation root menu +* plc:: Replay only commands + +* linemenu:: Line drawing functions +* animf:: Animation functions +* time:: Timing functions +* file:: File +* edit:: Edit +* fractal:: Fractal +* calc:: Calculation +* mfilter:: Filters +* ui:: UI +* misc:: Misc +* helpmenu:: Help +* xtextpos:: Horizontal text position +* ytextpos:: Vertical text position +* mformula:: Formulae +* palettemenu:: Palette +@end menu +@node root, animroot, , menus + + + +@node animroot, plc, root, menus + + + +@appendixsec Animation root menu +This menu is displayed at the top of the screen when animation replay is active. +@menu +* file:: File +* stopreplay:: Stop replay +* helpmenu:: Help +* ui:: UI +@end menu +@node stopreplay, , , animroot + + +@appendixsubsec Stop replay +Terminate animation replay. + +@emph{Available as}: menu item + + + +@node plc, linemenu, animroot, menus + + +@appendixsec Replay only commands +Some commands, such as timing primitives or animation functions, are available +only in animation files. +@menu +* linemenu:: Line drawing functions +* animf:: Animation functions +* time:: Timing functions +* load:: Include file +@end menu +@node load, , , plc + + + + +@appendixsubsec Include file +@defun load file +@end defun + +This function lets you include another file in your script. It works similarly +to @code{#include} in C or @code{load} in Scheme. +The file is searched for in the same directory as the current source file. + +@emph{Available as}: command + +@node linemenu, animf, plc, menus + + + +@appendixsec Line drawing functions +XaoS has support for drawing lines. These functions are available only in +animations and could be used to show some parts of fractals or draw simple +diagrams. See the tutorial ``Introduction to fractals'' +for examples of this feature. + +Lines can be drawn in @emph{screen} coordinates, where 0,0 +is the top left corner and 1,1 is bottom right, @emph{scaled} +coordinates, which are similar, but scaled to keep 0,0---1,1 rectangular, +or @emph{Fractal} coordinates, to draw a line at an exact position +on the screen. + +The color of the line should be specified by the @code{color} command. +You might draw an arbitrary number of lines and, later, morph them. Each line is +identified by a unique numeric key; the current key can be set using @code{linekey}. +Commands for changing lines operate on the line with the current key. +(Lines drawn in sequence have consecutive numbers.) + +For example: + + +@example +(color 'red) +(line 'scaled 0.3 0.5 0.7 0.5) +(line 'scaled 0.3 0.5 0.7 0.5) +(line 'scaled 0.3 0.5 0.3 0.5) +(line 'scaled 0.7 0.5 0.7 0.5) +(linekey 0) +(morphline 'scaled 0.3 0.3 0.7 0.3) +(morphline 'scaled 0.3 0.7 0.7 0.7) +(morphline 'scaled 0.3 0.3 0.3 0.7) +(morphline 'scaled 0.7 0.3 0.7 0.7) +(usleep 1000000) +@end example + + +Creates line morphing to rectangle. + + + + +@defun line keyword complex complex +@end defun + +Draw line between two points. +@code{keyword} specifies type of coordinates and should be one of the +following: @code{`fractal}, @code{`screen} or @code{`scaled}. +This function also increases the line key. + +@emph{Available as}: command + + + + + +@defun morphline keyword complex complex +@end defun + +Morph current line to given coordinates. +@code{keyword} specifies type of coordinates and should be one of the +following: @code{`fractal}, @code{`screen} or @code{`scaled}. +The line will start moving at the next timing command, and reach the +final position before the end of it. +This function also increases the line key. + +@emph{Available as}: command + + + + + +@defun morphlastline keyword complex complex +@end defun + +This function has the same functionality as morphline, but it doesn't +increase the line key, and touches the line with the previous key. This is useful when +you want to move a just-drawn line---you don't need to set linekey back. + +@emph{Available as}: command + + + +@defun linekey integer +@end defun + +Set current line key. + +@emph{Available as}: command + + + +@defun clearline +@end defun + +Clear current line. This function also increases the line key. + +@emph{Available as}: command + +@defun clearlines +@end defun + +Clear all displayed lines. Lines can also be cleared using the +@code{clearscreen} or @code{display} commands available from the Misc menu. @xref{misc}. + +@emph{Available as}: command + +@node animf, time, linemenu, menus + + + +@appendixsec Animation functions +These functions are used to animate fractal state---to zoom, unzoom and morph +various parameters. They should be used only in animation files. +Animations are usually performed for a time selected by an immediately following +timing function. @xref{time}. +For example: + + +@example +(view 0 0 1 1) +(morphview 0 0 2 2) +(usleep 5000000) +@end example + + +Will do a 5 second long unzooming animation. +@menu +* animateview:: Animate view +* smoothmorph:: Smooth morphing +* morphview:: Morph view +* morphjulia:: Morph julia +* moveview:: Move view +* morphangle:: Morph angle +* zoom:: Zooming functions +@end menu +@node animateview, smoothmorph, , animf + + +@appendixsubsec Animate view +@defun animateview float float float float +@end defun + +This function is almost identical to function @code{view}. @xref{uiview}. +It expects that the view will be changed only slightly, so recalculation is done +with @code{ANIMATE} priority. This means that dynamic resolution is used by +default. + +Viewport is selected by the center and two radiuses (real and imaginary). See +@code{view} for more information. + +@emph{Available as}: command + +@node smoothmorph, morphview, animateview, animf + + +@appendixsubsec Smooth Morphing +@defun morphview keystring starttime endtime +@end defun +This function lets you smoothly start and stop morphing. Specify +starttime and stoptime as nonzero, and morphing will speed up and slow down for +that number of usecs. + +The keystring is used to select what morphing you want to control. It is one of +the following: +@table @strong +@item 'view +control morphview +@item 'angle +control morphangle +@item 'julia +control morphjulia +@item 'line +control morphline +@end table +@node morphview, morphjulia, smoothmorph, animf + + +@appendixsubsec Morph view +@defun morphview float float float float +@end defun +For the time selected by the next @code{usleep} or other timing function, the viewpoint is smoothly morphed from +the current one to that selected by @code{morphview}. + +Viewport is selected by the center and two radiuses (real and imaginary). See +@code{view} for more information. + +This function can easily be used for creating zooming/unzooming animations using position files. +This is an example position file generated by XaoS: + + +@example +(initstate) +(defaultpalette 0) +(formula 'mandel) +(view -1.64128273713 -5.50393226816E-05 9.69332308848E-08 +9.69332308834E-08) +@end example + + +By replacing the @code{view} command with @code{morphview} and +adding @code{usleep} you can create a zooming animation: + + +@example +(initstate) +(defaultpalette 0) +(formula 'mandel) +(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 +9.69332308834E-08) +(usleep 10000000) +@end example + + + + +@emph{Available as}: command + +@node morphjulia, moveview, morphview, animf + + +@appendixsubsec Morph Julia +@defun morphjulia complex +@end defun +For the time selected by the next @code{usleep} or other timing function, the Julia seed +is smoothly interpolated from the current one to that selected by @code{morphjulia}. By default this will +cause recalculation of the whole screen. +To avoid this, use fast Julia mode. @xref{fastjulia}. + +A simple animation morphing Julia seed in the X axis: + + +@example +(initstate) +(fastjulia #t) +(juliaseed -2 0) +(morphjulia 2 0) +(usleep 2000000) +@end example + + + +@emph{Available as}: command + +@node moveview, morphangle, morphjulia, animf + + +@appendixsubsec Move view +@defun moveview complex +@end defun +Smoothly move the image center to another position. + +@emph{Available as}: command + +@node morphangle, zoom, moveview, animf + + +@appendixsubsec Morph angle +@defun morphangle float +@end defun +Smoothly rotate the image to another angle. By default rotation causes +recalculation of the whole screen. To avoid this you need to enable +fast rotate mode. @xref{rotate}. Don't forget to disable it later, since +it slows down other animations. + + +A simple ``rotozooming'' animation: + + +@example +(initstate) +(fastrotate #t) +(morphview -1.64128273713 -5.50393226816E-05 9.69332308848E-08 +9.69332308834E-08) +(morphangle 300) +(usleep 10000000) +(wait) +(fastrotate #f) +@end example + + +@emph{Available as}: command + +@node zoom, , morphangle, animf + + +@appendixsubsec Zooming functions + +The functions for zooming/unzooming were created mainly for recording +animations. In manually created animation files, it is easier to use +@code{morphview}. @xref{morphview}. + +@defun zoomcenter complex +@end defun +This function sets the center to zoom in on. The center is given as a position +in fractal coordinates. + +@emph{Available as}: command +@defun zoom +@end defun +Start zooming to the area specified by @code{zoomcenter}. + +The speed of zooming should be controlled by the function @code{speed} +or in a more exact way by @code{maxstep} and @code{speedup}. + +@defun unzoom +@end defun + +Start unzooming from the area specified by @code{zoomcenter}. + +@emph{Available as}: command +@defun stop +@end defun +Stop zooming or unzooming. + +@emph{Available as}: command + +@node time, file, animf, menus + + + +@appendixsec Timing functions +Timing functions are used to control the animation replay daemon. It can wait +for a given time, or wait until calculation is complete. The animation functions +are controlled by such waiting; animations that are running while delays start +keep running through the delay. +@menu +* usleep:: Usleep +* textsleep:: Wait for text +* wait:: Wait for complete image +@end menu +@node usleep, textsleep, , time + + +@appendixsubsec Usleep +@defun usleep integer +@end defun + +This function waits for a given amount of time (in usec) before processing +the next command. The screen is recalculated and displayed at the beginning of +usleep if necessary necessary. The remaining time is spent in waiting or +performing animation. + +@emph{Available as}: command + +@node textsleep, wait, usleep, time + + +@appendixsubsec Wait for text +@defun textsleep +@end defun + + +This function's behavior is very similar to @code{usleep}, +but the time is calculated from the number of letters currently displayed +onscreen. If you want to wait just long enough for the user to read the subtitle, +use this function. The user can alter the replay speed as desired using +@code{letterspersec}. @xref{letterspersec}. This value can be changed during +replay with the arrow keys. + +@emph{Available as}: command + +@node wait, , textsleep, time + + +@appendixsubsec Wait for complete image +@defun wait +@end defun + +Wait until the image is complete. You should always use this function after +zooming or unzooming when dynamic resolution is in use. This ensures that +the image calculation will be complete so the user can see the result before +the animation continues. It may also be useful in combination with filters like +motion blur. @xref{blur}. + +This function deadlocks if used with animation functions; don't +do that. + +@emph{Available as}: command + +@node file, edit, time, menus + + + +@appendixsec File +@menu +* loadpos:: Load +* savepos:: Save +* record:: Record +* play:: Replay +* saveimg:: Save image +* loadexample:: Load random example +* savecfg:: Save configuration +* quit:: Quit +@end menu +@node loadpos, savepos, , file + + +@appendixsubsec Load XaoS position file + +Load a XaoS position file (@code{*.xpf}). +See the format description for more information. + +@emph{Available as}: menu item, command line option + +@node savepos, record, loadpos, file + + +@appendixsubsec Save XaoS position file +@defun savepos file +@end defun + +Save current state to a XaoS position file (@code{*.xpf}). This file is +human-readable, and can easily be improved by hand after saving, or used as +a base for animations. +See the format description for more information. + +@emph{Available as}: menu item, command line option, command + +@node record, play, savepos, file + + +@appendixsubsec Record animation +@defun record bool [ file ] +@end defun + + +e +Toggle recording to a XaoS animation file (@code{*.xaf}). This file is +human-readable, and can easily be improved by hand after recording. +See the format description for more information. + +From the scripting language, @code{(record #t)} enables recording, and +@code{(record #f)} disables it. + +@emph{Available as}: menu item, command line option, command + +@node play, saveimg, record, file + + +@appendixsubsec Replay animation + +Replay a XaoS animation file (@code{.xaf}). + +@emph{Available as}: menu item, command line option + +@node saveimg, loadexample, play, file + + +@appendixsubsec Save image +@defun saveimg file +@end defun + +Save current state to an image file. This file is in @code{.png} (portable +network graphics) format, which can be read by many applications varying from +graphics programs all the way to Web browsers. + +This function needs an external library called @code{libpng}. If the library +wasn't available during compilation, this function is unavailable too. +Please see @code{INSTALL} for more information about obtaining libpng +and recompiling XaoS. + +@emph{Available as}: menu item, command line option, command + +@node loadexample, savecfg, saveimg, file + + +@appendixsubsec Load random example +@defun loadexample +@end defun + +Choose random @code{.xpf} file from the @code{examples} directory and +load it. +You might use it as the starting point for next exploration. + +@emph{Available as}: menu item, command line option, command + +@node savecfg, quit, loadexample, file + + +@appendixsubsec Save configuration +@defun savecfg +@end defun + +Save current configuration to @code{~/.xaosrc} (under Unix) or @code{xaos.cfg} +(under DOS and Windows). XaoS automatically reloads the configuration from this +file when it starts. + +@emph{Available as}: menu item, command line option, command + +@node quit, , savecfg, file + + +@appendixsubsec Quit +@defun quit +@end defun + +Quit XaoS. + +@emph{Available as}: menu item, command line option, command + +@node edit, fractal, file, menus + + +@appendixsec Edit +A fairly ordinary Edit menu. +@menu +* undo:: Undo +* redo:: Redo +* copy:: Copy +* paste:: Paste +@end menu +@node undo, redo, , edit + + +@appendixsubsec Undo +Undo last operation. `Last operation' is quite hard to define in +XaoS (where changes are continuous), so it might be surprising. +I hope it will do what you want. + +@emph{Available as}: menu item +@node redo, copy, undo, edit + + +@appendixsubsec Redo +Redo last undone operation. See undo. @xref{undo}. + +@emph{Available as}: menu item +@node copy, paste, redo, edit + + +@appendixsubsec Copy +Copy fractal to clipboard. This is a platform-dependent operation that may +not have an analogue on your platform (e.g. there is no concept of a clipboard +under aalib). + +@emph{Available as}: menu item +@node paste, , copy, edit + + +@appendixsubsec Paste +Paste fractal from clipboard. This is a platform-dependent operation that may +not have an analogue on your platform (e.g. there is no concept of a clipboard +under aalib). + +@emph{Available as}: menu item + +@node fractal, calc, edit, menus + + +@appendixsec Fractal +This menu contains all functions related to fractal parameters and display; +you can change things like the formula used, coloring modes, seeds and much +else. + +@menu +* formula:: Formula +* mformula:: formulae +* incoloring:: Incoloring mode +* outcoloring:: Outcoloring mode +* plane:: Plane +* palettemenu:: Palette +* uimandelbrot:: Mandelbrot mode +* uiperturbation:: Perturbation +* uiview:: View +* initstate:: Reset to defaults +* tcolor:: True-color coloring modes +@end menu +@node formula, uimandelbrot, , fractal + + +@appendixsubsec Formula +@defun formula keyword +@end defun + +Set the current fractal formula. @code{keyword} should be one of the +following: +@table @strong +@item 'mandel +Standard Mandelbrot set. @xref{mandel}. +@item 'mandel3 +Mandelbrot set, power 3. @xref{mandel3}. +@item 'mandel4 +Mandelbrot set, power 4. +@item 'mandel5 +Mandelbrot set, power 5. +@item 'mandel6 +Mandelbrot set, power 6. +@item 'newton +Newton's approximation method. @xref{newton}. +@item 'barnsley +First Barnsley's formula. @xref{barnsley}. +@item 'octo +Fractint's octo. @xref{octal}. +@item 'phoenix +Phoenix. @xref{phoenix}. +@item 'magnet +Magnet. @xref{magnet}. +@end table + +@emph{Available as}: command + +@node uimandelbrot, uiperturbation, formula, fractal + + +@appendixsubsec Mandelbrot/Julia mode + +Most fractals rendered by XaoS can be represented as Mandelbrot sets or Julias. +Each point in the Mandelbrot set has its own Julia set. To learn more about +this correspondence, see the tutorial on the Julia set. + +This function switches between Mandelbrot and Julia representations. When +switching to Julia, you need to set the seed---a point selected from the +Mandelbrot set. + +If you run this function from the menu, you are prompted for the Julia seed +as a number. Often, this can be clumsy, and it would be easier to specify a +point with the mouse pointer. If you hit the @code{M} key instead of +using the menu, the current mouse position is used. + +Good seedpoints lie at the boundaries of the Mandelbrot set; other seeds +usually generate quite a boring fractal. You can also explore various seeds +at high speed using the Fast Julia mode. @xref{fastjulia}. + +Not all fractals have Julias, but XaoS can generate fake Julia sets for +those that do not, which use some Julia-like modification of the formula; +so this function is currently usable for all fractal types. + +@emph{Available as}: menu item +@defun julia bool +@end defun + +This function is used to enable/disable julia mode in animation files. + +@emph{Available as}: command line option, command +@defun juliaseed complex +@end defun + +Select the current julia seed. + +@emph{Available as}: command line option, command + +@node uiperturbation, uiview, uimandelbrot, fractal + + +@appendixsubsec Perturbation + +Perturbation is a simple trick which changes the point at which orbits start. +Traditionally zero is used, but other values can generate interesting +results too. + +On enabling this function from the menu, you will be asked for a complex +number specifying the perturbation. It is a toggle; selecting it again +resets the perturbation to zero without prompting. + +It can be used to specify a complex number representing a point on the screen. +If you hit the @code{B} key instead of using the menu, the current mouse +position is used. This too is a toggle, so @code{B} again will disable +perturbation by setting it to zero. + +This function only has an effect for certain formulae (like the +Mandelbrot set) and only then in Mandelbrot mode. @xref{mandel}. + +@emph{Available as}: menu item +@defun perturbation complex +@end defun + +This is the scripting-language variation of the perturbation function. Instead +of toggling, you always specify the perturbation to use. Use 0 0 to disable +perturbation. + +@emph{Available as}: command line option, command + +@node bailout, fastjulia, maxiter, calc + + +@appendixsubsec Bailout + +Bailout is the value which is checked for each point of +the orbit if the point is far enough +from the complex zero point in the current iteration. +If the point is far enough, then the iteration immediately +stops and the starting point on the screen will be +painted with a given colour, depending on the fractal +type and many other settings. + +For the Mandelbrot set +this value is 4. Other fractal types usually +have the same bailout value. For most fractals many bailout values +give more or less similar output. E.g., for the second order +Mandelbrot set one can prove that the sequence |z| (z:=z^2+c) tends to +infinity if and only if |z|>2 for some element z of this sequence. +In XaoS program, Bailout value is the square of this 2, i.e. you can change this +to any value greater than 2 for similar results. + +Other fractal types may use other bailout values. The default +is 4 for each types. + +@emph{Available as}: menu item, command line option, command +@defun bailout float +@end defun + + +@node uiview, initstate, uiperturbation, fractal + + +@appendixsubsec View + +Set your current viewpoint in the fractal. This function is useful when you have +found some interesting coordinates somewhere (on a web page, perhaps) and you +want to see that position in XaoS. + +In the dialog you will be asked for the @emph{center}, @emph{radius} +and @emph{angle} of the image. + +The center specifies the point which is displayed at the center of the screen. +The radius is the radius of a circle around this point; XaoS will size the image +so that this circle only just fits on the screen. The angle gives the rotation of +the image in degrees. + +People specify fractal coordinates in many ways. Some people use the coordinates +of the upper-left and lower-right visible points, specifying the coordinates as four +numbers @math{x1}, @math{y1}, @math{x2}, @math{y2}. +To set the same viewpoint in XaoS, set the real portion of the center to +@math{(x1+x2)/2}, the imaginary part of center to @math{(y1+y2)/2}, and +the radius to the greater of @math{x2-x1} and @math{y2-y1}. + +Other programs use a zoom factor instead of a radius. For these, you can set the +radius to @math{2/zoom}. + +@emph{Available as}: menu item +@defun view float float float float +@end defun + +This function is used to set the visible area of fractal in animation files. +It doesn't let let you specify the angle, (for that, see the separate function +@code{angle}), but lets you specify an ellipse instead of a circle. You can +specify both a real and an imaginary radius, so you have better control over the +area that will be visible. XaoS will size the image so that the ellipse only just +fits on the screen. + +@emph{Available as}: command line option, command +@defun angle float +@end defun + +Set the rotation angle in degrees. By default this causes recalculation of the +screen. You can enable the fast rotation mode, which lets you +rotate the screen without recalculation; but it slows down other things, so +don't forget to disable it later. + +@emph{Available as}: command line option, command + +@node initstate, plane, uiview, fractal + + +@appendixsubsec Reset to defaults +@defun initstate +@end defun + +This function resets most of XaoS's values to their defaults. It is useful when +you get lost and want to start from the beginning. It should also be used +as the first command of every animation file, to ensure that the file is always +played with the same settings in effect. + +@emph{Available as}: menu item, command line option, command + +@node plane, incoloring, initstate, fractal + + +@appendixsubsec Plane +@defun plane integer +@end defun + +All fractals displayed by XaoS are functions with a complex parameter. +They can be be displayed in the normal complex plane where the @code{x} +coordinate is the real part of the number and the @code{y} is imaginary; +but they can also be displayed differently: +@table @strong +@item @math{mu} +Normal complex plane (default) +@item @math{1/mu} +Inversion---infinity is at 0 and +0 is at infinity. +@item @math{1/(mu+0.25)} +Similar to inversion, but moves +the center outside the Mandelbrot set, +so it looks parabolic. +@item @math{lambda plane}, @math{1/lambda}, @math{1/lambda-1} +Lambda plane and its inversion, and with a different center. +@item @math{1/(mu-1.40115)} +A very interesting mode for the +Mandelbrot set, this makes small +things large, for easier browsing +of the set's details. +@end table +The tutorial about planes has some examples. + + + +In the scripting language, the planes are numbered as follows: + +@table @strong +@item 0 +@math{mu} +@item 1 +@math{1/mu} +@item 2 +@math{1/(mu+0.25)} +@item 3 +@math{lambda} +@item 4 +@math{1/lambda} +@item 5 +@math{1/(lambda-1)} +@item 6 +@math{1/(mu-1.40115)} +@end table + +@emph{Available as}: command line option, command + +@node incoloring, outcoloring, plane, fractal + + +@appendixsubsec Inside coloring mode +@defun incoloring integer +@end defun + +Areas inside the set are usually filled in black, but this is only a convention; +you could color them in differently to make the fractal look more interesting. +The only method available to make areas inside the set visible is to display +the value of the latest orbit as the value of each pixel. + +The tutorial on incoloring has more information and +examples. + +XaoS has many different ways to show that value. The cryptic names of the modes +are mathematical formulae, where @emph{real} means the real part of the +latest orbit, and @emph{imag} means the imaginary part. @emph{zmag} +uses the magnitude of the value. The @emph{Decomposition-like} method uses +the angle of the orbit. Also, truecolor incoloring modes are available, that +display one value in each of the red, blue and green color planes (or, for some +modes, in each of the hue, saturation and value planes). + +In the scripting language, the incoloring mode is specified by one of the +following integers: + +@table @strong +@item 0 +@math{0} (default) +@item 1 +@math{zmag} +@item 2 +Decomposition-like +@item 3 +@math{real/imag} +@item 4 +@math{abs(abs(c)-abs(r))} +@item 5 +@math{cos(mag)} +@item 6 +@math{mag*cos(real^2)} +@item 7 +@math{sin(real^2-imag^2)} +@item 8 +@math{atan(real*imag*creal*cimag)} +@item 9 +squares +@item 10 +Truecolor. To set exact parameters for truecolor coloring use the +@code{tcolor} command. +@end table + +@emph{Available as}: command line option, command + +@node outcoloring, tcolor, incoloring, fractal + + +@appendixsubsec Outside coloring mode +@defun outcoloring integer +@end defun + +Outcoloring modes are similar to incoloring modes, but indicate +how to display the areas outside the set instead. As with incoloring modes, the +value of the latest orbit can be used to determine the color of each pixel, but the +default is to use the number of iterations needed for the value at that point to become +recognisably divergent as the color. + +The tutorial on outcoloring has more information and +examples. + +The cryptic names of the modes are mathematical formulae, where @emph{iter} +means the number of iterations required for the value to become recognisably divergent, +@emph{real} means the real part of the latest orbit, and @emph{imag} +means the imaginary part. @emph{binary decomposition} uses a different color +when the imaginary part of the orbit is lower than zero, and @emph{smooth} +attempts to remove stripes and discontinuities. Also, truecolor outcoloring +modes are available, that display one value in each of the red, blue and green color planes +(or, for some modes, in each of the hue, saturation and value planes). + +In the scripting language, the outcoloring mode is specified by one of the following +integers: + +@table @strong +@item 0 +@math{iter} (default) +@item 1 +@math{iter+real} +@item 2 +@math{iter+imag} +@item 3 +@math{iter+real/imag} +@item 4 +@math{iter+real+imag+real/imag} +@item 5 +binary decomposition +@item 6 +biomorphs +@item 7 +potential +@item 8 +color decomposition +@item 9 +smooth +@item 10 +True-color outcoloring mode. To set exact parameters for truecolor coloring use @code{outtcoloring}. @xref{tcolor}. +@end table + +@emph{Available as}: command line option, command + +@node tcolor, , outcoloring, fractal + + +@appendixsubsec Truecolor coloring mode +@defun intcoloring integer +@end defun +@defun outtcoloring integer +@end defun + +Truecolor coloring modes are similar to incolor and +outcolor coloring modes; but instead of using a palette, +they directly calculate the red, green and blue components of the color. +This lets you display more parameters at once, and produces interesting +and often attractive results. On 8bpp displays you need to enable the +palette emulator filter first to see anything, amd the quality +won't be so good, as far fewer colors are available per parameter. + +The tutorial on truecolor coloring modes has more +information and examples. + +The cryptic names of the modes are always three mathematical formulae (one for +each color component), where @emph{real} means the real part of the latest +orbit, and @emph{imag} means the imaginary part. + +To enable inside/outside truecolor coloring mode in the scripting language, +set @code{incoloring}/@code{outcoloring} value to 10 (truecolor coloring +mode) before (or after) calling @code{intcoloring} or @code{outtcoloring}. + +In the scripting language, the coloring mode is specified by one of the following +integers: + +@table @strong +@item 0 +black +@item 1 +@math{re*im} @math{sin(re^2)} angle +@item 2 +@math{sin(re)} @math{sin(im)} @math{sin(square)} +@item 3 +hsv +@item 4 +hsv2 +@item 5 +@math{cos(re^c)} @math{cos(im^2)} @math{cos(square)} +@item 6 +@math{abs(re^2)} @math{abs(im^2)} @math{abs(square)} +@item 7 +@math{re*im} @math{re*re} @math{im*im} +@item 8 +@math{abs(im*cim)} @math{abs(re*cre)} @math{abs(re*cim)} +@item 9 +@math{abs(re*im-csqr)} @math{abs(re^2-csqr)} @math{abs(im^2-csqr)} +@end table + +@emph{Available as}: command line option, command + +@node calc, mfilter, fractal, menus + + + +@appendixsec Calculation +This menu contains functions that control calculation parameters such as +the maximum iteration count and periodicity checking. +@menu +* range:: Solid guessing +* dynamic:: Dynamic resolution +* periodicity:: Periodicity checking +* maxiter:: Iterations +* bailout:: Bailout +* fastjulia:: Fast Julia mode +* dynamic:: Dynamic resolution +* rotate:: Rotation +@end menu +@node range, periodicity, , calc + + +@appendixsubsec Solid guessing range +@defun range integer +@end defun + +XaoS has a solid guessing optimization: if all corners of a rectangle have +the same color, it assumes that the whole rectangle is a solid colored block, +and doesn't calculate points inside the rectangle. This optimization saves +lots of calculation, but sometimes introduces errors. This value alters the +maximum size of the rectangle that can be guessed at one time. The default +value is 3; use 0 to disable the optimization. + +@emph{Available as}: command line option, command + +@node periodicity, maxiter, range, calc + + +@appendixsubsec Periodicity checking +@defun periodicity bool +@end defun + +Periodicity checking is one way to speed up the calculation. Areas inside the +set always need @code{maxiter} iterations to determine that +the point is probably inside the set (while it is rare for areas outside to +need anywhere near that much). Often the orbital trajectory falls into a +periodic, repeating cycle; if that can be detected, the calculation can be +stopped early, as there's no way that the orbit can ever leave the cycle +again (hence it cannot diverge, hence the point must be inside the set). + +Implementating this method efficiently is quite problematic. It slows down +the cases where cycles are not found, because cycle-checking is quite hard work +and has to take place for all points, even those that don't become cyclic. +Because of the inexactness of floating-point calculations, the cycles are +never exact, so you need to use an error value. Higher error values mean that +cycles will be detected sooner, while lower error values increase the +exactness of the calculation. Higher values can introduce serious errors, +especially at the front of the Mandelbrot set. XaoS detects this automatically +and corrects for it in most cases, but sometimes it might be wrong. Also, +other optimizations in XaoS (such as boundary tracing) don't give this method +much of a chance to run, since areas inside the set are usually not +calculated at all. + +That's why the advantages of this optimization are questionable. You should +probably experiment with enabling and disabling it. Sometimes XaoS is faster +with this enabled, sometimes when disabled. Also, this method works only +when incoloring methods are disabled, and only for some +fractal types (some fractal types, e.g. newton, don't have any concept of +an area `inside the set' at all.) + +The tutorial chapter ``Escape time fractals'' has +more information on fractal calculation in XaoS, and there is a lengthy +section in the hacker's manual (@code{xaosdev.texinfo}) devoted to the +subject. + +@emph{Available as}: menu item, command line option, command + +@node maxiter, bailout, periodicity, calc + + +@appendixsubsec Iterations +@defun maxiter integer +@end defun + +When the fractal set is calculated, a orbital trajectory is examined for each +point. If the orbit diverges to infinity, the point is outside the set. +Otherwise, the point is inside the set. For exact calculations, you need to +know the entire orbital trajectory, which is infinitely long for areas inside +the set, so fractals cannot be calculated exactly. By default, XaoS calculates +at most 170 positions (iterations) and then gives up; if the point is still +inside the bail-out value, it guesses that the point is inside the set. + +When zoomed into a detailed area, especially one close to the set boundary, +this value could become too low, and the fractal will become boring. +You might try increasing this value if you want to get the image interesting +again; but this necessarily slows down the calculation at the same time. + +The tutorial chapter ``Escape time fractals'' has +more information on fractal calculation in XaoS, and there is a lengthy +section in the hacker's manual (@code{xaosdev.texinfo}) devoted to the +subject. + +@emph{Available as}: menu item, command line option, command + +@node fastjulia, dynamic, bailout, calc + + +@appendixsubsec Fast Julia mode +@defun fastjulia bool +@end defun + +By default, changing the seed for the Julia set requires recalculation of the +image (which is quite slow). It's a nice effect to change the seed smoothly and +show the Julia set morphing as the seed changes. XaoS has a special algorithm +which can calculate such morphings in realtime. It is very inexact, but it is +good enough for a fast preview. + +If you want to select a good seedpoint, enable fast Julia mode and find a +nice place by dragging with the first mouse button depressed; then change to +the Julia mode to see the exact image. + +@emph{Available as}: menu item, command line option, command + +@node dynamic, rotate, fastjulia, calc + + + +@appendixsec Dynamic resolution +@defun fastmode keyword +@end defun + +XaoS performs many optimizations, but fairly often this is not enough. In order +to keep a high framerate, XaoS automatically lowers the resolution of the image, +increasing it when there is time for more calculation. This feature is enabled by +default when animating, but you might also like to enable it for new images +(which makes the image `come into focus' when it is recalculated from scratch for +whatever reason), or disable it completely if you don't like it. + +In the scripting languge, the keyword should be one of the following: +@table @strong +@item @code{'never} +Disable dynamic resolution +@item @code{'animate} +Use only for animations (default) +@item @code{'new} +Use also for new images +@end table +@node rotate, , dynamic, calc + + + +@appendixsec Image rotation + +XaoS has support for rotation of the image to any angle. By default, changing +the angle requires recalculation of the whole screen, but when +@emph{fast rotation mode} is enabled, the angle can be changed smoothly. +In this mode XaoS calculates a larger non-rotated image and rotates it when +needed, so it increases memory requirements and slows XaoS down; hence, it +should be disabled when rotation is not being used. + +The user interface provides two rotation modes---@emph{rotate by +mouse} which allows the angle to be changed by dragging with the first +mouse button depressed, and @emph{continuous rotation mode}, where the image +is rotated clockwise continuously, and the arrow keys can be used to change +the rotiation speed. +@defun fastrotate bool +@end defun + +This function is used to enable and disable fast rotation mode. +@emph{Available as}: command line option, command +@appendixsubsec Automatic rotation +@defun autorotate bool +@end defun + +Use this function to enable continuous rotation. In the scripting language you +can also use @code{morphangle} to get an outwardly similar +but more controllable effect. +@defun rotationspeed float +@end defun + +Specify the speed of continuous rotation, in degrees per second. +Negative values are allowed and rotate anticlockwise. + +@emph{Available as}: menu item, command line option, command + + + +@node mfilter, ui, calc, menus + + + +@appendixsec Filters +Filters are a post-calculation effect applied to the resulting image. They +can do things like motion blurring, edge detection, emulation of palettes +or truecolor on displays that can't handle them, and such things. There is +a tutorial chapter about them. + +@menu +* filter:: Filter command +* edge:: Edge detection +* edge2:: Edge detection2 +* starfield:: Starfield +* stereogram:: Random dot stereogram +* interlace:: Interlace filter +* blur:: Motion blur +* emboss:: Emboss +* palettef:: Palette emulator +* anti:: Antialiasing +* truecolor:: Truecolor emulator +@end menu +@node filter, edge, , mfilter + + +@appendixsubsec Filter command +@defun filter keyword bool +@end defun + +This command is used to enable or disable filters. @xref{mfilter}. +The @emph{keyword} specifies the filter to change, and should be one of +the following: + +@table @strong +@item @code{'edge} +Edge detection +@item @code{'edge2} +Edge detection2 +@item @code{'starfield} +Starfield +@item @code{'stereogram} +Random dot stereogram +@item @code{'interlace} +Interlace filter +@item @code{'blur} +Motion blur +@item @code{'emboss} +Emboss +@item @code{'palette} +Palette emulator +@item @code{'anti} +Antialiasing +@item @code{'truecolor} +Truecolor +@end table + +@emph{Available as}: command +@node edge, edge2, filter, mfilter + + +@appendixsubsec Edge detection + +This filter is a standard edge detection algorithm; solid areas are filled +in black. Some fractals look very interesting with this filter (and some +areas of some fractals just look like noise). This version of the filter produces +relatively wide lines, so is useful at higher resolutions. The filter +edge detection2 makes thinner lines, for the low resolution modes. + +@emph{Available as}: menu item, command line option + +@node edge2, starfield, edge, mfilter + + +@appendixsubsec Edge detection2 + +This filter is a standard edge detection algorithm; solid areas are filled +in black. Some fractals look very interesting with this filter (and some +areas of some fractals just look like noise). This version of the filter produces +relatively tight lines, so is useful at lower resolutions. The filter +edge detection makes thinner lines, for the high resolution modes. + +@emph{Available as}: menu item, command line option + +@node starfield, stereogram, edge2, mfilter + + +@appendixsubsec Starfield + +The starfield filter generates random stars whose density depends on the +iteration count. Choose your favorite spiral fractal and enable this filter +to get a Grand Design spiral galaxy :) + +@emph{Available as}: menu item, command line option + +@node stereogram, interlace, starfield, mfilter + + +@appendixsubsec Random dot stereogram + +Fractal images are good as a base for random dot stereograms. In +case you don't know what these are, please point your browser to +Google or another search engine and find some articles about such +images, because learning to read such images takes some effort. They +make it possible to generate three dimensional images on a normal monitor +without any additional hardware, by exploiting bugs in the human brain +(although you need two working eyes, and some people never learn to +see them; they can simply ignore this feature). + +XaoS is able to generate these images in animations, so you may use +all normal XaoS functions (except palette changing and palette rotation, +which makes no sense applied to a stereogram). To make the animation yet +more exciting, XaoS emulates ``falling'' into the set; while you zoom in, +your distance from the set drops and drops---but you never hit it; when the +set reaches the level of your monitor, the distance is changed again so +you are far away. + +To make this work right, XaoS needs to know the @emph{exact size of your +monitor}. Because most platforms have no way to determine this, you need to +use @emph{command line options} to tune it. If it's not set or is wrong, +the stereograms will probably be impossible to see (if your monitor is too +big or resolution too low), or the images will seem to be shallow (if your +monitor is too small or resolution too high). + +By default XaoS expects my 15" monitor (29.0cm x 21.5 cm). Another +cause of problems is the virtual screen supported by some windowed +environments (like some X servers) that makes a program think that the +resolution is higher than it actually is, and you see only part of +this extra-large screen. + +The worst thing you could possibly do is to run full-screen XaoS in some +graphical windowing system (OS/2 on top of Windows or Wine on top of Linux, +perhaps) where XaoS can't tell the real size of its window at all. In such +cases, it's normally better (not to mention faster) to run XaoS natively, +rather than under such an emulation layer. + +The following command line options are provided to specify sizes: + +@table @strong +@item @code{-screenwidth}, @code{-screenheight} +Lets you specify the size of your screen in centimeters. Note that +you need to specify the size of the visible image on the monitor, not +the size with edge borders, or the size of the tube. The simplistic +`my monitor is 17", just turn 17" into centimeters' doesn't work; +that 17" is a marketing figure and has only a vague connection to +reality. Get out a ruler and measure it. + +@item @code{-pixelwidth}, @code{-pixelheight} +Lets you specify the exact size of a single pixel, if XaoS cannot +determine this for itself from your screen size. +@end table + +These options are used by some other parts of XaoS as well, so you should +use them even when you don't want to see stereograms. You should probably +write a small starting script (or alias, or shortcut; whatever your environment +uses) that passes the correct parameters to XaoS. + +If the window is @emph{smaller than 8cm in any direction}, you will probably be +unable to see anything; make the window bigger. + +The correct way to see XaoS stereograms is: +@table @strong +@item 1 +Start XaoS with options specifying the exact size of your screen or one pixel on it +@item 2 +Sit 60cm away from monitor +@item 3 +If you use a windowed environment, resize XaoS's window to make it wider than, say, 15 cm. +@item 4 +Enable the filter (by pressing @code{E}) +@item 5 +focus on a point far away from the monitor (try to use your +own reflection, if your monitor's not antireflective); the random blurring should +eventually fall into the pattern of a Mandelbrot set. +@item 6 +Carefully use your mouse to zoom into interesting areas +(it is easy to lose concentration when you are not trained; but you can use +the autopilot...) +@item 7 +Enjoy animation :) +@end table + +If you still can't see the stereograms, it could be that the fractal, or your eye, +is deformed. A deformed fractal can be caused by your specifying your monitor size +wrongly. Visual problems that damage depth perception, as well as problems like +astigmatism, can make it impossible to see stereograms at all. + + +@emph{Available as}: menu item, command line option + +@node interlace, blur, stereogram, mfilter + + +@appendixsubsec Interlace filter + +The interlace filter halves the horizontal resolution, and in each frame alternates +between drawing only the even and only the odd lines. This speeds up the +calculation, and in higher resolutions produces a motion-blur-like effect. + +@emph{Available as}: menu item, command line option + +@node blur, emboss, interlace, mfilter + + +@appendixsubsec Motion blur + +Motion blur mixes the current frame with previous ones to produce a +motion-blur effect. It might be rather slow in 16bpp truecolor modes. The best +results can probably be seen in 8bpp modes, so you might want to enable the +palette filter first. + +@emph{Available as}: menu item, command line option + +@node emboss, palettef, blur, mfilter + + +@appendixsubsec Emboss + +This is a standard emboss filter, as seen in programs such as the GIMP or +Photoshop. It produces especially nice results with the smooth +outcoloring mode. @xref{outcoloring}. + +@emph{Available as}: menu item, command line option + +@node palettef, anti, emboss, mfilter + + +@appendixsubsec Palette emulator + +XaoS can work in either palette or truecolor mode. Both modes +have advantages and disadvantages. Palette mode allows effects such as palette +rotation, while truecolor mode allows smoother incoloring +and outcoloring modes and the +truecolor coloring modes. If your display is truecolor, you +can enable this filter to get palette emulation (albeit not as cheaply as in +a real paletted mode). + +@emph{Available as}: menu item, command line option + +@node anti, truecolor, palettef, mfilter + + +@appendixsubsec Antialiasing + +Antialiasing is a technique to increase image quality by eliminating jagged +edges. XaoS calculates four values for each pixel (on the subpixel boundaries) +and uses the average of them for the pixel value. + +This filter slows XaoS down a @emph{lot} and greatly increases memory +requirements. It is useful mainly when you want to save images and want to make +them look as nice as possible. Antialiasing also helps a lot when you want to +encode JPEG or MPEG files; they are much shorter if antialiased (MPEG and JPEG +hate jagged edges). + +@emph{Available as}: menu item, command line option + +@node truecolor, , anti, mfilter + + +@appendixsubsec Truecolor emulator + +XaoS can work in either palette or truecolor mode. Both modes +have advantages and disadvantages. Palette mode allows effects such as palette +rotation, while truecolor mode allows smoother incoloring +and outcoloring modes and the +truecolor coloring modes. If your display is 8bpp, you can enable +this filter to get truecolor emulation (but, obviously, not with as many colors +as a real truecolor display). + +More information about filters + +@emph{Available as}: menu item, command line option + +@node ui, misc, mfilter, menus + + + +@appendixsec UI + +This menu contains functions to control the user interface layer of XaoS: +zooming speed, the autopilot, realtime status information, and so on. + +@menu +* speed:: Zooming speed +* letterspersec:: Letters per second +* autopilot:: Autopilot +* recalculate:: Recalculate +* interrupt:: Interrupt +* nogui:: Disable XaoS's builtin GUI +* status:: Status +* ministatus:: Ministatus +@end menu +@node speed, letterspersec, , ui + + +@appendixsubsec Zooming speed +@defun speed float +@end defun + +Change zooming speed, where 1 is the default, 2 means twice as fast, and so on. + +@emph{Available as}: menu item, command line option, command + +In the scripting language you can use the following functions for better +control: +@defun maxstep float +@end defun + +Selects the zooming/unzooming speed. The parameter specifies how much of the +range will be removed each twentieth of a second; 0 means nothing, 1 means +everything (the parameter obviously has to be less than 1). +Higher values mean faster zooming. + +@emph{Available as}: command +@defun speedup float +@end defun +When zooming/unzooming, every twentieth of a second the @code{speedup} +value is added to the current step until @code{maxstep} is reached. +So this value selects the rate at which zooming stops and starts. +Both these functions are more for internal use of XaoS then for manually +written scripts, but they could come in useful nonetheless. + +@emph{Available as}: command + +@node letterspersec, autopilot, speed, ui + + +@appendixsubsec Letters per second +@defun letterspersec integer +@end defun + +Speed of subtitles for the @code{textsleep} function. +The user can set this value to suit; it can also be changed with the left and +right arrow keys during animation replay. + +@emph{Available as}: command line option, command + +@node autopilot, recalculate, letterspersec, ui + + +@appendixsubsec Autopilot +@defun autopilot bool +@end defun + +To make XaoS yet more impressive, we made a special autopilot mode that +automatically drives into interesting boundaries of the set; you should +press @code{A}, play your favorite music, drink coffee and relax. I never +tried this but it should be really relaxing! Many pictures in the XaoS +gallery were discovered using the autopilot. + +The autopilot also has some additional features. It backtracks if the +zoomed picture is not interesting anymore, and can detect when it's zoomed +into really a boring part of the fractal or reached the limit of floating +point arithmetic on the platform, and restart zooming from the top. + +@emph{Available as}: menu item, command line option, command + +@node recalculate, interrupt, autopilot, ui + + +@appendixsubsec Recalculate +@defun recalculate +@end defun + +Recalculate current fractal. This should be used when the fractal on the +screen is strange because of error propagation caused by +solid guessing. @xref{range}. + +@emph{Available as}: menu item, command line option, command + +@node interrupt, nogui, recalculate, ui + + +@appendixsubsec Interrupt +@defun interrupt +@end defun + +Interrupt current calculation. + +@emph{Available as}: menu item, command line option, command + + +@node nogui, status, interrupt, ui + + +@appendixsubsec Disable XaoS's builtin GUI +@defun nogui bool +@end defun + +Disable XaoS menus and dialogs. This function should be used by external GUI +programs; these manipulate XaoS via a pipe, so the internal GUI should be +disabled at the same time. See the hacker's manual (@code{xaosdev.texinfo}) +for more details. + +@emph{Available as}: menu item, command line option, command + +@node status, ministatus, nogui, ui + + +@appendixsubsec Status +@defun status bool +@end defun + +Enable/disable status information. This displays some useful information +about the current fractal, such as viewpoint etc. (In low-resolution modes it +also almost completely obscures the current fractal...) + +@emph{Available as}: menu item, command line option, command + +@node ministatus, , status, ui + + +@appendixsubsec Ministatus +@defun ministatus bool +@end defun + +Enable/disable status line. This contains basic information such as how +much you are zoomed and the framerate. + +@emph{Available as}: menu item, command line option, command + +@node misc, helpmenu, ui, menus + + + +@appendixsec Misc +Miscellaneous functions. +@menu +* command:: Command +* renderanim:: Render animation +* clearscreen:: Clear screen +* display:: Display fractal +* text:: Display text +* color:: Color +* xtextpos:: Horizontal text position +* ytextpos:: Vertical text position +* textposition:: Text position +* message:: Message +@end menu +@node command, renderanim, , misc + + +@appendixsubsec Command + +You can invoke all XaoS functions using a simple command language reminiscent +of Scheme. This option lets you run a single command. If you want to run more +than one, you might want to use an XaoS animation file instead; +they are written in the same language. + +@emph{Available as}: menu item + +@node renderanim, clearscreen, command, misc + + +@appendixsubsec Render animation + +Render an animation to image files. See How to encode MPEG files +for more information. + +@emph{Available as}: menu item, +@node clearscreen, display, renderanim, misc + + +@appendixsubsec Clear screen +@defun clearscreen +@end defun + +Clear the screen. To display the fractal again, use @code{display}. @xref{display}. +This function is mainly useful in tutorials and similar animations. + +@emph{Available as}: menu item, command + +@node display, text, clearscreen, misc + + +@appendixsubsec Display fractal +@defun display +@end defun + +Display fractal. This functions reverses the effect of the @code{clearscreen}, +line drawing and text output functions. + +@emph{Available as}: menu item, command + +@node text, color, display, misc + + +@appendixsubsec Display text +@defun text string +@end defun + +Display the given text on the screen. This function is mainly useful in tutorials. +Text should be cleared by printing lots of spaces, or using the +@code{clearscreen} or @code{display} +functions. You might also want to use the @code{textposition} +function to select the part of the screen to display the text on. + +To wait for the user to read the text, you can use the @code{textsleep} +function. + +Example: + + +@example +(clearscreen) +(textposition 'center 'middle) +(text "Welcome into my animation") +(textsleep) +(display) +@end example + + +@emph{Available as}: menu item, command line option, command + +@node color, textposition, text, misc + + +@appendixsubsec Color +@defun color keyword +@end defun + +Change text and line color. @emph{keyword} should be one of @code{'white}, +@code{'black} and @code{'red}. + +@emph{Available as}: menu item, command line option, command + +@node textposition, message, color, misc + + +@appendixsubsec Text position +@defun textposition keyword keyword +@end defun + +Select text position. The first keyword specifies the horizontal +position, the second the vertical position. The horizontal position should be +one of @code{'left}, @code{'center}, and @code{'right}. +The vertical should be one of @code{'top}, @code{'middle}, and @code{'bottom}. + +@emph{Available as}: command line option, command + +@node message, , textposition, misc + + +@appendixsubsec Message +@defun message string +@end defun + +This function is almost identical to the @code{text} function, +except that it uses message catalogs in the @code{catalog} directory to +translate messages into other languages. It should be used only in the multi-lingual +XaoS tutorials. + +@emph{Available as}: command line option, command + +@node helpmenu, xtextpos, misc, menus + + + +@appendixsec Help +This menu contains help and tutorials. + +@node xtextpos, ytextpos, helpmenu, menus + + + +@appendixsec Horizontal text position +Select the horizontal position used to display text. @xref{text}. +It can be placed at the left, in the center or at the right. + +@node ytextpos, mformula, xtextpos, menus + + + +@appendixsec Vertical text position +Select the vertical position used to display text. @xref{text}. It can be +placed at the top, in the middle or at the bottom of the screen. + +@node mformula, palettemenu, ytextpos, menus + + + +@appendixsec formulae + +Each escape time fractal has its own formula. XaoS supports the following +formulae: + +@menu +* mandel:: Mandelbrot +* mandel3:: Mandelbrot^3 +* octal:: Octal +* newton:: Newton +* barnsley:: Barnsley1 +* phoenix:: Phoenix +* magnet:: Magnet +@end menu +@node mandel, mandel3, , mformula + + +@appendixsubsec Mandelbrot + +The Mandelbrot set is the most famous escape time fractal ever. It has the +simple formula @math{z=z^2+c}. See the tutorial chapter. + +@emph{Available as}: menu item, command line option + +@node mandel3, octal, mandel, mformula + + +@appendixsubsec Mandelbrot^3---Mandelbrot^6 and Mandelbrot^9 + +The Mandelbrot^3 fractal is a simple modification of the standard +Mandelbrot set formula, using @math{z=z^3+c} instead of +@math{z=z^2+c}. + +Other derivations of the Mandelbrot set (Mandelbrot^4 and so on) use even +higher powers. See the tutorial chapter. + +@emph{Available as}: menu item, command line option +@node octal, newton, mandel3, mformula + + +@appendixsubsec Octal + +This is a less well-known fractal that Thomas discovered in Fractint. +It has an interesting shape when displayed in the alternative +planes. @xref{plane}. See the tutorial chapter. + +@emph{Available as}: menu item, command line option + +@node newton, barnsley, octal, mformula + + +@appendixsubsec Newton + +This is Newton's approximation method for finding the roots of a polynomial. It +uses the polynomial @math{x^3=1} and counts the number of iterations needed +to reach the approximate value of the root. See the tutorial chapter. + +This fractal doesn't have Julia sets, but XaoS is able to generate Julia-like +sets which are also very interesting (they are sometimes called ``Nova +formulae''). + +@emph{Available as}: menu item, command line option + +@node barnsley, phoenix, newton, mformula + + +@appendixsubsec Barnsley1 + +This is a formula by Michael Barnsley. It produces very nice crystalline Julia +sets. See the tutorial chapter. + +@emph{Available as}: menu item, command line option + +@node phoenix, magnet, barnsley, mformula + + +@appendixsubsec Phoenix + +This formula produces very nice Julia sets. +See the tutorial chapter. + +@emph{Available as}: menu item, command line option + +@node magnet, , phoenix, mformula + + +@appendixsubsec Magnet + +This is a formula that comes from theoretical physics. +It is derived from the study of theoretical lattices in the context of magnetic +renormalization transformations. +See the tutorial chapter. + +@emph{Available as}: menu item, command line option + +@node palettemenu, , mformula, menus + + + +@appendixsec Palette +This menu contains functions to change the palette the fractal is displayed with. +@menu +* defpalette:: Default palette +* randompalette:: Random palette +* palette:: Custom palette +* cycling:: Color cycling +* shiftpalette:: Shift palette +@end menu +@node defpalette, randompalette, , palettemenu + + +@appendixsubsec Default palette +@defun defaultpalette number +@end defun + +Create a default palette. In the scripting language, @code{number} specifies +how much the palette is shifted by. + +Note that changing the palette in truecolor modes forces recalculation of +the whole screen. To avoid this, you can enable the +palette emulation filter first. + +@emph{Available as}: menu item, command line option, command + +@node randompalette, palette, defpalette, palettemenu + + +@appendixsubsec Random palette +@defun randompalette +@end defun + +Create a random palette. XaoS will automatically pick one of its +palette-generation algorithms and create one. + +Note that changing the palette in truecolor modes forces recalculation of +the whole screen. To avoid this, you can enable the +palette emulation filter first. + +@emph{Available as}: menu item, command line option, command + +@node palette, cycling, randompalette, palettemenu + + +@appendixsubsec Custom palette +@defun palette integer integer integer +@end defun + +A custom palette lets you re-create some of the random palettes. The first value +specifies the algorithm, which should currently be one of the following: +@table @strong +@item 0 +Default palette +@item 1 +Black to color gradient +@item 2 +Black to color to white gradient +@item 3 +Cubistic-like algorithm. +@end table +The seed specifies a random seed for the palette; different seeds generate +different palettes. The last value is the amount by which the palette is shifted. + +Note that changing the palette in the truecolor modes forces recalculation of +the whole screen. To avoid this, you can enable the +palette emulation filter first. + +@emph{Available as}: menu item, command line option, command + +@node cycling, shiftpalette, palette, palettemenu + + +@appendixsubsec Color cycling +@defun cycling bool +@end defun + +Color cycling is an old and simple effect to animate fractals. The Mandelbrot +set looks particularly nice when color-cycled. On truecolor displays, color +cycling fails to initialize (since those displays don't have a palette). +You can enable palette emulation filter to make it possible. + +@emph{Available as}: menu item, command line option, command + +In the user interface, colors can also be cycled in the opposite direction +with the ``@emph{Reversed color cycling}'' function. + +To control the cycling speed, you coan use arrow keys or the +``@emph{Color cycling speed}'' function. + +@emph{Available as}: menu item +@defun cyclingspeed integer +@end defun + +The parameter specifies the number of skips per second. It can be negative to +cycle in the opposite direction. + +@emph{Available as}: menu item, command line option, command + +@node shiftpalette, , cycling, palettemenu + + +@appendixsubsec Shift palette +@defun shiftpalette integer +@end defun + +Shift palette by the specified number of cells. This can be used to tune the +palette's position on the fractal. You can also use the +@emph{Shift one forward} and @emph{Shift one backward} functions +for fine-tuning. Note that shifted and rotated palettes could look different on +different displays (because they may have different palette sizes). + +Shifting the palette on truecolor displays causes a recalculation of the screen. +To avoid this, you could use palette emulation filter. @xref{palettef}. + +@emph{Available as}: menu item, command line option, command + + +@c ## menus controls ## +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +@comment node-name, next, previous, up +@node about, support,menus ,Top +@appendix About XaoS +@appendix Credits +(alphabetically) +@table @strong +@item Lucio Henrique de Araujo (lucio.matema@@gmail.com) +Brazilian/Portuguese translation +@item Samuel Bizien (samuel@@bizien.info) +Beryl fractal +@item Eric Courteau (ecourteau@@cplus.fr) +francais.cat (translation of tutorials) +@item Jean-Pierre Demailly (Jean-Pierre.Demailly@@ujf-grenoble.fr) +Updates for French translation +@item Radek Doulik (rodo@@atrey.karlin.mff.cuni.cz) +TK interface, windowid patches +@item Martin Dozsa (madsoft@@centrum.cz) +cs.po (Czech translation of menus) +@item Arpad Fekete (Fekete.Arpad.2@@stud.u-szeged.hu) +Some new fractals, and the 'More formulae' menu +@item Zelia Maria Horta Garcia (zeliagarcia@@seed.pr.gov.br) +Brazilian/Portuguese translation +@item Tim Goodwin (tgoodwin@@cygnus.co.uk) +english.cat corrections +@item Ben Hines +autoconf suggestions, Mac OS X port +@item Jan Hubicka (jh@@ucw.cz) +Zooming routines, ugly interface, palettes, drivers, autopilot, filters, documentation, tutorials etc. +@item Jens Kilian (jjk@@acm.org) +BeOS driver, deutsch.cat +@item Thomas A. K. Kjaer (takjaer@@imv.aau.dk) +OS/2 ports (320x200 graphics and AA-lib) +@item Zoltan Kovacs (kovzol@@math.u-szeged.hu) +Internationalization, Hungarian translations, finalizing version 3.1, bug fixes, web design, current maintainer +@item Zsigmond Kovacs (kovzsi@@gmail.com) +Fractal examples +@item J.B. Langston III (jb-langston@@austin.rr.com) +Native Mac OS X port (from version 3.2.2); web redesign; co-maintainer +@item Andreas Madritsch (amadritsch@@datacomm.ch) +New fractal types, bailout, many fixes +@item Mateusz Malczak (xaos@@malczak.info) +User formula evaluation library +@item Giorgio Marazzi (gmarazzi@@vtr.net) +Improvements and fixes for espanhol.cat +@item Thomas Marsh (thomas.marsh2@@gmail.com) +First zoomer, formulae, planes, X11 driver, inversions, many ideas +@item Dominic Mazzoni (dmazzoni@@cs.cmu.edu) +Macintosh port (version 2.0) +@item David Meleedy +Grammatical and spelling fixed version of @code{xaos.6} +@item Paul Nasca (zynaddsubfx@@yahoo.com) +Ministatus improvement +@item Nix (nix@@esperi.demon.co.uk) +Grammatical and spelling fixed version of @code{xaos.hlp} and other files +@item Terje Pedersen (terjepe@@login.eunet.no) +Amiga port +@item Cesar Perez (oroz@@users.sourceforge.net) +Spanish translations +@item Fabrice Premel (premelfa@@etu.utc.fr) +Periodicity checking +@item Jan Olderdissen (jan@@olderdissen.com) +Win32 port +@item Ilinca Sitaru (ilinca.sitaru@@gmail.com) +Romanian translation +@item Daniel Skarda +Fractal examples +@item Andrew Stone (Stone Design - www.stone.com) +Videator Support, Cocoa improvements, performance mode, bug fixes +@item Marton Torok (marton.torok@@gmail.com) +Small fixes for pipes +@item Pavel Tzekov (paveltz@@csoft.bg) +Win32 support +@item Charles Vidal +Tcl/Tk interface +@item Tapio K. Vocaldo (taps@@rmx.com) +Macintosh port +@item Tormod Volden +Fixes for X11 driver to improve compatability with Xorg, XScreenSaver, Beryl and Compiz +@item Philippe Wautelet (p.wautelet@@fractalzone.be) +Bug fixes for version 3.1.1, French translation, gcc 4.0 fixes +@item Sergio Zanchetta +Italian translation +@end table +@subsection Included Software +XaoS uses the following libraries. These libraries may be included +with some binary distributions of XaoS. + +@emph{gettext 0.17} +Website: @code{http://www.gnu.org/software/gettext/} +Copyright (C) 1995-1997, 2000-2007 Free Software Foundation, Inc. +License GPLv3+: GNU GPL version 3 or later (http://gnu.org/licenses/gpl.html) +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +@emph{GNU Scientific Library 1.11} +Website: @code{http://www.gnu.org/software/gsl/} +Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 The GSL Team. +License GPLv3+: GNU GPL version 3 or later (http://gnu.org/licenses/gpl.html) +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +@emph{libpng 1.2.25} +Website: @code{http://www.libpng.org/pub/png/libpng.html} +Copyright (c) 1998-2008 Glenn Randers-Pehrson +Copyright (c) 1996-1997 Andreas Dilger +Copyright (c) 1995-1996 Guy Eric Schalnat, Group 42, Inc. + +@c ## appendix about ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node support, index ,about ,Top +@appendix Getting Support +XaoS is a community-supported free software project. There are many ways +to get help, all of which are explained below. + +@appendix Home Page +The XaoS homepage is @code{http://xaos.sf.net}. Check here for the +latest news and information about XaoS and to download the latest versions. + + +@subsection Discussion Forums +XaoS has two discussion forums hosted on SourceForge. You can read them +freely, but in order to post, you must to register for a free SourceForge +account. + +@table @strong +@item Help +Provides a place for you to ask for help using XaoS. Other XaoS users +and/or the XaoS developers will answer your questions. + + +@code{http://sourceforge.net/forum/forum.php?forum_id=17768} +@item Open Discussion +Provides a place to discuss anything related to XaoS or fractals. +You can share tips, your own fractal creations, or any other fractal-related +ideas with other XaoS users. + + +@code{http://sourceforge.net/forum/forum.php?forum_id=17767} +@end table + + +We welcome you to join these forums and become involved in the XaoS community. + +@subsection Mailing Lists + +XaoS currently has three mailing lists hosted on SourceForge. Unfortunately, +there is currently very little traffic on any of them. Hopefully in the future, +we can get more XaoS users and developers involved in the mailing lists. +The lists are as follows: + +@table @strong +@item xaos-announce@@lists.sourceforge.net +Low volume list that is used only to announce new releases. + + +Subscribe: @code{http://lists.sourceforge.net/mailman/listinfo/xaos-announce} +Archive: @code{http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-announce} + +@item xaos-devel@@lists.sourceforge.net +Developer mailing list, where the developers coordinate and discuss XaoS development. + + +Subscribe: @code{http://lists.sourceforge.net/mailman/listinfo/xaos-devel} +Archive: @code{http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-devel} + +@item xaos-discuss@@lists.sourceforge.net +General discussion list is for XaoS users to share tips and ideas about XaoS. + + +Subscribe: @code{http://lists.sourceforge.net/mailman/listinfo/xaos-discuss} +Archive: @code{http://sourceforge.net/mailarchive/forum.php?forum_name=xaos-discuss} +@end table + + +Please feel free to join any or all of these mailing lists and share your ideas with the +developers and other XaoS users. + +@subsection Bug Reports +If you think you have found a bug in XaoS, please report it. The developers will do their +best to resolve the bug in a timely manner. + + +Bug Tracker: @code{http://sourceforge.net/tracker/?atid=105771&group_id=5771} + + +Please don't submit duplicate bugs. Browse the existing ones first to make +sure nobody has already reported it. You may add additional information about a bug by +entering a comment on an existing bug. + + +If you are not sure if something is a bug, please open a support request. The developers +will try to answer your question and can convert your support request to a bug if necessary. + + +Support Requests: @code{http://sourceforge.net/tracker/?atid=205771&group_id=5771} + +@subsection Feature Requests +If you have an idea for a great new feature you'd like to see added to XaoS, please let us know about it. +You can submit a feature request via SourceForge, and the XaoS developers will do their best to +implement your request in a future version. + + +Feature Requests: @code{http://sourceforge.net/tracker/?atid=355771&group_id=5771} + + +Please don't submit duplicate feature requests. Browse the existing ones +first to make sure nobody has already requested the feature your want. You may add your +vote for a feature by adding a comment to the existing request. + +@c ## appendix support ## + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@comment node-name, next, previous, up +@node index, ,support ,Top +@unnumbered Index of functions + +@printindex fn + + +@contents +@bye 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 + #include + + .... + + 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_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 -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 diff --git a/doc/xaosdev.texinfo b/doc/xaosdev.texinfo new file mode 100644 index 0000000..49203d8 --- /dev/null +++ b/doc/xaosdev.texinfo @@ -0,0 +1,2842 @@ +\input texinfo @c -*-texinfo-*- + +@c Use A4 paper - If you don't like that, remove the following 3 lines. +@iftex +@afourpaper +@end iftex + +@setfilename xaosdev.info +@settitle A fast real-time interactive fractal zoomer --- hacker's guide +@dircategory Graphics +@direntry +* XaoS: (xaosdev). The fast real-time interactive fractal zoomer + (developers documentation) +@end direntry + + +@ifinfo +@copyright{} 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. + +@end ifinfo + +@c %**end of header + +@set VERSION 3.1.1 +@set DATE Feb 5, 2005 + +@titlepage + +@title XaoS @value{VERSION} +@subtitle A fast real-time fractal zoomer --- hacker's guide + +@author Jan Hubi@v cka +@tex +Dukelsk\'ych bojovn\'\i ku 1944 +@end tex +@* +390 03 T@'abor @* +Czech Republic + +Email: @code{jh@@ucw.cz} + +@value{DATE} + +@page +@vskip 0pt plus 1filll +@vskip 0pt plus 1filll + +@copyright{} 1997 @tex Jan Hubi\v cka +@end tex + +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. + +@end titlepage + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node Top, , (dir), (dir) + +@ifinfo +@top XaoS @value{VERSION} +@flushright 1.0 +A real-time interactive fractal zoomer +Hacker's guide +@value{DATE} +@end flushright + +This manual contains documentation for those who are interested in +studying and improving the XaoS sources or using them in other programs. +It includes a description of the algorithm and documentation of those parts +of XaoS that I think might be useful for others. +@end ifinfo + +@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 +@end menu + +@node design, driver ,Top ,Top +@chapter Overview of the XaoS design + +XaoS is divided into several ``libraries'' (some of them have been merged +together; nonetheless the conceptual divisions are there and they can be +separated easily). + +Understanding the design philosophy should help you to navigate in the sources. +I also expect that much of the lower level stuff may be useful in other +projects, since it is designed to be fairly generic. + +So here is an overview, from the lowest level stuff to the highest. + +@section Palette and image library + +@findex image +@findex palette +The sources for this are in the directory @code{src/filter}. +The aim of the palette library is to provide a relatively abstract interface to +the various visuals, and hide differences in the hardware and driver +implementations. Fixed color, pseudocolor, grayscale and truecolor visuals +should be handled in almost the same way. + +It provides the @code{palette} structure, containing a palette. You might +allocate new colors here (you give an RGB value and the corresponding pixel +is returned), interpolate colors where possible, cycle colors and so on. + +Every palette contains two parts --- the preallocated color cells and the actual +palette. For instance, this could be used to allow the GUI the possibility to +allocate static, unchanging colors for its texts and dialogs, while the rest of +the palette is under the control of different parts of XaoS. + +This library also contains a set of functions to allocate different palettes +used by other parts of XaOS. I expected that different parts of XaoS could share +the same palette. This hasn't happened yet, but the functions are kept here just +in case. + +The image library is built on top of the palette library, providing +functionality for handling actual image data. Each image is represented by one +or two frame-buffers (useful for double-buffering). One frame-buffer is +called `current' and the other `old'. They are flipped by a special function. +The program can draw into either of them. + +Frame-buffers are held as a set of pointers to scan-lines. This provides more +flexibility than more obvious representations, because tricks like sub-windows +and flipped bitmaps are possible. It's also fast, since you should avoid one +multiplication. + +The last significant information the image structure holds is of course the bpp +depth. It is counted in bytes, and ranges from 0--4 (where 0 is used for 1bit +bitmaps). + +@section Filter library +Sources are available in @code{src/filter}. +This library controls the process of image creation. It handles a queue of +filters, where each filter modifies the image in some way. The filters at the +beginning and end of the queue are special; the first filter is usually the +actual fractal engine which creates the image, and the last filter is usually +the user interface helper library. + +@section Xthread library +This library provides an interface to various multi-threading libraries; +currently the BeOS, plan9 and POSIX implementations are available. It allows the +running of various functions in parallel, and provides some synchronization +primitives (semaphores). It is simple, but has all the functionality required +for the XaoS engine. + +@section Fractal library +Sources are available in @code{src/engine/}, headers in @code{fractal.h}. +This library contains the actual fractal calculation routines. It is governed by +a fractal context, which contains information like the current formula, the seed +(for julia sets), the palette, and so on. + +Functions for calculating the various fractal types and various coloring modes +are also available here. + +@section Zooming engine and other filters. +Sources are available in @code{src/engine/}. +This is the actual zooming engine filter. It is fairly independent of the +fractal library, so it could possibly be used for zooming other stuff. (It has +already been used for zooming large scale images containing maps of Hungary). + +The file @code{ui_helper} contains the implementation of all filters not already +mentioned, and a structure containing all functions exported from the filter to +the user interface. One other terminal filter is implemented --- the Julia +morpher. Other filters add special effects (such as motion blur), or do +conversions (such as rotation or dithering). + +@section Timer library +This library provides many useful timing primitives (such as timers). +It is used by some other programs too. + +@section xio library +This library aims to provide a unified, portable interface to the file +system. Some strange systems (such as MacOS) have a very different filesystem +API to UNIX; perhaps they don't represent filenames as a string, use special +structures, or something; this library abstracts away from all that. + +@section xshl library +Xshl stands for XaoS simple hypertext library. It contains a fairly universal +engine parsing an `xshl' language, similar to HTML, with some additions and many +restrictions. It can render text for both proportional and monospaced fonts, in +various sizes. + +@section help library +This is built on top of the xshl and xio libraries. It can read help files +containing help chapters, can parse keywords in chapters, and so on. + +@section 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. + +@section Catalog library +This is a library for handling message catalogs. It should read catalogs and +convert keywords into an actual message. + +@section PNG library +This library provides a function for saving an image from the Image library to a +file, in PNG format. Other formats could be added as well if required. + +@section UI-helper library +This library controls all the low-level stuff and provides a high-level +interface to it. It has functions for playing animations, zooming/un-zooming +and suchlike. It all the other libraries heavily. It doesn't implement +functions for handling menus and such, but could be helpful for such +implementations, because of the function registry database. + +@section Ugly interface +This is currently the only real user interface for XaoS (there is another, wich +is used for rendering animations, but it is not a user interface as users +understand the term). It is built above the UI-helper library and provides +functions for drawing menus, dialogs and so on. It has drivers for many +platforms, and can be easily ported to others. + +In the future, it should be quite easily extended to let drivers specify their +own menu/dialog handling code; so it should be possible to give it a ``native'' +look on each platform. + +It can also operate in a mode where the GUI drawing routines are disabled; the +function registry database is transferred through a pipe to an external program, +which should build the menus and act as an external user interface, sending back +commands in the scripting language (presumably representing things that the user +has done). This provides another way to give a native look to the ugly interface, +and could also be used to interface other scripting languages to XaoS. + +The ugly interface has one serious limitation --- for historical reasons, it is +coded to handle just one window (the rest of XaoS can probably do multiple +windows, but this is untested), so in windowed environments it is impossible to +open multiple menus with fractals. On the other hand, this limitation is not so +important once external GUIs enter the picture, as they could just start +multiple XaoS engines. This is also preferred because it brings extra +robustness, multitasking and some other advantages. That's why I don't plan to +remove this limitation yet. + +@node driver, gui-driver ,design ,Top +@chapter Driver API description + +To port XaoS successfully to some platform you need: + +@itemize @bullet +@item +An ISO C compatible optimizing compiler. Note that an optimizing compiler is +really required, since XaoS is coded to be a good target for optimizations and +doesn't have many routines coded in assembly; so if you will use a bad compiler, +you will notice drastic slowdowns (a slowdown of 10x or more). Some compilers +have serious problems compiling XaoS; this applies to most DOS compilers (Watcom +C, Borland C, Microsoft C) for instance. They generate incorrect code or crash +during compilation. I highly recommend using the GNU C compiler, but even some +versions of GNU C have difficulty. Please read @code{compilers.txt} for more +information. +@item +A fast way to avoid division by zero/overflow and other floating point +exceptions. XaoS is carefully coded to not crash in this case, but doesn't have +any tests to avoid such situations; expect random results in such cases. Many +platforms provide a means to switch coprocessor into a mode where 1/0 produces +Inf and so on. If there is no such means, try to use some kind of signal handler +that will ignore such exceptions. + +The ``normal'' solution --- add @code{if}s to avoid division by zero --- is +almost impossible. Division is quite easy to check for, but other cases (such as +overflows) are much harder. I don't think it is possible to avoid all crashes +just by adding @code{if}s. + +XaoS doesn't depend on IEEE arithmetic. The result in the sort of edge cases +where IEEE makes a difference is mostly undefined. XaoS usually works well with +compiler switches for inexact math enabled (such as @code{-ffast-math} in GCC), +but, of course, there are no guarantees. For example on Alphas this is not true, +since they usually generate exceptions in that case. +@item +A text or graphics output device. If you only have a text output device you may +use the AA driver, which renders fractals into high quality ASCII art. In this +case you might want to skip this chapter, download AA-lib +(http://www.ta.jcu.cz/aa) and read the porting chapter of AAlib manual. A +graphics device must be one of: + +@findex C256 +@findex FIXEDCOLOR +@findex GRAYSCALE +@findex TRUECOLOR +@findex TRUECOLOR24 +@findex TRUECOLOR32 +@itemize @bullet +@item 8 bits per pixel with user definable palette @code{C256}, static palette @code{FIXEDCOLOR}, or static grayscale @code{GRAYSCALE} +@item 16 bits per pixel with arbitrary bits per color @code{TRUECOLOR} +@item 24 bits per pixel with 8 bits per color, arbitrary order @code{TRUECOLOR24} +@item 32 bits per pixel with arbitrary order of colors, where each color fits in exactly one byte @code{TRUECOLOR} +@item 1 bit per pixel bitmap, either least or most significant bit first +@end itemize + +Please contact me if you have a different kind of device. Some modes (like +mis-ordered truecolor modes) could be added really easily if required. Note +that mono/4/16 colors devices will probably never be supported internally by +XaoS, since I expect they will be slower than 8bpp, so XaoS will internally work +in 8bpp and then convert to 1/2/4bpp. Contact me if you want to write such a +converter. (For bitmap one already exists --- see @code{dither.c}.) +@item +Some way to save images. By default XaoS uses @code{libpng}, which is ported to +many platforms, but there are many platforms where it isn't ported yet. If your +system has some standard image format which is easier to handle than +@code{.png}, contact me and I will show you how to add such support to XaoS (see +@code{png.c}). +@item +Stdio compatible library (this is a problem on the Mac and BeOS). XaoS has an +abstract layer above stdio, so it can use other input/output libraries too. You +could write another implementation of this layer, called @code{xio}. See +@code{xio.h}, @code{xstdio.c}, and @code{xstdio_mac.h} for an example. +@end itemize + +The ugly interface is designed to make writing new drivers as easy as possible. +Use the file @code{ui_template} when starting to write a new driver from +scratch. You need to write only a few functions, filling out the following +table: +@findex ui_driver +@example +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; +@}; +@end example + +@section Functions + +@code{ui} uses the following functions to communicate with a driver: + +@defun init + Initializes the driver and returns 1 on success and 0 on failure. +@end defun +@defun getsize (int *@var{width}, int *@var{height}) + Returns the size of screen (or window) in x and y dimensions. +@end defun +@defun processevents (int @var{wait}, int *@var{x},int *@var{y}, int *@var{buttonmask}, int &@var{keys}) + Gets new keyboard/mouse events. Parameters are: + @table @var + @item wait + If 1, the function can block, waiting indefinitely for the next event, + otherwise it just determines if something's already arrived. This is + useful on multi-tasked OSes, where eating unnecessary CPU time on + busy-waiting is discouraged. + @item *x,*y + Returns the current mouse coordinates. + @item *b + Returns a mouse button bitmask of @code{BUTTON1}, @code{BUTTON2}, and @code{BUTTON3}. + @item *k + Returns a cursor key bitmask: + @table @code + @item 1 + @key{left} + @item 2 + @key{right} + @item 4 + @key{up} + @item 8 + @key{down} + @end table + @end table + The function calls @code{ui_key} (ASCII character) and @code{ui_resize} + if required. For special keys use @code{UIKEY_UP}, @code{UIKEY_DOWN}, etc. + See @code{ui.h} for a complete list of these constants. + + In case of problems freeing/allocating inside @code{processevents} you may + call @code{ui_call_resize}, which calls resize later outside this function. +@end defun + +@defun uninit + Uninitialises driver---called before exit. +@end defun + +@defun set_range (ui_palette *@var{palette}, int @var{start}, int @var{end}) +This is the preferred way to set the palette (the other way is with +@code{set_color}). When @var{imagetype} is @code{UI_C256} (256 color with +palette) one of these two functions @emph{must} be used. In truecolor modes they +are unused. If direct palette access is possible on your platform, define this +function. The function is expected to set all color cells between @var{start} +and @var{end} to colors defined in @var{palette}. @var{ui_palette} is array of +@var{ui_rgb} elements. @var{palette[0]} is the color of entry number +@var{start}. @var{ui_rgb} is an array of @code{char}. @var{palette[0][0]} is +the red field of entry number @var{start}, @var{palette[0][1]} is the green and +@var{palette[0][2]} is the blue. @code{0} means black and @code{255} means full +intensity. Use @code{NULL} if your driver doesn't support this call. +@end defun + +@defun set_color (int @var{r}, int @var{g}, int @var{b}, int @var{init}) + This is a secondary way to set the palette, that should be used at platforms + w/o direct palette access (like X11 or static color schemes). It receives the + RGB value of the color, and returns the index of the color cell with this + color, or -1 if no more color cells are available. The @var{init} parameter is + set to 1 when this function is called for the first time on a given + palette; @code{set_color} is then expected to free all color entries + previously allocated. Use @code{NULL} if your driver doesn't support + this call. +@end defun + +@defun print (int @var{x},int @var{y}, char *@var{text}) + Prints text to screen at position x/y. This function is a bit archaic + (XaoS now uses its own functions drawing directly to the buffer in most + cases), but in some cases --- initialization messages or calculation --- + the functions are unusable, so we still need this primitive. In the + @code{C256} mode you can rely on the first allocated color always being + black and the second being white. +@end defun + +@defun display (void) + Displays current buffer on screen +@end defun + +@defun alloc_buffers (char **@var{buffer1},char **@var{buffer2}) + Allocates two buffers that can hold a bitmap the size of the screen. + Also sets the current buffer to @var{buffer1}. Since version 2.1, this + returns the scan-line size in bytes (usually the screen width) or 0 + on failure. This is useful on systems that allocate a bitmap bigger + than the window/screen (divisible by 4 or thereabouts). +@end defun + +@defun free_buffers (char *@var{buffer1}, char *@var{buffer2}) + Frees allocated buffers. +@end defun + +@defun flip_buffer (void) + Flips buffers --- sets the current buffer to the other one. +@end defun + +@defun flush (void) + This function should be used by drivers with buffered output to flush + those buffers. Other drivers should set it to @code{NULL}. +@end defun + +@defun mousetype (int type) + This function is used to change the mouse cursor. @var{type} has the + following values: + @table @code + @item NORMALMOUSE + This pointer is that usually displayed, while the UI waits for user + input. + @item WAITMOUSE + This pointer is displayed when the UI is busy (perhaps the famous + hourglass) or you may use that defined in ui_dos --- a Mandelbrot + set. + @item REPLAYMOUSE + This pointer is displayed during replay. There should be none in + fullscreen drivers, since a blinking mouse cursor during replay + looks ugly. On windowed systems, disabling the mouse looks ugly, + so it should be some funny cursor. + @end table + You should use @code{NULL} if your driver doesn't support this. +@end defun + +@section Other information +Some additional variables are also used to inform the ui library about the +driver. All these values can be changed by init functions in case they were +unknown beforehand. + +@table @var +@item textheight, textwidth + Width and height of your font +@item palettestart, paletteend + First and last palette entry that can be changed. You should use this + to avoid changing entries reserved for the window system, UI objects, + mouse, etc. +@item rmask, gmask, bmask + These fields are used in truecolor modes to specify where each color is + defined. +@item maxentries; + Number of allocatable entries. Normally should be + @var{palettestart}-@var{paletteend} +@item imagetype + Defines the type of image. Should be one of the following values: +@findex UI_C256 +@findex UI_FIXEDCOLOR +@findex UI_GRAYSCALE +@findex UI_TRUECOLOR +@findex UI_TRUECOLOR24 +@findex UI_TRUECOLOR32 + @table @code + @item UI_C256 + The classical 256 color with palette scheme used by most older graphics + adapters. You should also use it for static-color schemes, but they are + not well supported in current versions of XaoS. + @item UI_TRUECOLOR + 32bpp truecolor mode + @item UI_TRUECOLOR24 + 24bpp truecolor mode + @item UI_TRUECOLOR16 + 16bpp truecolor mode + @end table +@end table + +What follows is @emph{not required} to get the driver working at first, +so you may skip to @emph{registering driver} on the first read and return +here later. + +@table @var + +@item params + You may define command line options for your driver. + + They are defined using a @var{params} structure like: +@findex params + @example + static struct params params[]=@{ + @{"-mode",P_NUMBER,&defmode, + "Select graphics mode(same number as in interactive menu)"@}, + @{NULL,0,NULL,NULL@} /*this MUST be last option field*/ + @}; + @end example + + where every line is one parameter. The list ends with @code{@{NULL,0,NULL,NULL@}}. + The first field is the option name. + The second field is the parameter type: +@findex P_SWITCH +@findex P_NUMBER +@findex P_STRING +@findex P_FLOAT + @table @code + @item P_SWITCH + No parameter --- variable is just set to 1 if the option is supplied. + @item P_NUMBER + Integer number + @item P_STRING + String + @item P_FLOAT + Floating point number (variable is float) + @end table + The third element is a pointer to a variable that is changed if the option is + supplied. (For instance, it is @code{int*} for @code{P_NUMBER} or + @code{P_SWITCH}.) + The last element is help text displayed by @code{ui -h}. + + +@item width,height + See @var{flags}. May be set to @code{0.0, 0.0} at the start. + +@item maxwidth,maxheight + See @var{flags}. May be set to 0,0 at the start. + +@item @var{flags} + This variable says more about your driver. A good starting value is 0. + But for the final version it is recommended to read the following carefully. + + Flags are uppercase constants and should be set as follows: + + @code{ASYNC_PALETTE | RANDOM_PALETTE_SIZE} + + The following flag constants are supported: + + @table @code +@findex RANDOM_PALETTE_SIZE +@findex UPDATE_AFTER_RESIZE +@findex RESIZE_COMMAND + @item RANDOM_PALETTE_SIZE + States that the palette is randomly sized. This is used in X where the + palette is shared between many programs. By default XaoS allocates all + available colors up to 256. This is not very nice to other applications in + X, so this flag states that that a random number of colors (in the range + 8--256) are allocated. + + When this variable is off XaoS expects that the same number of colors is + always available. + @item UPDATE_AFTER_RESIZE + Causes the screen to be recalculated and redrawn upon a resize, even if + its size has not changed, in case the resize procedure destroys data in + XaoS' buffers. + @item RESIZE_COMMAND + Some drivers (mainly the fullscreen ones) may ask the user for the size + and color depth to use, in the function @code{get_size}. It would be nice + to let the user change this parameter at runtime and force XaoS to + reinitialize all its images. This is done with the @code{ui_resize} + call + + In windowed drivers, this is called by external window-system events, but in + fullscreen drivers you'll need a key or menu item for this. You could add + this function directly into XaoS's function registry (see for example the + GGI driver) --- it is useful mainly when you want to use a size selection + dialog that is standard for your environment, or let XaoS use its default + one. For example, see the SVGAlib or DOS driver. + @end table + + Screen/window size information: + + Xaos needs to know the exact physical size of displayed images. This is + required for random dot stereograms and also for keeping the aspect ratio + of fractals correct (do not make them wide in 640x200 resolution etc.) + At least one of the following values should be defined (given in the order I + prefer) +@findex SCREENSIZE +@findex PIXELSIZE +@findex FULLSCREEN +@findex RESOLUTION + @table @code + @item SCREENSIZE + The @var{width}/@var{height} values specify the exact size of the + screen/window in centimeters + @item PIXELSIZE + The @var{width}/@var{height} values specify the exact size of one pixel in + centimeters. This is better for windowed environments, where the window + size is often changed. + @item FULLSCREEN + The driver runs fullscreen. XaoS automatically uses the default screen size + (29.0cm x 21.5cm) + @item RESOLUTION + The driver does not know the exact screen size, but knows the resolution + used (in the @var{width}/@var{height} variables); XaoS automatically + calculates pixel width using width = 29.0cm/maxwidth and height = + 21.5/maxheight. + @end table + Of course the default width and height can be changed by command line + options. You may also use combinations like: + + @table @code + @item SCREENSIZE | FULLSCREEN + The best for fullscreen drivers + @item PIXELSIZE | RESOLUTION + The best for windowed drivers + @item FULLSCREEN + For fullscreen drivers that have no idea about screen size... + @end table + + Do not forget to set the @var{width}, @var{height}, @var{maxwidth}, + @var{maxheight} fields if required. + +@item gui_driver + See the next section for description. +@end table + + +@section Registering the driver + +Once you've done the above, you just register the driver in @code{drivers.c} and +you may compile :) You can use @code{ui_template.c} as a driver template. + +You may also look at the xthreads library description if you are porting XaoS to +some SMP platform. + +Please let me know if you want to start to code a driver. + +@node gui-driver, eui ,driver ,Top +@chapter Writing a GUI driver + +XaoS has a builtin GUI. Many operating systems have native GUI toolkits and XaoS +default GUI might look strange there. To avoid this problem, you might write an +external GUI program (see eui section) or write mappings from the XaoS GUI +functions to the native ones. The advantage of an external GUI process is +multitasking; XaoS is not thread safe and the GUI must be synchronous with +calculation. Also, the ugly interface code currently doesn't support multiple +windows (although this should be solved in the future). This solution is +suitable mainly for those systems where two cooperating programs sharing one +window is a problem (like Windows). + +To write a GUI driver you need to fill out the following structure: +@example +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); +@}; +@end example + +All functions have a @code{uih_context} parameter. You don't need to worry about +its contents; just pass it to the functions that require it. This parameter is +for multiple window support, which is not implemented yet. + +The @code{setrootmenu} function draws the root menu according to the menu called +@code{name}. To get the menu fields you might use the following piece of code: +@example +#include +#include + +.... + +int i; +menuitem *item; +for (i = 0; (item = menu_item (name, i)) != NULL; i++) + @{ + if (item->type == MENU_SUBMENU) @{ + /* This field is a submenu. You might call a function to + construct the submenu here. item->shortname contains + the name for the submenu. */ + @} + /* Add menu field here. + + You might check flags here: + item->flags&MENUFLAG_CHECKBOX + field has a checkbox + item->flags&MENUFLAG_RADIO + field is part of a radio button group. In the current + implementation, there is one radio button group per menu. + + in both cases you can call menu_enabled(uih, item) to see + if the item is checked or not. + + item->name contains the field's text + + item->key contains a hotkey (a one letter string in the + current implementation) + @} +@end example +Once the field is selected, call the function @code{ui_menuactivate(item, NULL)} +where @code{item} is a pointer to the @code{menuitem} record of the selected +field. + +The @code{enabledisable} function is called when the checkbox or radiobutton +state is changed. The @code{name} parameter is the same as the +@code{item->shortname} of the changed field, so you need to search all the +menus, compare @code{name} to @code{item->shortname}, and if it matches, call +@code{menu_enabled} to get the new state. For radiobuttons, only enable events +are noticed. Your code is expected to automatically disable all other +radiobuttons in the same submenu. + +The @code{menu} function works similarly to @code{setrootmenu}, but displays a +popup menu. + +The @code{dialog} function is called for dialogs. The function should look like: +@example +menuitem *item = menu_findcommand(name); +menudialog *dialog = menu_getdialog(uih, item); +int i; +for(i=0; dialog[i].question; i++) +@{ + /* Construct dialog, where the left side contains labels with + dialog[i].question, and the 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 available). + 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. + cast dialog[i].defstr to char ** to get a pointer to a NULL + terminated array of choices. +@} +@end example +Once the dialog is filled by the user, @code{gui_driver} is expected to allocate +an array of union @code{dialogparam}: +@example +dialogparam *p = calloc (sizeof (*p), nitems); +@end example +and fill in the selected values. @code{p[i].dint} is used to pass an integer +value, or the number of a DIALOG_CHOICE selection, @code{p[i].number} is used +for floating point numbers, @code{p[i].dstring} for strings and filenames, +@code{p[i].dcoord[0]} and @code{p[i].dcoord[1]} for complex values. + +The string values are expected to be in separately @code{malloc}ed chunks. Once +the array is filled, call @code{ui_menuactivate(item, p)}. + +The function @code{help} is used to display help about a given topic. To +implement it you could either convert XaoS help file to some native format, or +use the xshl library to render the help page for you. To render an xshl page +use: +@example +#include +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 - emphasized text + XSHL_MONOSPACE - monospaced text (typewriter) + XSHL_LINK - line (should be underlined or suchlike) + XSHL_WHITE + XSHL_RED + XSHL_BLACK - color of text (not very meaningful here) + XSHL_RIGHTALIGN + XSHL_CENTERALIGN - alignment of text + +@} +lines = help_make (name, getwidth, textheight, largetextheight); +if (lines == NULL) + lines = help_make ("main", getwidth, textheight, largetextheight); + +@end example +Now you might use @code{lines} to draw the help. It is a pointer to the array of +structures: +@example +struct xshl_line @{ + int y; + struct xshl_item *first; +@}; +@end example +@var{y} is the position of the line from the beginning of the text, and +@var{first} is a pointer to the blocks of text on the line. The last line +contains a @code{NULL} pointer in the first section. + +@code{first} is a linked list of @code{xshl_item} structures: +@example +struct xshl_item @{ + struct xshl_context c; + char *text; + int x; + int width; + struct xshl_item *next; +@}; +@end example + +You can draw @code{text} at position @code{x} (and @code{y} from the line +record) using the text style described by @code{xshl_context}: +@example +struct xshl_context @{ + int flags; + char *linktext; +@}; +@end example +@code{flags} has the same meaning as in the @code{getwidth} +section. @code{linktext} is the name of the next help page when the field has +the @code{XSHL_LINK} atribute. + +For an example of @code{gui_driver}, see the win32 driver code. + + + + +@node eui, ui-helper ,gui-driver ,Top +@chapter Writing an external user interface + +This part describes how to make an external user interface --- that is, a +separate program which constructs a window with all menus and dialogs. It uses +the XaoS engine to calculate the fractal as a separate process. This design +brings many advantages --- the external GUI implementation could have a ``native +look'' for given platform and could contain many extensions (perhaps multiple +windows). Also all calculation is done while multitasking, so the user interface +is usable even when the engine is busy. + +The X Window System provides a way for programs to draw into others' windows --- +the ``master'' program creates window the sub-window where it wants to put the +fractal, then calls the engine with @code{-windowid} @var{number_of_window} +parameters. Instead of creating a new window, the engine uses uses the specified +window. The most famous example of such cooperation is probably +ghostscript/ghostview. + +Other windowed environments probably provide similar means for for +cooperation. In most others it will probably be implemented using shared memory, +so it should work on most platforms, I expect. + +Of course, you might also design the UI as a separate button box in another +window, like most animation players, or ImageMagick do. In fact, the external +GUI could be very similar in style to ImageMagick... + +@section Basic concept + +The UI implementation has a function to disable its GUI functions. Because of +the function registry, all its menus and dialogs are described in a fairly +simple database, which is also mapped to the Scheme-like scripting language. +The external UI implementation can just translate the user's actions into this +scripting language and send that through the pipe. + +The commands, menus, and dialogs should be created automatically from the +database, so the UI doesn't need to have special code for each XaoS feature. At +the beginning it should use XaoS' @code{(print_menus)} command to force it to +send information about the database, then build menus using this information. + +For this you only need some equivalent to UNIX pipes, so again I expect it is +doable on most platforms. + +@section Starting XaoS as a slave process + +One of the first things the engine needs to do is to initialize XaoS in the +right mode to work as a slave process. For this you need to do several things: + + +@itemize @bullet +@item Open the pipe +@item Disable the builtin GUI +@item Read the menu hierarchy (this is optional --- GUI can also have all menus +coded into it. But it is not recommended, since it will cause problems with +adding new features in future) +@end itemize + +Opening pipe is done via the @code{-pipe} option. It takes one parameter, the +name of the FIFO you want to use. If you specify ``@code{-}'', XaoS will read +input from stdin. + +To disable the XaoS GUI use @code{-nogui}. This will disable all menus, dialogs +and help text. + +To read the menu hierarchy, just add @code{-print_menus} parameter and then +parse XaoS's output. This will print the whole menu hierarchy. If you are +building menus at the time they are selected, you might prefer to use the +@code{print_menu} command, which prints just one menu without its submenus; its +output could be immediately used for building a menu. The command takes one +string parameter, the name the menu you want to print; i.e., to print the root +menu use @code{-print_menu root}. + +Under the X Window System you also need to specify the @code{-windowid}; also +the @code{-shared} option is quite recommended. Otherwise in pseudocolor visuals +XaoS will create its own colormap, wich will likely collide with the UI's +colormap, and either XaoS or the UI will have wrong colors. If you have any +idea how to avoid this, let me know. + +You might also let the user specify some extra parameters from the command line, +by simply adding those options to the end of the command line. The @code{-nogui} +and @code{-print_menus} commands must be first for a simple reason: XaoS parses +its command line early in initialization. Some commands (like +@code{-print_menus}) should be processed at this time, while others (like +@code{-loadpos} need a working engine. Such commands are queued and processed +later, once the engine is initialized. XaoS never reorders commands; if an +option that requires queuing is located before @code{-print_menus} on the +command line, it will queue @code{-print_menus} too. This will cause the menus +to be printed much later, slowing startup. + +So the proper calling sequence for the user interface under X should look like: + + +@example +xaos -nogui -print_menus -windowid -share -pipe - @var{[other options]} +@end example + +@section Parsing the menu structure + +The structure is printed menu by menu. Each menu contains a header, some +entries, then @code{endmenu}. The listing from @code{print_menus} is terminated +by @code{endmenus}. + +The header starts with @code{menu} and then contains a menu identifier, and the +menu's full name, e.g. + +@example +menu "fractal" "Fractal" +@end example + +Each entry which follows has its own line. It starts with a menu type, which +should be @code{submenu} or @code{menuentry}. + +@code{submenu} has a similar format to the header --- the full menu name, and an +identifier. + +The next few fields are @code{menuentry}-related. It has an entry type, which +could be @code{normal}, @code{radio} or @code{checkbox}. @code{radio} and +@code{checkbox} are followed by @code{on} or @code{off} specifying whether it is +enabled or disabled by default. (The radio-buttons don't have explicit +information about which group they belong to. For now I expect that each menu +contains just one such group, so it is clear in any case.) + +A set of flags should follow. Currently two flags are defined: @code{dialog}, +wich specifies that the function has a dialog box, and +@code{dialogatdisable}. By default, dialogs for check-boxed functions are +displayed only when the checkboxes are enabled. The second flag reverses this +behaviour. It is currently used for the @code{mandelbrot} function, which +behaves in this way; when you disable it, the user is prompted for the Julia +seed. + +So a specification should look something like this: + +@example +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 +@end example + +@section Activating functions and dialogs + +Once the menu structure is built and the user selects some item, it should be +activated. This is done by a simple command: @code{(@var{name})}. Once +``@code{)}'' is sent, the command is executed by XaoS. + +Check-boxed functions has one extra parameter --- @code{#t} to enable them and +@code{#f} to disable. So if you want to enable the @code{autopilot} item, send: +@code{autopilot #t} + +Radio-buttons don't have any such parameter, because disabling radio-buttons +makes no sense. + +If the item has a dialog enabled, the engine expects that the UI will make the +dialog first, ask the user for values and then pass back a function with +parameters. But first, the UI needs to know what parameters the function +expects. This is done by sending the command @code{(print_dialog +"@var{name}")}. XaoS replies with a dialog specification very similar to the +menu specification. + +This has the header @code{dialog} followed by the name of the function being +described. Then one dialog entry per line is sent, started by +@code{dialogentry}, followed by the question the UI should display. Next is a +type, which should be one of the following: +@table @code +@item integer +Integer number such as @code{123} +@item float +Floating point number such as @code{123.123} +@item string +String such as @code{"ahoj"} +@item keyword +String such as @code{'ahoj}. Keywords are mostly similar to strings, except that +they can not contain spaces. They are used, for example, for specifying types of +formulae. Strings are used for printing text and so on. +@item inputfile +@item outputfile +Here the UI should display a file selection dialogs. With @code{outputfile} it +is also a good idea to check whether the file exists and ask the user if he +wants to overwrite it. +@item onoff +Boolean value (@code{#f}, or @code{#t}) +@item complex +Complex value --- two floating point numbers such as @code{123.123 123.123} +@item choice +Choice between some keywords. The keywords are sent after @code{choice}, +enclosed in @code{@{} @code{@}}. +@end table +The last information on the line is the default value, in the same format as the +examples above. For files, the default value is in the format +@code{"@var{[prefix]}*@var{[extension]}"}. + +Some examples: + +@example +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 + +@end example + +To activate a function, send a command consisting of the function name followed +by a sequence of parameters, mapped one-to-one to dialog box fields, in the same +order as those fields. The parameters have the same format as in the above +examples; checkbox fields return @code{#t} and @code{#f}. For instance: + +@example +(uiview 0 0 0.5 0) +(load "text.xpf") +(color 'white) +@end example + +@section Synchronization + +In some cases, XaoS can change radio-box and check-box values itself (when user +presses a key, or loads some file, for instance). All such changes are sent to +the GUI so that it can update what the user sees correspondingly. They are sent +to standard output in the following format: + +@example +checkbox "name" on/off +radio "name" on/off +@end example + +Your GUI code should parse this and change its menus when necessary. + +XaoS's menus can contain multiple distinct trees. In some cases (like when +animation replay is active) the root of the menu structure should change. To +indicate this to the GUI, XaoS sends a command: + +@example +root "name" +@end example + +Also, the user can press keys which normally display menus, dialogs or +help. If XaoS has the keyboard focus, it will receive these instead of the +GUI. XaoS sends commands to indicate this: + +@example +menu "name" +dialog "name" +help "topic" +@end example + +All these commands should be taken into account by the GUI, or could be ignored +(not recommended!) + +@section help + +XaoS's help is in a simple hypertext language. In order to simplify its parsing, +I've made xshl and help libraries. Making a help window with these libraries +should be quite easy; just call the help function: +@deftypefn Function struct xshl_line *help_make (char *@var{command}, int @var{getwidth} (void *, int @var{flags}, char *@var{text}), int @var{width}, int @var{smallheight}, int @var{bigheight}); +@end deftypefn +and you will receive a stream of text with coordinates describing where to +display the text into the shared window. + +The @code{command} parameter is the help topic. The @code{getwidth} function +returns the width of a given piece of text. @code{width} is the width of the +window, @code{smallheight} is the height of the small font, and @code{bigheight} +is the height of the big font. + +Please ask me for more details if necessary. + +And thats all. Good luck with coding. + +@node ui-helper, xthreads ,eui ,Top +@chapter UI-helper library + +UI helper library takes care of all of XaoS' engine functions and features and +provides a higher level API which is quite easy to understand. If you want to +write a completely new user interface (a replacement for the ugly interface --- +not just new bindings for native menus or external user interfaces) or you want +to use the XaoS engine in your program, you will probably want to use this +library. + +Its API has many calls and features. This section gives a brief overview of its +calls. Please ask me for details. + +@section initialization + +To initialize the UI helper library, you need to prepare a palette and image. +The palette is created using the palette library call +@code{createpalette}. Creating a truecolor palette should look like this: + +@example + struct palette *pal = createpalette (0, 0, TRUECOLOR, 0, 0, NULL, + NULL, NULL, NULL); +@end example + +For details about creating palettes see @code{ui.c} or ask me. + +To create an image, call: + +@example + struct *image img = create_image_mem (width, height, 2, pal, + pixelwidth, pixelheight); +@end example + +This creates an image in memory. If you want to create it in your own buffers, +you might use @code{create_image_cont} or @code{create_image} calls. Again see +@code{ui.c}. + +Then it is time to fire up the main library: + +@example + struct uih_context *uih = uih_mkcontext (0, img, passfunc, + NULL, NULL); +@end example + +The @code{passfunc} is called when the engine is calculating. It might process +external events and display progress information. It should look like this: + +@example +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 */ + @} +@} +@end example +It can set @code{uih->interrupt} if it wants to interrupt the current +calculation (whereupon the main calculation loop will return to its caller). + +You can also load the catalog file in order to make tutorials work: + +@example + uih_loadcatalog (uih, "english"); +@end example + +Once this is done, the ui_helper library is fully functional and you can enter +the main loop. + +@section main loop +The UI helper library does not have any timing primitives; so it expects a +standard form of main loop. It asks it caller to redisplay a changed image when +necessary. The library also uses the generic timerlib library for its timing, +for which see elsewhere in this document. + +The main loop should look like this: + +@example +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 for the given time in usec - wait for events etc..*/ + @} + /*and repeat*/ + @} +@end example + +@section Calling functions + +The UI helper library has many functions declared in @code{ui_helper.h} for +various actions. There are too many of them to describe here, but their names +are quite informative, so I hope you will not have problems. + +(You could also use the XaoS function registry, which does all this stuff for +you; you will just draw menus and dialogs based on this registry and all +features will be automatically made available. If you are writing an ordinary +user interface, this is the preferred way.) + +Note that the @code{ui_helper} library is not reentrant, so you can't call most +of these functions from the @code{passfunc}. If you are using the registry, the +activating function handles this automatically and queues functions when +necessary. To process them you need to flush the queue in the main loop as +follows: + +@example +static void +processbuffer (void) +@{ + menuitem *item; + dialogparam *d; + if (uih->incalculation) + return; + while ((item = menu_delqueue (&d)) != NULL) + @{ + menu_menuactivate (item, d); + @} +@} +@end example + +@section closing library + +This is done using: + +@example + uih_freecontext (uih); +@end example + +One user of this library is the ugly interface code in XaoS; see the +@code{src/ui} directory. Another, much simpler user is +@code{src/ui-hlp/render.c}, which does animation rendering. + +@node xthreads, filters ,ui-helper ,Top +@chapter XaoS thread library + +This description should be useful for those who want to port XaoS to +multiprocessor platforms, and those who want to implement a filter or other +relatively computationally expensive code. Note that the thread library uses +nothread calls as a degenerate case when only one thread is used, when the host +does not allow multi-threading or it is not an SMP architecture (since this +library is used only to distribute calculation into other CPUs). + +XaoS thread library is a simple map of a few functions required by XaoS to the +system's library for threads. + +It has the following variables: + +@deffn Variable ethreads +This is set to 1 in the case that threads are enabled +@end deffn + +@deffn Variable nthreads +Number of threads +@end deffn + +It provides the following functions: + +@deftypefn Function {void} xth_init (int @var{threads}) +This function initializes the threading library (starts threads, sets +@var{ethread} to @code{1} and @var{nthreads} to @var{n}. @var{threads} parameter +should be set to 0 for auto-detection, or to the number of threads the user +wants. If threads is set to 1, the threading library is disabled and the +following functions are mapped to the @code{nothread_} equivalents defined in +@code{xthread.h}. + +Note that all threads are not interchangeable --- there is a main thread (the +one that called @code{xth_init}) that communicates with drivers, controls +calculation, and so on, and there are child threads that are waiting for orders +from the main thread. The latter threads can't use any functions from the +xthread library. +@end deftypefn + +@deftypefn Function {void} xth_uninit (void) +This function un-initializes the thread library --- kills child threads and sets +@var{ethread} to 0 and @var{nthreads} to 1. +@end deftypefn + +@deftypefn Function {void} xth_function (xfunction *@var{function}, void *data, int @var{range}) +This function is used when the engine wants to perform some operation on the +image in parallel. It is expected to wait until all threads are ready, then +start @var{function} on all threads, including the control one, with the +following parameters: @var{data} --- the same as @var{data} passed to +@code{xth_function}, @var{taskinfo} --- pointer to a platform-dependent +@code{taskinfo} structure (defined in @code{xthread.h}), but must have at least +a field @code{n}, that holds the thread number (where the control thread is +numbered 0 and other threads are numbered in the range 1 -- @var{nthreads}). +The next two parameters are the range of images across which the function is +expected to work. @code{xth_function} is expected to divide @var{range} into +@var{nthreads} equal pieces and pass to each thread the start of a piece and the +start of the next piece (@var{range} for the last one). The function does not +wait for other threads to finish at the end, but returns immediately to main +thread after @var{function} returns. + +This function is called approx. 5--10 times per frame. +@end deftypefn + +@deftypefn Function {void} xth_sync (void) +This function waits until all threads are ready for the next order from the main +task. + +This function is called approx 5--10 times per frame. +@end deftypefn + +@deftypefn Function {void} xth_bgjob (xfunction *@var{function}, void *@var{data}) +This function is expected to behave as follows: if there are any threads waiting +for orders, ask one of them to call @var{function} with similar conventions as +in @code{xth_function} except that the @var{range} parameters are set to 0. +Otherwise it starts function in the foreground, as usual. + +This function is called once per frame. +@end deftypefn + +@deftypefn Function {void} xth_nthread (struct taskinfo *@var{s}) +This function should be used to determine the current thread number. Do not use +@code{taskinfo->n} instead, since if threads are disabled this will be defined +to 0 to allow the optimizer to perform better optimizations. This function can +be called by all threads. +@end deftypefn + +@deftypefn Function {void} xth_lock (int @var{n}) +@end deftypefn +@deftypefn Function {void} xth_unlock (int @var{n}) +Lock/unlock lock number @var{n}. At least @code{MAXSEMAPHORS} locks must be +available. +@findex MAXSEMAPHORS + +Note that locks are used for very short fragments of code, so they need to be +fast; so spinlocks may be better than classical Dijkstra semaphores (although +this is untested). They are called once per calculated line/row during zoom and +once per approx 10 pixels during calculation of a new image. +@end deftypefn + +@findex MAXCONDS +@deftypefn Function {void} xth_sleep (int @var{n}, int @var{l}) +Expected to atomically unlock lock @var{l} and sleep in queue @var{n}. At least +@code{MAXCONDS} queues must be available. After the function is woken up, lock +@var{l} again. This mechanism is used by the new image calculation algorithm, +but it is designed to minimize its calls, so I expect it should be called once +or twice. +@end deftypefn + +@deftypefn Function {void} xth_wakeup (int @var{n}) +Wake up some thread from queue @var{n}. The lock used by sleep calls is locked +in this case. The function should wake up all threads if a single-thread awaken +is not supported by the host API. + +With luck, this function will not be called at all; it will be called by the new +image calculation routines when the queue is empty. This happens when there are +50 threads or thereabouts, but happens rarely at two or eight threads in my +tests. +@end deftypefn + +@deftypefn Function {void} xth_wakeall (int @var{n}) +Similar to wakeup but wake up all threads. +@end deftypefn + + +@node filters, algorithm ,xthreads ,Top +@chapter Filters + +This is a brief description of the filter system used internally by XaoS. +Filters in XaoS provide an object oriented interface to every part of the XaoS +engine. The main filters are the user interface implemented in ui_helper.c and +the zooming engine implemented in zoom.c. Active filters are kept in a queue --- +in the beginnning there are just two filters here (zoom and ui), but at any +later time additional filters (stereogram generation, and so on) can be inserted +into the middle of the queue. + +When calculating, every filter should use data calculated by the filter +immediately before it in the queue, which that filter placed into the image it +passes to its child. For example, the stereogram filter should take the fractal +generated by the zooming engine and create a stereogram from it (assuming that +the zooming engine is immediately after the zooming engine in the filter queue). + +This makes XaoS's code more flexible and makes future enhancements easy (perhaps +a different zooming engine, or image rotation, other special effects, plug-ins +or some other funny stuff) since the enhancements are forced to be decoupled by +the filter library, and since each filter has a degree of control over filters +that follow it in the queue. For instance, the stereogram filter should change +the palette, force the zooming engine to change the depth, width and height of +the calculated image to fit its needs, and so on. + +This document mainly describes the creation of a filter like the stereogram +generator --- i.e. a filter placed into the middle of the queue --- since I +don't expect there will be many people creating ``terminal'' filters (zooming +engines/user interface layers). Note that different user interfaces are +possible, since the user interface layer is not the real user interface, just a +set of high level functions that should be called by the main application, like +@code{set_view}. So if you want to use XaoS as a calculation engine in your +program this document is probably not for you. + +Each filter is defined by a @var{filteraction} structure, as follows:: +@findex filteraction +@example +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); +@}; +@end example +This structure describes unchanging parameters to the filter (like its name) and +a basic set of methods required for communication with the rest of XaoS. The +@var{name} field is a comparatively long description of the filter's name, such +as ``A random dot stereogram generator''. @var{name} is displayed by the ugly +interface in the Filters menu, so it is expected to be descriptive (but shorter +than 30 characters). The short name is a one word long name for the filter, like +``stereogram''. This name is used in save files and command line parameters; +everywhere that the user might need to write it, so writing a long descriptive +name would just be wasteful of time and disk space. + +The flags field is reserved for future enhancements and is expected to be 0 for +now. + +@section Instance creation / destruction + +Functions @code{getinstance} and @code{destroyinstance} are equivalent to the +constructor and destructor in object-oriented languages. @code{getinstance} is +expected to create and fill out the following structure: + +@findex filter +@example +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; +@}; +@end example +Although this structure seems to be long and complex, most of the fields are +currently unused, and the rest of them are filled out automatically by a helper +function: + +@deftypefn Function {struct filter *} createfilter (struct filteraction *@var{fa}); + +This function should be used to do the dirty work of instance creation and fill +out the @var{filter} structure. The only possibly interesting field is +@var{data}, a pointer reserved for the filter's internal use; it can be a +pointer to the filter's internal variables if required. This is what a +@code{getinstance} implementation that allocates such an additional structure +might look like: + +@findex getinstance +@example +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); +@} +@end example + +If nothing similar is required you can simply put @code{creatfilter} into the +@var{getinstance} field. + +@end deftypefn + +@code{destroyinstance} is expected to free the memory used by the filter +structure and all the filter's internal data. To free the filter structure use +the normal @code{free} call. An implementation of such function should look +something like +: +@example +static void destroyinstance(struct filter *f) +@{ + destroyinheredimage(f); + free(f->data); + free(f); +@} +@end example +The meaning of @code{destroyinheredimage} will be described later. + + +@section Initialization + +During the initialization phase, each filter says to its parent what kind of +images it supports (which should depend on the images that it's child has said +it supported), the parent chooses the best supported image format for its +purpose and gives that to the child (while passing that information on up the +queue of filters). Initialization is done in two passes: + +The first pass starts at the lowest filter in the queue (zoom, by default); each +filter passes a @var{requirements} structure to its parent. + +The second pass starts at the highest filter (the ui filter), and each filter +passes to its child an image and some other stuff. Then calculation should +begin. + +The queue needs to be reinitialized after creating, resizing, adding or removing +a filter, and similar operations. + +The first pass is implemented using the @code{require} function. This function +is expected to look at the child's requirements it received as a parameter, fill +out its own @var{requirements} structure, and call the @code{require} function +of its parent filter. +@findex requirements +@example +struct requirements @{ + int nimages; + int supportedmask; + int flags; +@}; +@end example +The @var{nimages} field should be set to 1 or 2. When it is 2, the parent filter +@emph{must} pass the image in two buffers (double-buffered). Note that if it is +1, the parent @emph{should} pass the image in two buffers, but is not required +to. + +@var{supportedmask} is a mask giving the image types supported by the +filter. Valid image types are: +@findex C256 +@findex FIXEDCOLOR +@findex GRAYSCALE +@findex TRUECOLOR +@findex TRUECOLOR24 +@findex TRUECOLOR32 +@table @code +@item C256 + A normal 8bpp image with palette +@item TRUECOLOR24 + A 24bpp truecolor image with 8 bits for each color. +@item TRUECOLOR16 + A 16bpp truecolor image +@item TRUECOLOR + A 32bpp truecolor image with 8 bits for each color. +@item LARGEITER + A 16bpp image, but without colors. The pixels are expected to hold an + iteration count; it could also be thought of as a 16bpp grayscale image. +@item SMALLITER + Similar to @code{LARGEITER}, but 8bpp. +@end table + +@findex MASK1BPP +If you don't want to worry about palettes, color allocations and so on, but just +want to do some non-display operation with a bitmap, you probably only care +about the image depth and not the precise meaning of the pixels; in that case, +you can use one of the bitmasks @code{MASK1BPP} for 8 bit images, +@code{MASK2BPP} for 16 bit and so on. + +The final field in the @var{requirements} structure is @var{flags}. It's a mask +composed from the following constants: + +@table @code +@item IMAGEDATA + Set this if your filter requires the data from previous frame untouched. When + this is not set, filters can reuse your image and change it. But some + filters, like motion blur or the zooming engine, require data from the + previous frame to construct the new one; for such filters, this flag should be + set. +@end table +There are no more flags supported at the moment. The @code{require} function +should also save the child's @code{requirements} structure into +@var{filter->req} for later use by the initialize pass. The code for a +@code{requirement} function might look like +@example +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*/ +@} +@end example +The next pass is the main initialization pass. It goes in the opposite order +(from parent to child, from the top of the queue to the bottom, in the same +direction as image flow), and the child receives some stuff from the parent +(such as images). The @code{initialize} function receives an @var{initdata} +structure: +@findex initdata +@example +struct initdata @{ + void (*wait_function) (struct filter *f); + struct image *image; + struct fractal_context *fractalc; + int flags; +@}; +@end example +@var{wait_function} points to a function called by the filter during calculation +that lets the parent filter (usually the user interface layer) inform the user +of calculation progress. @var{image} is an image expected to be filled with an +image in the calculation phase. @var{fractalc} is a pointer to a structure that +will contain information about the fractal itself during calculation (formula +type and so on). @var{flags} is a mask of the following constants: +@table @code +@item DATALOST + This is set if the data in the previous image was lost (if the image was + cleared or resized or freshly allocated). Filters that use data from previous + frames should pay attention to this flag. The zooming engine, for example, + recalculates the whole image if this flag is set, since all pixels from + the previous frame were lost. + Note that data will also be lost if the filter receives a different + @var{image} than in the previous initialization (since some filter before it in + the queue was removed). +@end table +Inheritance is carried out using these functions: + +@deftypefn Function void inhermisc (struct filter *@var{f},struct initdata *@var{i}); + +This function sets fields in the filter structure like @var{fractalc} or +@var{wait_func}. Inheritance of images is quite complex, since the new image +needs to be prepared for the child filter. In order to save memory it is highly +recommended to use the same image --- or at least the same memory --- for data +when passing to the child, but this is not allays possible. The following +function implements a heuristic to reuse the image where possible: +@end deftypefn +@deftypefn Function int inherimage (struct filter *@var{f},struct initdata *@var{data}, int @var{flags}, int @var{width}, int @var{height}, struct palette *@var{palette}, float @var{pixelwidth}, float @var{pixelheight}) +You should call this function in your @code{initialize} pass. It fills out +@var{image} and @var{childimage} in the @var{filter} structure, and prepares +@var{initdata} and @var{image} for the child. Note that in some cases it may +fail and return 0. In this case the filter is expected to interrupt +initialization and return 0 too. + +The @var{flags} parameter is a mask of the following constants: +@table @code +@item IMAGEDATA + Set if your filter requires data from the previous frame. +@item TOUCHDATA + Set if your filter touches data in the output image. This is the usual case, + but some filters, like interlace or subwindow, don't touch the image data at + all. +@item NEWIMAGE + Set if your filter cannot use the same image for output as it uses for input + (that is, if the two images must be distinct blocks of memory). +@end table +@var{width} and @var{height} are the width and height of the image you want to +pass to the child; it should be set to 0 if you want the same width/height as in +the parent image. @var{palette} is the palette of the image you want to pass; +set to @code{NULL} if the palette should be inherited from the parent's image +(as is usual). @var{pixelwidth} and @var{pixelheight} give the physical size of +a pixel in centimeters; if set to 0 they are inherit from the parent's image. +@end deftypefn + +If you use the @code{inherimage} mechanism, you must also call +@code{destroyinheredimage} in the @code{destroyinstance} function and +@code{updateinheredimage} at the beginning of the @code{calculate} function. + +Example implementation: +@example +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)); +@} +@end example +Also note that the fractal context holds a pointer to the fractal's palette. If +you don't change the image's palette everything is OK; but if the child's image +differs from the parent's, there should be two behaviors --- the fractal's +palette is the child's one (this is common in color conversion filters, going +from 8bpp to TrueColor and suchlike), or the fractal's palette is the parent's +one (like in the edge detection filter). By default the fractal's palette is set +to the parent's one, because this is most likely to be generally useful; +anything else requires explicit work from the parent to set up the child's new +palette. + +This can be changed by the @code{setfractalpalette} call, which has two +parameters --- the @var{filter} structure, and the new palette. When you pass +the child's palette as @var{palette}, the fractal's palette will be changed to +the child's. If you pass @code{NULL}, changing the palette will be disabled (as +in the motion blur filter in 8bpp mode). This is only changeable if you still +have access to the fractal's palette; some parent might have already redirected +the palette beforehand, in which case this function does nothing. + + +@section Calculation + +The calculation is done using the @code{doit} function: + +@deftypefn Function int (*doit)(struct filter *f,int flags,int time) + +This function is expected to call the child's calculation function when +required, and apply its filter to the child's output. + +The @var{flags} are mostly undefined; only @code{INTERRUPTIBLE} is defined for +now, and @emph{that} is mainly for the zooming engine so I do not describe it +here. Nonetheless, the filter is expected to pass the @var{flags} to its +child. Finally, @var{time} is the time in milliseconds that expired since the +last @code{doit} call. It can be used to calculate the animation speed, perhaps +in an attempt to keep the speed constant. + +@end deftypefn + +Calculation loops return a bitmask composed of the following flags: +@findex ANIMATION +@findex CHANGED +@findex INEXACT +@table @code +@item ANIMATION + Set if the filter performs some animation, and expects that its calculation + function will be called again soon. +@item CHANGED + Set if something changed in the output image (the usual case). +@item INEXACT + This is enabled by the zooming engine in @code{INTERRUPTIBLE} mode in case the + @var{time} was exceeded. +@end table + +Most @code{doit} functions change the image. The @var{image} structure contains +following fields that might be significant to filters: +@findex image +@table @code +@item bytesperpixel + Number of bytes per pixel (image depth). +@item palette + Palette of image. +@item currlines + Array of pointers to the beginning of each scanline in the image. +@item oldlines + Like @var{currlines}, but for the previous image, when double-buffering is + enabled. +@item nimages + Set to 2 when double-buffering is active. +@item flipimage + Pointer to a function that flips @var{oldlines} and @var{currlines}. +@end table + +The @var{palette} structure contains the following significant fields: + +@table @code +@item type + Type of palette/image (@code{C256}, @code{TRUECOLOR} etc...) +@item size + The number of allocated entries in the palette. +@item pixels + The array of allocated entries; a conversion table mapping from the iteration + number to a pixel value. +@item rgb + @sc{RGB} values for pixels (@code{NULL} for @code{TRUECOLOR}, @code{HICOLOR} + and similar paletteless types) +@end table + +To make writing calculation loops for different bit-depths easier, +@code{pixel8_t}, @code{pixel16_t} and @code{pixel32_t} are predefined. You also +can use preprocessor magic as the edge detection filter does; this lets you +write calculation loops just once, using @code{cpixel_t}, and the code will be +compiled for every bitmap depth. See the edge detection filter +(@code{src/engine/edge.c} and @code{src/engine/edged.c}) for implementation +details. + + +@section Coordinate conversion + +The @code{convertup} and @code{convertdown} functions are used for converting +screen coordinates to a position in the fractal and back. @code{convertup} +receives coordinates in the child's image, and is expected to convert them into +coordinates in the parent's image and call the parent's @code{convertup} +function. + +@code{convertdown} is the reverse of @code{convertup} (going from parent to +child). + +If coordinates correspond 1:1 you should use @code{convertupgeneric} and +@code{convertdowngeneric}; otherwise, the implementation should look something +like this: + +@example +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); +@} +@end example + +@section Filter removal + +Before the filter is removed from the queue, the @code{removefilter} function is +called. It is expected to clean up anything that the filter changed. + +In most cases, it should be left at @code{NULL}. + +@section Filter registration + +Once the @var{filteraction} structure is filled, the filter is ready, and you +should try to enable it. To enable it in the user interface you need to edit +@code{src/ui-hlp/ui_helper.c}, add the filter to the @var{uih_filters} +structure, and increase @var{uih_nfilters}. Note that the order of filters in +@var{uih_filter} defines the order of the filters in the filter queue. + +Then it is high time to start experimenting. + +Good luck! +@node algorithm, timerlib, filters ,Top +@chapter Algorithm description +The main idea behind XaoS is that it is not necessary to calculate the whole +image in every frame; most pixels were already calculated by 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 +flickers a bit and why points do not blink randomly as in recalculated +animations. + + This document describes some of the most important algorithms in XaoS: + @itemize @bullet + @item Saving Previous Pixels + @item Approximation Algorithm + @item Moving Pixels to New Positions + @item Calculating New Pixels + @item Symmetry + @item Calculation of Mandelbrot Set + @item Dynamic Resolution + @item Autopilot + @end itemize + +@section 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 the program Frang. It remembers all pixels as +triplets of (x,y,value), and when it builds a new image, it draws all +the pixels that it remembers to that image and then browses the image +and fills it with new pixels. (Possibly an @sc{rle} encoding should be +used for calculated pixels to conserve memory.) Frang actually uses an +algorithm that takes away pixels from the screen, so it behaves in +exactly the same way as the algorithm described here. On the other hand, +this method seems to require much more memory than XaoS' algorithm, and +drawing pixels/browsing the image costs quite a lot, so the algorithm +described here seems to be faster, since it never requires examining the +whole image, and the new image is constructed using block move +operations. + +For this reason, only the last generated frame is used as a reference. +This way the memory requirements are proportional to @math{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: The imaginary and real parts of the calculated image are not +precise, since they are the result of successive iterations of the +algorithm. In order to prevent errors from being propagated 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 calculated to fill in the +gaps in the frame. + +Obviously, much less work is done than in a brute-force calculation: +there are only @math{xsize + ysize} calculations instead of +@math{xsize * ysize}. So the main loop in XaoS looks like this: + @itemize @bullet + @item Make approximations for rows + @item Make approximations for columns + @item Move old pixels to their new positions + @item Calculate pixels for which there is no good approximation for + their row + @item Calculate pixels for which there is no good approximation for + their column, but there is one for their row + @end itemize + +@section Approximation Algorithm + + @unnumberedsubsec Introduction to problem + +You can see that the approximation algorithm is central to the +implementation of XaoS. If a 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, if doubling should happen (i.e., using an +old row or column more than once) the resolution will lower and the +image will look jagged. 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 @math{xsize + ysize} +values, but if its speed is proportional to @math{O(n^2)}, it can be +slower than a whole recalculation of the image. Speeds of @math{O(n)} or @math{O(n * log(n))} are acceptable. + + @unnumberedsubsec 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 + (@math{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 than 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 @math{step / 2.} +This caused a considerable slowdown so the limit was returned to @math{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 too 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): +@example + X1 X2 X3 X4 X5 X6 X7 +O1 O2 O3 O4 O5 O6 O7 O8 +@end example + +The normal algorithm will aproximate X1 by O2, X3 by O4 but nothing +more. For the algorithm with threshold step instead of @math{step / 2}: + +@example + O2 to X1 + O3 to X2 + O4 to X3 + O5 to X4 + O6 to X5 + O8 to X6 +@end example + +But this will fail with X7. The second algorithm which relies on lower +values will do the following: + +@example + O1 to X1 + O3 to X2 + O4 to X3 + O5 to X4 + O6 to X5 + O7 to X6 + O8 to X7 +@end example + +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. + + @unnumberedsubsec 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 exactly define the ``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 @math{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 @math{(4 * step) +* (4 * step)}. This means that the approximation is acceptable when +@math{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 +@math{length < n} to make a guess at the length of @math{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 +the previous column: Try new position n. Calculate the price and add the +best approximation for the previous (row/column 1) that uses a new +position lower than n (thus prohibiting doubling or swapping). This +should be one of 8 positions or (eventually) adding a 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, @math{9 * n} steps are required and n steps to +backtrack to the best approximation. The only problem is that this +algorithm is still a little slow (chiefly because of slow memory access +on the 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 a real +problem. The last optimization made was based upon the fact that added +rows/columns do not have the exact real and imaginary components +calculated by (@math{beginning + x * step}) but lie at the average of +their 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 of this algorithm is that adding new +rows/columns into their ideal positions could cause misordered results, +since some rows/columns could be off more than the distance between +them. To avoid this, I use an algorithm that always examines the start +and end of a block of new rows/columns and linearly interpolates the +value between them. Special care needs to be taken with the blocks that +start at the beginning or finish at the end. + +Implementation should be much faster using custom fixed-point +routines --- first recalculate values such that 0 means start of image +and 65536 means end. Than calculation is much cleaner. Values <0 and +>65536 are off screen, calculation is independent of scale, and many +things should be recalculated --- like tables for calculating price from +distance. Also dividing the main loops into many specialized parts and +avoiding filling unnecessary parts of tables helps. So current algorithm +in XaoS is about 5 or 6 times faster than first naive implementation. + +@section Moving Pixels to New Positions + +Since XaoS is using the approximation algorithm the following table is +filled for every row/column: + @itemize @bullet + @item calculate + @item oldpoint + @item position + @end itemize + +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 of 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 by about four times and made this function +so fast that it is no longer a problem. (In fact, it takes much less +time than all other parts of XaoS.) + +@section 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 can traverse the whole set +and 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 no +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. + +@section 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. + +@section Calculation of the Mandelbrot Set + +The internal Mandelbrot calculation loop is unrolled --- it calculates +the first 8 iterations using the normal method, and then it expects that +number of iterations will probably be large, so it switches into a mode +where it calculates iterations in blocks of 8 with one bailout test at +the end. When the bailout is attained, saved values from previous +iterations are restored and the last 8 iterations are recalculated slowly +to get exact values. This especially helps on the Pentium, where +conditionals in floating point code are slow. + +Another stuff is periodicity checking. XaoS has loops with and without +periodicity checks. In most cases it uses the no-periodicity-checking +version. The periodicity check version is used just in the case where +some inside-set pixel has been found during the solid guessing +phase. This is done mainly because the periodicity checking version of +the loop is significantly slower. + +@section 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 simply approximated by referencing the +nearest 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 a priority to every row/column and +calculating the high priority row/column first. The algorithm for adding +these priorities is as follows: +@itemize @bullet + @item Find middle row/column of uncalculated block. Priority is the size + of the block (in floating point coordinates) + @item Start function for left block and right block +@end itemize + +This function produces quite good results. It tends to make same-sized +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 the center of the zoom anyhow. + +This is done by simply adding to the calculated priority +@math{normal_priority / (abs(newposition - oldposition) / step + 1)}. This +prefers rows/columns that do not move a great deal. (Of course, +unzooming uses the reverse of this formula.) + +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 +this indicates a framerate lower than 15FPS, 15FPS is used instead, since +slower animations are unacceptable. On the other hand, if it is higher +than 35FPS, it is set to 35FPS, since a higher framerate than that is +just wasting computer resources. When the image is not animating, this +value is changed, so a framerate between 5FPS and 15FPS is selected. This +ensures that images are calculated quickly after zooming stops. + +@section 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. It also detects oscillations / vacillations and breaks them. + +The current implementation also does detection of out of range numbers; +randomly chosen points are chosen near the old one, to avoid frequent +changes of direction. + +@section SMP support +Since version 3.0 XaoS supports SMP. This is done using threads. Most of +XaoS routines should be threaded easily --- for example +@code{moveoldpoints} just divides image into @math{n} equal parts and +each part is computed by one processor. The only unthreaded part is the +realloc table calculation routines. I don't see any way to paralellize it +except for calculating both @math{x} and @math{y} approximations +simultaneously (using two processors). Another interesting algorithm to +parallelize is boundary trace; see the comments in +@code{src/engine/btrace.c} for discussion of the current implementation. +The only problem I see in the current implementation is the possibility +that calculation is divided into too many parts (realloc tables, move +points, calculate, symmetries, dynamic resolution) causing too much +synchronization between each part. So this may be too slow on a real SMP +box. + +@node timerlib, registry,algorithm ,Top +@chapter The timer library + +Timer library is a library originally written for timing in XaoS; but I +found it useful in many other programs (like demonstrations, games, +animation players and 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 are many ways to design a timed application (such as a game) + +@enumerate +@item +Read user input, move baddies, display and loop again. + +This way has one disadvantage; the speed of game depends on the speed of +the computer. This was acceptable in olden times where the only +processor was the Z80 :) but now with a wide variety of hardware with +widely differing speeds such a loop is unacceptable. + +@item +Read user input, measure time since last loop and calculate step for +baddies, move baddies for set step, display and loop again. + +This way fixes the problem with speed. But moving baddies just for +calculated step, that should differ a much is quite complex, usually +introduces complex calculation, floating/fixedpoint math and other +unnecessary stuff that makes program long and introduces many bugs. + +@item +Set a fixed framerate that is high enough to make the game smooth but low +enough to do the whole internal loop in time. The internal loop then +looks like this: read user input, move baddies, display, measure time +spent in loop, sleep until next frame. + +This is quite a popular scheme but has another disadvantage --- game can +not be designed to use the whole CPU power, since on slower computers +internal loop would longer than is available for one frame, so the game +will run slowly again. + +@item +To take away disadvantage of previous method, many games time just the +moving of baddies and user input. Other stuff like displaying should be +done in the `untimed' rest of the time. In DOS games moving and user +input is often done in an asynchronous interrupt and drawing runs as the +main loop. This solves the case where the drawing of the game takes a +significantly longer time than the moving of baddies. This is quite +common so this scheme works well. + +@item +The previous scheme still has one problem --- since the timer interrupt +works asynchronously, there could be many race conditions: if moving +takes a longer time than the time reserved for it, the computer can +crash. So this scheme should be enhanced into a synchronous one with +exactly the same result but avoiding the problem with race conditions: + +Read user input, measure the time spent by the loop and calculate how +many simulated frame interrupts were activated since last activation: if +zero, sleep until simulated interrupt, move baddies as many times as +required, display, and loop again. + +This is a combination of 4 and 3 and seems to be the most comfortable way +for writing games, but since the main loop is now quite complex many +games don't do that. + +@item +there is still one small problem. Method 5 expects that moving takes a +significantly smaller time than displaying. This may not be the truth. A +simple work around is to write a moving routine that should move for +@math{x} moves in a faster way than calling move @math{x} times. This is +often possible, and makes extension to scheme 5 easy. This scheme allows +you to use a very large maximal framerate (say 100FPS) and to have the +same results as method 2 (which is the maximally exact method) +@end enumerate + +As you can see, designing the main loop isn't so easy. This is just a +very simple example: a more advanced application might want to move one +set of baddies at one framerate and another at a different +framerate. This requires two such timings. Another complication is that +there are many different ways to measure time exactly on different +platforms. Under Linux you can measure using @code{gettimeofday}, but +under DOS this is exact to just 1/18 of second and thats too low for +smooth animation, and so on. + +That's why I decided to design a portable easy to use timer library, that +makes it easy to implement all methods described above, combinations of +them, and much more. During the design I took care of the following +things: quality of timing, how easy to use it is, speed, portability and +to minimise unexpected situations (like race conditions in asynchronous +interrupts and so on) + +@section The name of the game + +The timer library operates with @dfn{timers}. They should be created, you can +measure time since last reset, pause them or set @dfn{handler} and +@dfn{interval}. But handler is not yet activated at the given interval. Since +timer library is not asynchronous, you must activate them yourself. + +For activating @dfn{groups} are used. You should process a group at some place +in your program, whereupon all timers in the group are checked and their +handlers activated if required. When the time spent since last activation is +higher than the interval, the handler is activated more than once. Also, the +interval to next invocation is calculated to keep frequency. Simple scheduling +is performed for handler --- handler is activated just once and then all other +timers are checked before it is activated again. You can also define a +multihandler --- a handler that is activated just once and receives as an +argument a count of intervals. + +There are two special groups --- @code{asyncgroup}. Timers in this group are +activated asynchronously (as though they were called from interrupts). Thisis +not recommended, since the asynchronicity brings many problems and usually isn't +required. Also it does not work on many platforms. @code{syncgroup} is the +default group. The program is expected to process it quite often. If you don't +need to use more than one group, 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 @code{tl_updatetime}. I did this in +order to minimize context switches, but later I found this scheme very useful, +since you normally look up the timer, do something and then reset it and don't +want to worry about any time spent between lookup and reset. This helps to keep +frequency of timers exact w/o any errors caused by such situations. At the other +hand you need to call @code{tl_updatetime} at least once in your main loop. + +Maybe you don't know why you'd want to create more groups, but I found it quite +useful. For example, an autopilot in XaoS has such a special group --- I need +to call it approx. every 1/20 of second, but just at one place in the +program. Invocation of the autopilot when calculation is active would produce +incorrect results, so I have a special group for autopilot and process it in +just one place where I am sure it is safe. + +Timers can also be emulated. You can stop them and then control the flow of time +for given timer. This should be quite useful; for example, when you want to +precalculate animation at a given framerate. + +To control a group of timers, you can create @dfn{emulators}, which are just +other timers controlled by you. They are useful in cases where you want to +emulate fixed framerates (for animation rendering) or suchlike. + +@section Time functions + +@deftypefn Function void tl_update_time (void) +Update time used by timerlib. This must be called at least once in the main loop +otherwise time will not flow. See above. +@end deftypefn +@deftypefn Function void tl_sleep (int @var{time}) +Sleep for the given @var{time}. Similar to @code{usleep} in @sc{POSIX}. +@end deftypefn +@section Group functions + +@deftypefn Function tl_group* tl_create_group (void) +Allocate and initialize the group header. Returns @code{NULL} when @code{malloc} fails. +@end deftypefn +@deftypefn Function void tl_free_group (tl_group *@var{group}) +Free memory storage used by group structure. +@end deftypefn +@deftypefn Function int tl_process_group (tl_group *@var{group}, int *@var{activated}) +Process timers in @code{group} and activate their handlers. Returns time until +next invocation; the main loop should sleep for that long. The @var{activated} +parameter is either @code{NULL}, or a pointer to a variable that is set to +the number of activated handlers. +@end deftypefn +@section Timer functions + +@deftypefn Function tl_timer* tl_create_timer (void) +Create timer structure. +@end deftypefn +@deftypefn Function void tl_free_timer (tl_timer *@var{timer}) +Free memory storage used by timer structure. +@end deftypefn +@deftypefn Function void tl_reset_timer (tl_timer *@var{timer}); +Reset timer to current time (the time of last actication of @code{tl_update_time}). +@end deftypefn +@deftypefn Function int tl_lookup_timer (tl_timer *@var{timer}); +Return time since last call of tl_reset_timer or last activation of handler. +@end deftypefn +@deftypefn Function void tl_set_interval (tl_timer *@var{timer}, int @var{interval}); +@end deftypefn +@deftypefn Function void tl_set_handler (tl_timer *@var{timer}, void (*@var{handler}) (void *),void *userdata); +@end deftypefn +@deftypefn Function void tl_set_multihandler (tl_timer *@var{timer}, void (*@var{handler}) (void *,int),void *userdata); + +Handler, multihandler and interval control functions +@end deftypefn + + +@deftypefn Function void tl_add_timer (tl_group *@var{group}, tl_timer *@var{timer}) +Add timer to given group. A timer should be in only one group. +@end deftypefn +@deftypefn Function void tl_stop_timer (tl_timer *@var{timer}) +@end deftypefn +@deftypefn Function void tl_resume_timer (tl_timer *@var{timer}) +Stop and resume timer. +@end deftypefn + +@deftypefn Function void tl_slowdown_timer (tl_timer *@var{timer},int @var{time}) +The time in the timer is moved back to the given time. +@end deftypefn + +@section Emulator functions +@deftypefn Function struct timeemulator *tl_create_emulator (void); +This function creates new a emulator --- you need to create one first before +emulating. +@end deftypefn +@deftypefn Function void tl_free_emulator (struct timeemulator *@var{t}); +Destroy emulator's data. +@end deftypefn +@deftypefn Function void tl_elpased (struct timeemulator *@var{t}, int @var{elpased}); +Move emulated time. +@end deftypefn +@deftypefn Function void tl_emulate_timer (struct timer *@var{t}, struct timeemulator *@var{e}); +Set timer to the emulated mode; the passage of time is now controlled by the +emulator @var{e}. All other behavior of timer keeps unchanged. +@end deftypefn +@deftypefn Function void tl_unemulate_timer (struct timer *@var{t}); +Disable emulated mode for the timer. +@end deftypefn +@section Example main loop + +@example +while(1) +@{ + time=tl_process_group(syncgroup,activated); /*Call game control functions*/ + update_keys(); + if(activated) /*something changed*/ + display(); + else tl_sleep(time); +@} +@end example + +@node registry, index,timerlib ,Top +@chapter XaoS function registry + +XaoS has an ui helper library, which provides functionality used by the user +interface. All its useful functions are registered into a central registry. +This registry is used to generate menus and dialogs as well as command line +options or scripting language; so it is a very significant thing in XaoS design. + +This is not just useful for those who want to hack XaoS ui-helper layer, but +also for authors of drivers, who can use this to add new driver dependent +functions into XaoS's menu. The external user interface is also based on the +registry. The main idea behind external user interfaces@footnote{currently one +for Tcl/Tk and Gtk is under development} is this: XaoS transfers its registry to +the interface (using asimple description language). The user interface starts +XaoS in its window and builds menus and dialogs based on the registry. Then, +once user selects some function, the user interface creates a command in XaoS' +scripting language and sends it back to XaoS' engine. + +Knowledge of this part is thus essential for many developers. Please pay +attention. :) + +The implementation of the registry is in @code{xmenu.c}, and the header is +@code{xmenu.h}. For historical reasons, it talks about menus and dialogs (it was +originally designed for the GUI). I am keeping this terminology, since it is +quite clean and easy to understand instead of talking in some cryptic abstract +terms. + +@section Function description + +To add a function into the database, you need to put a description into the +@var{menuitem} structure. It has the following definition: + +@findex menuitem +@example +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; +@end example + +@defvar menuname +Name of menu (or category) the function belongs in. The root of all categories +is called @code{"root"}. XaoS also uses an @code{"animroot"} when animation +replay is active. If you are adding a function, it is better to add it into some +subcategory like @code{"ui"} (which will place it into the UI menu) or to create +a new category for your functions, which will appear as a submenu of the main +menu in the UI. +@end defvar + +@defvar key +@sc{ASCII} code of the hotkey that activates this function. Use @code{NULL} if +none. +@end defvar + +@defvar name +Longer name of the function, used in the menu entry, or @code{xaos --help} +listing. +@end defvar + +@defvar shortname +One-word name of function used in command language and other references to +the function. +@end defvar + +@defvar type +Type of function --- this is @emph{not} the return type. @var{type} should be +one of the following constants: +@table @code +@findex MENU_SUBMENU +@item MENU_SUBMENU + A submenu. This is not a function, but a name for the submenu. You can fill + in the @var{key}, @var{name}, and @var{shortname}. The name of this new + submenu is placed in the field @var{pparam}. +@findex MENU_NOPARAM +@item MENU_NOPARAM + A normal function without any parameters. When activated, + @var{function} will be called with a pointer to @code{uih_context} as its + parameter. +@findex MENU_INT +@item MENU_INT + This should be used to simplify entering of many similar functions (handled + by just one universal function in the C code). The @var{function} is handled + in the same way as @code{MENU_NOPARAM}, but also one integer parameter taken + from @code{iparam} is passed in. +@findex MENU_STRING +@item MENU_STRING + Similar to @code{MENU_INT} but uses a string instead of an integer. +@findex MENU_DIALOG +@item MENU_DIALOG + If your function needs some paramters, use the dialog structure to describe + them. In the scripting language your function then have parameters; in + the user interface, a dialog will be displayed. @var{pparam} must point + to array of dialog entries (writing them will be described later). + If your function has just one parameter described in the dialog structure, it + will be called in the normal C way --- if you want a string parameter, one + pointer pointing to a string (in addition to @code{uih_context}) will be + passed to the functions. + + If multiple parameters are requested, it is impossible to call + function in a C way without a special wrapper for each case. So it will + receive a pointer to an array of @code{dialogparam} unions, wich contain + one entry for each parameter. @code{dialogparam} is declared as follows: +@example +typedef union + @{ + char *dstring; + int dint; + number_t number; + number_t dcoord[2]; + xio_path dpath; + void *dummy; + @} +dialogparam; +@end example +@findex MENU_CDIALOG +@item 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 the function @var{dialog} is called first, and it is expected to + return a pointer to the correct dialog structure. The dialog structure must + lie in static storage (since it is not freed), and must always have the same + fields, and differ only in the default values. + This function must also work correctly even when the pointer to + @code{uih_context} is @code{NULL}, since it is often called in the + initialization stages (parameter parsing etc.) +@end table +@end defvar +@defvar flags +The @var{flags} are used to set additional information about the function: +@table @code +@findex MENUFLAG_CHECKBOX +@item MENUFLAG_CHECKBOX +Some features act like check-boxes --- i.e. repeated calls to the function +toggle the features. In menus it is useful to add a check-box for this function +indicating whether the feature is on or off. This flag adds such a check-box. + +So that the UI can determine the current state of the checkbox, you need to +define the function @var{control}, which returns @code{1} when enabled and +@code{0} when disabled. In order to let external GUIs work correctly you also +need to call @code{uih_updatemenus("name")} every time the state of this +function changes. + +In the scripting language, this adds a single parameter, either @code{#t} or +@code{#f}. The engine then calls the function only when necessary. When +@code{#t}, a dialog is requested; when @code{#f}, the function is called just as +@code{NOPARAM}. I.e. the dialog is displayed only when enabling the feature. + +@findex MENUFLAG_DIALOGATDISABLE +@item MENUFLAG_DIALOGATDISABLE +Display dialog on disabling of this checkbox feature, instead of on enabling. +@findex MENUFLAG_RADIO +@item MENUFLAG_RADIO +Other features act like radio-buttons. Control functions in this case receive +the same parameter as is defined for @code{MENU_INT} or @code{MENU_STRING} +types, and is expected to return @code{1} when enabled and @code{0} +otherwise. You also need to call @code{uih_updatemenus} when the value is +changed. No special parameter is added in the scripting language. + +@findex MENUFLAG_INTERRUPT +@item MENUFLAG_INTERRUPT +Interrupt current calculation when this function is called (used by functions +with cause recalculation of the screen) + +@findex MENUFLAG_INCALC +@item MENUFLAG_INCALC +By default XaoS queues functions and calls them later when they are activated in +the calculation. This flag disables this feature. + +@findex MENUFLAG_ATSTARTUP +@item MENUFLAG_ATSTARTUP +By default XaoS queues functions and them calls later when they are activated as +command line parameters (in case the engine is not fully initialized yet). This +flag disables this feature. + +@findex MENUFLAG_NOMENU +@item MENUFLAG_NOMENU +If set, the function will not be visible in the menu. + +@findex MENUFLAG_NOPLAY +@item MENUFLAG_NOPLAY +If set, the function will not be available as a command in scripts (and therefore +won't be usable by external GUIs). + +@findex MENUFLAG_NOOPTION +@item MENUFLAG_NOOPTION +If set, the function will not be available as a command line option. +@end table +@end defvar + +@section Initializing the menuitem structure as a static variable +In most cases, menuitems should be written as static variables. Because the +contents of this structure could change in future, please use one of the macros +defined in @code{xmenu.h}. They provide a cleaner and easier to extend way to +define these entries than does doing it by hand. + +For example to define a @code{MENU_NOPARAM} function, use the following macro: +@defun MENUNOP (menuname, key, name, shortname, flags, function) +@end defun +Similar macros exist for other types too. They end in @code{CB} or @code{RB} for +check-boxed or radio-box functions. See @code{src/ui-hlp/menu.c} for a large +number of example definitions. They should look like this: + +@findex menuitem +@example +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), + ... +@end example + +@section Dialog description +A dialog description is similar to a menuitem. It is an array of the following +structures: +@example +typedef struct dialog + @{ + char *question; + int type; + int defint; + char *defstr; + number_t deffloat; + number_t deffloat2; + @} +menudialog; +@end example +It is terminated by an element with the @var{question} pointer set to +@code{NULL}. + +The @var{question} contains the string the UI should display when it asks for +this field. + +@var{type} should be one of the following values: +@code{DIALOG_INT}, @code{DIALOG_FLOAT}, @code{DIALOG_STRING}, +@code{DIALOG_KEYSTRING} (the difference between string and keystring is that +in the scripting language string is passed as @code{"hello"}, but keystring is +passed as a Scheme keyword: @code{'hello}), @code{DIALOG_IFILE} (input file), +@code{DIALOG_OFILE}, @code{DIALOG_CHOICE} (choice between different +keystrings), @code{DIALOG_ONOFF} (boolean parameter), @code{DIALOG_COORD} (two +floats --- a complex number) + +Set the corresponding @var{def*} field to set the default value. In the case of +files, use a string in the format @code{"@var{[prefix]}*@var{[extension]}"}. For +type @code{DIALOG_CHOICE} set @var{defstr} to a pointer to an array of strings, +terminated by a @code{NULL} entry. + +To write dialog structures, as with menus, use macros defined in @code{xmenu.h} +like: +@example +DIALOGSTR(question,default) +@end example +The definition should look like: + +@findex menudialog +@example +static menudialog uih_viewdialog[] = +@{ + DIALOGCOORD ("center:", 0, 0), + DIALOGFLOAT ("Radius:", 1), + DIALOGFLOAT ("Angle:", 0), + @{NULL@} +@}; +@end example +@section Modifying the registry +@deftypefn Function void menu_add (menuitem *@var{item}, int @var{n}); +Add an array of @var{n} items to the database. +@end deftypefn +@deftypefn Function void menu_delete (menuitem *@var{items}, int @var{n}); +Remove an array of @var{n} items from the database. +@end deftypefn +@section Querying registry +@deftypefn Function menuitem* menu_findkey (char *@var{key}, char *@var{root}); +Find item for given key. @var{root} is menu to start (submenus are searched +recursively). +@end deftypefn +@deftypefn Function menuitem* menu_findcommand (char *@var{name}); +Find item for given short name. +@end deftypefn +@deftypefn Function char* menu_fullname (char *@var{menu}); +Return a long name for a menu, given a short name. +@end deftypefn +@deftypefn Function menuitem* menu_item (char *@var{menu}, int @var{n}); +Return the @var{n}th entry in the @var{menu}. Return @code{NULL} if that entry +does not exist. +@end deftypefn +@deftypefn Function int menu_enabled (menuitem *@var{item}, struct uih_context *@var{c}); +Check whether the given item is activated (for check-boxed and radio-boxed +functions). +@end deftypefn +@deftypefn Function int menu_havedialog (menuitem *@var{item}, struct uih_context *@var{c}); +Return whether this function has an associated dialog. +@end deftypefn +@defun menu_getdialog (@var{context}, @var{m}) +This macro returns a pointer to the dialog structure for a given menu item. (If +the item doesn't have a dialog, garbage is returned). +@end defun +@deftypefn Function int menu_available (menuitem *@var{item}, char *@var{root}); +Check whether an item is available as one of the entries of @var{root} (or it's +submenus) +@end deftypefn + +@node index, , registry, Top +@c node-name, next, previous, up +@unnumbered Index of functions, variables, types and constants + +@printindex fn + +@contents +@bye -- cgit v0.9.1