vII Graphity Help/Documentation (version 0.21)

Contents
1.Introduction/Purpose
2.Basic Usage
2.1 Getting started
2.2 Menu Commands
2.3 Option Settings
3.Effects/commands table
4.History
5.Plans/Future/Missing Things
Contacting the author

1.Introduction/Purpose
As I've seen Cthugha the first time, I was fascinated by the everchanging patterns on screen and the influence of the music on the graphical patterns. With the addition of mixing pre-loaded images into the graphical output it even became a bit like the video clips we know from TV. But here also the main fault of the program got obvious: pure randomness becomes boring with the time, even if there's no repetition. So now with BUZZ it should be possible to add creativity again and allow to control graphical output equally as the music is controlled by the BUZZ patterns.

I intended to do a complete Cthugha port as a start, but because I'm too lazy (or too busy) for this, I started my machine from scratch, and hope it's nonetheless useful already in the present state: as image viewer for slide-show like things without many graphical effects yet. I based it on DirectDraw for better performance, but had some problems with the fullscreen-modes, which strangely seem to influence the sound output quality of BUZZ, so in the moment it's windowed only, and all those fine palette animating tricks of Cthugha will be impossible (or only much harder?).

For image storage I had the options of always loading them as bitmaps, so they would have to be bundled with the song, or to store them as "wave" with the song, which I prefered. But this way the songs may become very big: I don't use any compression yet and storing a 320x200 bitmap with 24bits color already needs 200k, paletted images on the other hand don't work perfect yet. The images are stored temporary in a file buzztemp.bmp, which may be left behind on your HD. You can savely delete this one (or use it as image-rip until I add an "image save" feature)

Most implemented blit effects are just an interface to the DDraw blit routines, so they may depend on the graphic card and driver, because not everything will be emulated by DDraw. So unfortunately the screen output may vary from PC to PC :(

2.Basic Usage
The machine is an effect machine designed to allow receiving of sound input, so you have to put the DLL into the Gear/Effects directory. You have to connect input and output and some sound has to come in, otherwise it won't be activated by BUZZ (at least for some of the vGraphity modes, so better always care). It's output is pure silence, so it shouldn't change the sound of the song anyway (beside from artefacts due to higher CPU usage).

You can have more than one vGraphity machine in the song, all accessing the same output window, but you should connect them parallel or set the "sound through" option in all but the last machine (because otherwise there will be no input sound, which may prevent the machine from working as expected). Also with more than one machine the order of processing them may be of importance (for instance erasing the screen with one machine and drawing something with another), but I have no influence here: it seems to be always the order the machine were created. Maybe I can add some reorder option to m2buzz if this seems to be necessary here. All coordinates, zoom factors and colors, which are remembered by the machine, are independent for every machine. But the basic modes (resizable/fixed window) are the same for all.

2.1 Getting Started
You have to decide between one of two modes: either a resizable window (default, compatible to vGraphity 0.11), where you can access windows of any size (that is less than 0x2000 ;) and have some extra (graphic card dependent) blit modes, but none of the (growing number of) image processing effects you get in the other mode: fixed window size (320x200 recommended because of performance reasons), switchable to fullscreen mode (right mouseclick). Against my primary plans 16Bit color mode is prefered in the moment (mainly because windowed and fullscreen mode are the same here): be aware that a lot of the effects won't work for less or more colors.

Look at the demo song or just load some bitmaps from the machine menu. Some explanations about the single columns are given in the following table:

column | explanations/remarks
wave slot number | If you put a number here, anything you loaded with the machine into BUZZ may be used: bitmaps, text files or translation tables. Using zero as wave number deletes the complete window contents and fills it with the given RGB color (erase screen/window). bitmaps:Set the wave number where a bitmap is stored in the waveslot column and it should be displayed (with the left top corner at the specified X and Y coordinates). For scaling use the effects 0x0006,0x0007 or 0x0008. If at least one of the RGB columns contains a number, the given color will be used as source transparency key, that is: this color will become transparent. text files: After loading any standard text file, you can show the first line of text by giving the corresponding wavenumber here. The actual color and coordinates are used. Set the text height with the command 0x0061 and change the text line number with 0x0062. translation tables: You can also load translation tables from DOS-Cthugha or Cthugha97 (not from Cthugha for Winamp or some Linux Cthugha versions; a table has to be exactly 130,560 bytes). These tables allow a lot of nice effects for the 320x200 fixed window mode: they just give the source point for every pixel after the transformation, there also exist several programs to create these tables. Just use the wave number where you stored the table, and the transformation will be done. This column is always processed behind the others (that is all effects, coordinates, colors already apply here), so if I ever make a new incompatible version, this column will become the rightmost.
X/Y coordinates | You can set the coordinates in different ways: a) absolute coordinates: 0...0x2000 ->positive values (0x2000=8192, should be large enough) 0x2001...0x4000 ->negative values (-0x1fff...0) b) relative coordinates: 0x4001...0x4800 ->dx=1...0x800 0x4801...0x4fff ->dx=-0x7ff...-1 The actual values will be remembered by the machine (comon for all tracks!) and used in case there's no coordinate given, for the relative coordinates or for commands needing two coordinates (line drawing). Exception is the "line to" command, where the older coordinates of the starting point are remembered instead.
Red/Gree/Blue | In most cases you simply set an RGB color here. This color is used for several commands: erase window, color fill, pixels, lines or as transparency color for bitmap blitting,... To have an additional value for the default dots ("..") I've always mapped the maximal value of 0xfe to become 0xff. (In 16bit color mode there is no difference: only 5 or 6 bits are used for one color component, so 0xfe or 0xff give the same color). Some commands (0x0110...0x0113) use these columns for color shifts with a different format. The color values aren't remembered in these cases.
Effect/Effect data | look into the effects table

Most intern variables (X,Y,Red,Green,Blue, X and Y zoom factors,...) are common for all tracks (in one machine), this way you can set X and Y coordinates in the first track and use them as start values for a line in the second track. It should/will also be possible to accumulate effects to apply at once for one image this way. On the other hand this complicates some things (like doing 2 independent things at once, but this is possible with using several machines) and may give a lot of tracks.

2.2 Menu Commands
Open Window/Refresh: Here you open the window for the graphical output. If it's already open, only the images in memory are synchronized with those stored in the wavetable section. This is necessary to actually delete an image from memory you deleted from the wavetable (and even more after deleting a text file or translation table: BUZZ will crash if you try to use a deleted table and I have no idea how to prevent this).

Load Bitmap/Text/Translation table: You can load any standard bitmap here, but non-paletted ones are recommended. They are stored in the wavetable section of BUZZ (in the first available free wave slot)and additionally loaded into an offscreen DirectDraw surface. Additionally you can load translation tables from DOS-Cthugha (have to be exactly 130,560 bytes) or standard text files.

Options: see below

2.3. Options
There are 2 groups of options: global options, which apply to all machines in the song, and machine specific options. For most options to take effect you have to close and re-open the graphics window.

Global options:

- graphics window title: Chose if you want to see a window caption in the windowed modes, you can change it in the line below.
- always on top: This option is recommended.
- window type: You may either use a resizable window, which may be as large as you want (that is <0x2000) and is compatible to vGraphity 0.1/0.11, or a fixed window with the size given in the window size field. The resizable mode additionally allows some more graphic card dependent blit modes (especially effects 0x0001 and 0x0004), while the fixed window mode introduces the effects above 0x0100 and translation tables. Later there may be another fixed size mode, centered in the middle of a resizable one (looks better) and an option to ask for fullscreen mode automatically at startup. You can switch to fullscreen mode in all other modes with a right mouseclick in the window (another left or right click switches back again), but even for the resizable window you are restricted to the set window size and color depth. But the remarks about the possible effects also apply to a mode switched to fullscreen.
- autoshow bitmap: This can either be -1 to show the first available image, 0 to show nothing or the number of a wave slot with the bitmap you wish to show at startup after loading of the song.

Machine specific options:

- write always direct to screen: This option is only useful if you have the fixed window option on. Without this option in fixed window mode an offscreen image is used for drawing everything and applying any effects and will transfered to the (visible) screen/window after. You can now chose to write with this machine directly to the screen AFTER the offscreen image has been transfered. Everything you do here in one row will automatically be overwritten the next, so this is very usefull for some animation-like things or text scrolling (but not very smooth ). Of course none of the offscreen effects will apply here (you neither should use them in this machine), but neither the graphic card dependent blit options.
- sound through: passes all input samples to output, especially useful for putting several vGraphity machines in a row
- MIDI: If activated you can trigger bitmaps, text files or translation tables with MIDI note-on commands on the given MIDI channel. The parameters for coordinates and color can be controlled with the standard BUZZ MIDI controller interface. Controlling the effect parameter would change the proportional bitmap scaling factor.

3. Effects/commands table

Setting effects data without an effect is equivalent to effect 0x0006 (zoom X and Y), this may be useful for MIDI input ;)

vGraphity Effects | Effect/Command | Description | Data | Remarks
0x000x | Bitmap blit effects | * | * | *
| 01:Mirror/Rotate |  | 1: rotate 90° 2: rotate 180° 3: rotate 270° (-90°) 4: flip horizontal 5: flip vertical | these mostly work only for direct blit to screen (they aren't emulated) -> non-fixed window only, graphic card dependent
| 03:Color fill | fills bitmap retangle with RGB color | - | uses the actual RGB values
| 04:ROP | uses given raster operation | 0: SRCCOPY,dest=dest 1:SRCPAINT,dest=src OR dest 2: SRCAND,dest=src AND dest 3:SRCINVERT, dest=src XOR dest 4:SRCERASE, dest=src AND (NOT dest) 5:NOTSRCCOPY, dest=NOT src 6: NOTSRCERASE, dest=(NOT src)AND (NOT dest) 7: MERGECOPY,- 8: MERGEPAINT, dest=(NOT src) OR dest 9:PATCOPY,- 10:PATPAINT,- 11:PATINVERT,- 12:DESTINVERT, dest=NOT dest 13:BLACKNESS, dest=BLACK 14:WHITENESS, dest=WHITE | these mostly work only for direct blit to screen (they aren't emulated) -> non-fixed window only, graphic card dependent they also don't seem to work together with image scaling for me :(
| 06: scale proportional 07: scale horizontal 08: scale vertical | scales image | 0x1000 -> scale 1.0 (no scale) | The actual horizontal (X) and vertical (Y) zoom factors are always rembered for the machine, so you need to set them only if you want to change them.
0x002x | pixel commands | * | * | *
0x0020 | set pixel / square airbrush |  | 0x0001: set one pixel 1...0x0040: width of "Airbrush" square | setting a lot of pixels with these commands causes heavy CPU usage and often disturbs sound output, better let the argument be less than 20
0x0021 | set pixel/ round airbrush |  | 1...0x0040: radius of "Airbrush" circle | as above
0x004x | line commands | * | * | *
0x0040 | draw line (updates x,y coordinates) |  | line thickness | you normally need 2 tracks for line drawing, the first for the start coordinates X and Y (if they aren't already at the right place), the second for the line command, color, and line thickness
0x0041 | draw line to (no update of x,y coordinates) |  | line thickness | as above
0x005x | filled shapes | * | * | *
0x0050 | set fill color |  | 0: disable fill color usage -> fill color always is actual color ....(no value): set fill color to current RGB color | default is to fill a shape with the same color as the shape frame, but you can explicitely set a fill color with this command
0x0051 | Circle/Ellipse |  | 0xAABB: AA is the horizontal half diameter of the ellipse, BB the vertical, if you leave one zero, both will be set equal, and you'll get a circle |
0x006x | (primitive) text | * | * | *
0x0060 | draw character |  | 0xAABB: AA is the font height to use, BB the ASCII code of the character | uses the actual RGB values I'm aware, that this isn't the text processing software of the future...
0x0061 | set font height |  | font height for text output | this value is remembered for all future textoutput of the machine
0x0062 | set text line number |  | line number of textfiles | default is to use the first line of multline textfiles, all future textoutput refers to this line number (for all text files the same!)
0x01xx | offscreen image processing | * | * | all these absolutely don't work for the resizable window
0x0100 | floating image | just moves everything a bit | 0xAAxy: AA: reserved (let it be zero!) x: X-shift 0...8, 9...F means -7..-1 y: Y shift (same format) | works for 8bit and 16bit modes,
0x0101 | Blue Ghost | 16bit: moves only the lower byte, like some blueish shape | as above | 8bit: the same as 0x0100
0x0102 | Anti-Blue Ghost | 16bit: the ghost stays, the rest wanders | as above | 8bit: the same as 0x0100
0x0103 0x0104 | Almost Invert | 16bit: moving +changing either high to low byte or inverse | as above | apply once and you get some almost inverted image, but better use effect 0x0107 ... 8bit: the same as 0x0100
0x0110 | Color shift | 16bit: shifting the RGB values + image moving | as above additionally the RGB columns are used: either 0x80 or ..: unchanged <0x80: shift color component down (0 removes the component completely) >0x80: shift up (0xfe maximizes) | 16bit only the RGB values used here aren't remembered and hence don't mess other color things up
0x0111 | Color shift with wrapping | 16bit: almost as palette animation would be, the same as 0x0105, | as above, but without 0xfe as maximizing or 0x00 removing color components: 0x00 or 0xfe do a complete shift and wrap around and hence leave everything unchanged | 16bit only as above
0x0112 0x0113 | Color shift after invert 0x0107 with wrapping | as above | as above | 16bit only as above
0x0120 | little diffusive thingy |  | - | not very impressive : ( may also work for 8bit (untested)

4. History
version 0.1:
-first release: bitmap slide-shows, no effects

version 0.11:
-working colorfill (effect 0x0003)
-erase window uses DirectDraw colorfill now (slight incompatible: uses given color now, so just add RGB 0,0,0 to all old erase window commands!), this is also in sync with other bitmap commands
-circle airbrush (effect 0x0021)
-source transparency with given color (only if at least one of the RGB columns actually contains a number)
-negative x,y coordinates 0x2001...0x4000 -> -0x1fff....0
-color RGB value mapping 0xfe -> 0xff
-more bitmaps in one row work correctly now
-window initialized now a bit away from top left desktop corner
-show first available image at startup

version 0.2
-begin handling of DDraw fullscreen mode(s): switch with right mouse click; take care: they can mess up your desktop icons :(
-offscreen buffering for effects -> only 320x200 seems useful (at least on my P200)
-aaahhh: version 0.11 was already able to hande multiple machines accessing one window; refined this a bit
-added first effects, quite nice and really fast enough :) (at 320x200) -> instead of doing the 8bit modes I'll probably stay in 16bit now
-now it really becomes multi-layered: added option for single machines, to keep blitting directly to the screen, while others
do the offscreen buffering, this is very cool for animations
-instead of having to force a special machine order for the previous point (obviously the direct screen blit has to occur after
the offscreen to screen blit) -> some code wandered into the Work() function: that's why the machine input has to be active again for the new modes
-added fixed window size option
-added options dialog + saving/loading of settings
-VERY BASIC text interface: draw one character (per ASCII code) with given size and color at given positions (ARIAL font), ... will the text processing software of the future be like this...
-saving of last window size with the song and using this for creating the resizable window instead of the deafult 320x200
-F5/F8 can now also be pressed in the vGraphity window (especially usefull for fullscreen modes)
-loading and using DOS-Cthugha translation tables (for 320x200 fixed window mode)
-loading text-files, but what command interface to use for them ?
-relative coordinates 0x4001...0x5000 (very useful for text scrolling)
-sound through option (to allow putting several vGraphity machines in a row)
-MIDI input ;)
-default effect (if only data is set) -> 0x0006 (may be better for MIDI controlling)
-disabling graphics output for anything other than BUZZ or m2buzz
-handling of multiline textfiles

version 0.21
-some fixes for newer BUZZ 1.2 betas, loading of bitmaps caused crashes; now bitmap loading is delayed 3 seconds,
and you may need to explicitely use the menu command "Refresh Bitmaps"; there are still some sound problems though : (
-added wave slot offset and periodicity for MIDI input
-JPG loading
-temporary files are now created in usual temp-directory and deleted after usage -> no buzztemp.bmp files anymore and loading files from CD-ROM possible

possible plans/future (and still missing things):

- effects, effects, effects (Cthugha flames,...)
- sound input -> oscilloscope,FFT,...
- correct palette handling and other 8bit stuff (?)
- random mode (without need to create patterns, just the usual random visualisation thing)
- emulating some useful blit ROPs ?

contact me: ( vII) or look at my Homepage