libggi 7ggi GGI libggi a fast, simple, small and flexible user-space graphics library GGI Project. It attempts to abstract the many different graphics output systems existing under Unix (and in the future, other platforms). The support for all of these different types of displays and hardware are provided by dynamically-loaded mini-libraries. The following outlines the environment variables, intended for the user, which affect the behaviour of LibGGI: DISPLAY If set, assumes that you want to use the GGI_DISPLAY Specifies the default target (used when the application calls : Multiple inputs can be specified by this notation: ():() ... If neither this variable nor GGI_INPUT Specifies extra LibGII input sources for all for details on the format. You can also append the name of a specific target to the environment variable name to specify extra input sources for that target. For example: export export GGI_DEFMODE Specifies the default mode, which is used for mode negotiation with LibGGI applications. Specifically, when The format is: (all on one line, of course) S x x V x D x F [ / ] Anything and everything can be omitted, except tokens indicating what the next number is. Any omitted values default to ' Denotes visible size, which is the area visible to the user. Totally optional, as dimensions without a specifier are considered to be the visible dimensions. ( ' Denotes virtual size, the total drawing area available to the application. The virtual size must be equal or greater than the visible size. ' Denotes the number of dots-per-pixel. For graphics modes, this is always 1x1, and for text modes, this is the size of the character cell. ' Denotes number of frames available to the application. Applications can switch between different frames for double-buffering, etc. ' ' Delimits the graphics type. One of: CColored PPalettized (indexed-color) mode KGreyscale TText (character-cell) mode Pixel depth in number of bits. Size of pixel in number of bits, including padding. Instead of 640x480 just the visible size 640x480#640x960 same size, but double-height virtual screen #1024x768 only virtual size defined 80x40[T] (default-fontsized) text mode with 80x40 characters #x100[T] text mode with 100 virtual lines 640x400[8] 640x400 at 8 bits per pixel 640x480[GT_8BIT] same as above, but palettized 320x200x15 320x200[C15] 320x200 with 32768 colors (hicolor) 320x200[C/16] 320x200 with 16-bit pixels (also hicolor) 320x200[C24/32] 320x200[GT_32BIT] 320x200, with 32-bit pixels, 16777216 colors (truecolor) GGI_DEBUG The debugging level for 0 or unset debug output is off; debugging is off 255 all debug output is on You may also bitwise 'or' any of the following together: 2debug core 4debug mode setting 8debug color handling 16debug drawing 32misc debugging output 64debug dynamic library handling 128debug event handling GGI_DEBUGSYNC Turn on synchronous debugging output, flushing the output buffers before returning from FRAMEBUFFER Specifies which framebuffer device file the GGI_NEWVT If set, causes a new virtual console to be allocated for some Linux-console-based targets (currently GGI_MANSYNC_FPS This variable specifies the framerate for targets emulating SYNC mode (manual sync). The default is 20fps. If you are experiencing problems with the X target over realtively slow remote connections it might be due to connection overload. You might want to try with a lower Displays in an X window. Emulates a linear framebuffer which is blitted to the X server with the -inroot -inwin= The X display to connect to, otherwise defaults to the display specified in Run in root window -inwin= Run in already-existing window with id In this target, toggles mouse grabbing. It will try to emulate a "relative" mouse device, i.e. one that can be moved arbitrarily far in any direction without ever leaving the window. This is useful for game controls, where loosing focus is generally undesireable. Note that grabbing must be turned off in order to leave the window. Other features: Unaccelerated Multiple frames Panning Uses Xlib primitives to do drawing. Faster than This target has the same options and hotkeys as Other features: DirectBuffer never available. Accelerated if the hosting X server is. Uses the XFree86 DGA extension to do fullscreen direct framebuffer access on X servers which support this. The bad thing about the DGA extension is that it requires root access in order to map /dev/mem, which means that you have to be The display to connect to can be optionally specified. Otherwise the display in The environment variable /dev/mem. This allows you to use the Other features: DirectBuffer always available. Unaccelerated Multiple frames Panning Uses the AAlib, an ASCII art library, for output and input. The standard AAlib Other features: DirectBuffer always available. Unaccelerated Uses the Linux /dev/fb* devices to do fullscreen graphics. -noinput The filename of the framebuffer target to use. The default is to get it from the -noinput Do not open any input libraries by default. Other features: DirectBuffer always available. Accelerated when using KGIcon or matroxfb. Multiple frames Panning Renders an image into a file. The file can be a framebuffer device (e.g. /dev/fb0), in which case a reasonable representation of the image will be drawn on the console This target generates no input ! The -flushcmd=" -flushframe= -flushtime= The foo.%04d.gif/. The command is passed through a which has the current count of saved frames as an argument (or rather as 10 arguments to allow a few more complex commands). This shell command is either executed at every Note, that the invocation of the shell command will slow down the program, so make sure you use a reasonable value, if you use the The primary file is updated before every invocation of the shell command. Other features: DirectBuffer always available. Unaccelerated. Uses the Glide rasterisation library to display fullscreen on a 3DFX graphics card. The 3DFX card to use can be optionally specified as a number. ( Environment variables: specifies the maximum update frequency your monitor can handle (in Hz). Default is 70Hz. specifies the maximum horizontal frequency your monitor can handle (in kHz). Default is 48kHz. if this is set applications will be halted on console switchaway. The default is to continue running. Other features: DirectBuffer never available. Accelerated, one of the fastest targets when it comes to drawing-primitives. Multiple frames. Emulates a linear framebuffer in main memory. This memory area can be a shared memory segemnt, an area specified by the application, or be -input shmid: keyfile: pointer If the "-input" option is set, an input buffer of ggi/display/memory.h (default is 8192 bytes) is allocated at the start of the requested memory area. This is useful, when running on shared memory, because it enables you to use SendEvent to give input to other processes sharing that segment. This is demonstrated in shmid: use existing shared memory ID keyfile: create a new shm segment with id ftok( pointer use the memory pointed to by If you specify a memory area to use - be sure it's big enough as no checks can or will be made that a certain mode fits into it. Other features: DirectBuffer support always available. Unaccelerated. Uses the SVGAlib library to display fullscreen on a VGA-compatible graphics card. Other features: DirectBuffer is available for the 320x200x8 mode. For other modes, support is only available if SVGAlib supports linear addressing. Unaccelerated Uses the Linux /dev/vcsa* devices to render text modes onto the console. -shade -ascii The filename of the device file, defaulting to /dev/vcsa which draws on the current virtual console. -shade The -shade The Other features: No DirectBuffer support. Unaccelerated. Emulation targets are those that run on top of one or more other targets. Emulates palettized modes (GT_PALETTE) on another target which can only do text modes, by representing the graphics as ASCII characters. The effect is the much the same as the -a= -x= -y= -x= -y= A value between 1 and 5 which determines how accurately to map the graphics to ASCII characters. Lower values are less accurate, but can represent a wider range of intensity levels. The default is X=2 and Y=4. -a= Same as above, but sets both the X and Y accuracy to the specified value. Other features: DirectBuffer never supported. Unaccelerated. Duplicates all drawing operations onto multiple `child' targets, producing identical output on multiple visuals. Required: A colon (`:') separated list of target specs to draw on. Because target specs can (and often do) contain colons, they need to be enclosed in parentheses. Other features: DirectBuffer never supported. Unaccelerated. Emulates palettized modes ( -parent= -parent= Force the parent target to use a specific mode (standard LibGGI mode string expected). Specifies the target which to draw on (the `parent' target). This defaults to automatic selection (just like using Other features: DirectBuffer never supported. Unaccelerated. Emulates one big target, splitting it up into `tiles' where each tile is drawn on separate targets (the `children'). decimal values of the coordinates at which the tile begins within the whole visual. are decimal values for the size of the tile within the whole visual. a target spec. Since target specs can (and often do) contain colons, it needs to be enclosed in parentheses. enables the DirectBuffer emulation. This is the default. DirectBuffer emulation works regardless of whether the child visuals support DirectBuffer or not. disables the DirectBuffer emulation. Instead, Emulates tes truecolor modes ( -parent= -dither= -model= -parent= Force the parent target to use a specific mode (standard LibGGI mode string expected). -dither= Specifies the amount of dithering. Legal values are 0, 2 and 4, defaulting to 4. When the target is running, changes the dithering level. -model= Color model to use (only when the parent is palettized). Legal values are rgb, cube and pastel. Default depends on the parent mode. When the target is running, changes the current color model. Specifies the target which to draw on (the `parent' target). This defaults to automatic selection (just like using Other features: DirectBuffer never supported. Unaccelerated. These targets can only be opened explicitly by applications; setting Creates a `child' visual within a "parent". This can be thought of as a window and the No textual arguments. Other features: DirectBuffer not supported. Accelerated to the point of the parent. Calls are mapped through with modified clipping and coordinates.. The sub target behaves a bit special with respect to the setmode call. It uses the "visible" size for the top left corner position of the window within the visual, and the "virtual" size for window width and height. Note, that moving/resizing the window does _not_ cause any drawing action. You have to perform those yourself. All it does for you is providing a virtual visual within an existing one, which is convenient to allow for window system canvases to be about any GGI program. Various LibGGI hackers. Converted to DocBook and man page by Steve Cheng The LibGGI API Manual