title: svgalib.mach32(7)

text:
# svgalib.mach32(7)

## NAME
svgalib.mach32 - Information on the Mach32 chipset driver

## TABLE OF CONTENTS
0. Introduction

1. Specifying pixel clocks

2. Copyrights

3. The mach32info utility

4. Third party cards

5. Logical linewidth

6. Noisy video signals

7. The configuration EEPROM

8. EEPROM woes

9. The Mach32Eeprom command

10. Setup of the memory aperture (linear framebuffer)

11. Accelerator support and other weird features

12. Ramdacs

13. Meaning of the detection message from svgalib

14. Conclusions

## 0. INTRODUCTION
The driver should allow you to use any of the graph-modes your Mach32 card supports. Note that there is no support for <8bpp modes and that I won't ever implement that because I don't see any reason for doing so. All standard VGA-modes are supported, of course (by using the standard VGA driver routines).

If you configured your Mach32 for a memory aperture and it is at least as big as the memory of your card (that is, not a 1MB memory aperture for a 2MB card) support for linear frame buffer access of svgalib is given.

Auto detection of the Mach32 seems not to work on all cards. That's really strange since I got the code from the X people. It should be OK regardless of my docs. Well, I fixed that (hopefully). Actually the bug was found by Daniel Lee Jackson (djackson@ichips.intel.com). (Thanks again.. It was so silly... I would have never found it) If you still have problems just put a chipset Mach32 in your config file.

## 1. SPECIFYING PIXEL CLOCKS
WARNING! The Mach32 driver needs to know correct clock frequencies for graceful DAC configuration. Wrong clocks may damage your card! However, this version contains code for automatic clock detection. Since clock detection is time critical, please do it on a completely idle system. Then put the printed out clocks line in your libvga.config(5) file.

The driver tries to do this for you. After that, you can restart whatever svgalib program you used and you are set. If you already put a clocks line in your config by hand, comment it out to have the driver check your clocks.

Since clock probing is time critical, values differ from time to time, you may try it multiple times and see which values seem to be most exact. You can also compare them with the standard clock chips for Mach32 cards in libvga.config(5)).

The clock probing relies on the 7th clock being 44.9MHz as this is what Xfree does. If this is not true (and it is not always), probing is hosed. See libvga.config(5) for a list of the clocks used by common svgalib cards.

## 2. COPYRIGHTS
Some tiny routines are copied from Xfree86. The clock detection code is almost just copied. So I repeat the copyright statements for these parts here:

Copyright 1992 by Orest Zborowski <obz@Kodak.com>

Copyright 1993 by David Wexelblat <dwex@goblin.org>

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Orest Zborowski and David Wexelblat not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Orest Zborowski and David Wexelblat make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Orest Zborowski and David Wexelblat disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall Orest Zborowski or David Wexelblat be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.

Copyright 1993 by Kevin E. Martin, Chapel Hill, North Carolina.

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Thomas Roell not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Thomas Roell makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Thomas Roell, Kevin E. Martin, and Rickard E. Faith disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall the authors be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

Author: Thomas Roell, roell@informatik.tu-muenchen.de

Rewritten for the 8514/A by Kevin E. Martin (martin@cs.unc.edu)

Modified for the Mach-8 by Rickard E. Faith (faith@cs.unc.edu)

Rewritten for the Mach32 by Kevin E. Martin (martin@cs.unc.edu)

And here is my own copyright:

This driver is free software; you can redistribute it and/or modify it without any restrictions. This library is distributed in the hope that it will be useful, but without any warranty.

Copyright 1994 by Michael Weller

Email addresses as of this writing:

eowmob@exp-math.uni-essen.de mat42b@spi.power.uni-essen.de

Michael Weller disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall Michael Weller be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

## 3. THE MACH32INFO UTILITY
The mach32info(6) utility or demo reads out all configuration registers and the configuration EEPROM of your Mach32 card. If there is a problem with the particular card you have, compile and run the utility in the mach32/ directory of the svgalib distribution and send it's stdout to me This might also be useful if you need a lot of options (e.g. clocks on new models?) to get it to work so that this can be done automatically in future versions.

## 4. THIRD PARTY CARDS
I got a few reports about AST systems with onboard Mach32. They do feature an incompatible EEPROM setup, but I think I got around that. Nevertheless the Mach32 chipset driver doesn't work out of the box on any AST system I heard of.

Since original ATI Mach32 demos and tools don't work as well, I've to claim that the Mach32 on these AST systems does not conform to ATI's Mach32 docs. Fortunately, Vernon C. Hoxie <vern@zebra.alphacdc.com> found a work around after years (really!) of investigating. AST Mach32 seems to work now. The work around was also submitted to Xfree and will be incorporated to allow running it on the AST hardware too in recent versions. Please read on the misc_ctl command below.

Dell users should have a look at the vendor, ramdac, and svgaclocks commands below (if they have problems with the default settings).

### Commands to support third party cards
I had to learn that those cards seem to use not only non standard clocks for the Mach32, but also for the included SVGA. However, since people often like to use proprietary, non standard VGA (read 80x25) textmodes, the Mach32 driver has to set the included SVGA to a VGA compatible clock frequency. Otherwise svgalib has problems using plain VGA modes. This screws VGA modes up if these clocks have different values on third party Mach32 cards.

svgaclocks n

with n a number between 0 and 31 to select the svga clocks to be used in vga modes. The bits of n refer to specific ATI register bits to complicated to explain here. Even if I would, I can't tell which clocks they would select on your third party card (which is the actual problem) svgaclocks 9 is the default setting and correct for original ATI cards.

Often svgaclocks 0 (Dell cards) works.

svgaclocks keep

is special in that the driver will not touch any SVGA timings. This requires the Mach32 SVGA part to be in a VGA compatible mode when the svgalib application is started, that is, you must use 80x25 (maybe 80x50) console textmodes.

As I mentioned already, Vernon C. Hoxie <vern@zebra.alphacdc.com> really seems to have located the reason for the Mach32 AST problems. Any access to MISC_CTL locks up the card & system. Fortunately MISC_CTL is only used for some DAC fine tuning (actually the setting you can fine tune with the blank command) which is only of barely noticable effect to the screen.

The following configuration commands exist to support AST cards:

misc_ctl keep-off

Do not dare to touch MISC_CTL.

misc_ctl use

Use it for fine tuning of the Ramdac setup (default).

Finally, for your convenience there exist:

vendor ati

vendor dell

vendor ast

These are macros that expand to settings for svgaclocks, ramdac, misc_ctl, and mach32eeprom that are usually correct for ATI, Dell, AST cards. Be aware that they really work like macros. That is, they override any setting of svgaclocks, ramdac, misc_ctl, and mach32eeprom made before them and individual aspects will be changed by a following svgaclocks, ramdac, misc_ctl, and mach32eeprom command. Note that the mach32eeprom ignore required for some Dell cards requires you to include explicit timings for Mach32 modes other than 640x480x256. The mach32/mach32.std-modes file in the svgalib distribution contains recommendations for modes from ATI.

I heard about a bug in some ATI chipsets returning wrong memory amounts configs. (But cannot confirm that)

You can enforce correct chipset identification from the configuration file:

chipset Mach32 chiptype memory

where chiptype is the sum of at exactly one value from each of the following two groups

128

use no memory aperture.

160

use a 1MB memory aperture.

192

use a 4MB memory aperture.

0

choose size for the memory aperture automatically.

and

16

Ramdac is of type 0 (ATI68830)

17

Ramdac is of type 1 (IMS-G173, SC11486)

18

Ramdac is of type 2 (ATI68875, TLC34075)

19

Ramdac is of type 3 (INMOS176, INMOS178)

20

Ramdac is of type 4 (Bt481, Bt482)

21

Ramdac is of type 5 (ATI68860)

0

Ramdac type is queried from Mach32 chip.

memory is the amount of videomemory in KB.

Note that the type of the ramdac can be set more conveniently with the ramdac command.

## 5. LOGICAL LINEWIDTH
At least my VRAM card seems to be very peculiar about logical linewidths. From my experience a multiple of 64 pels is needed. Your mileage may vary. Use the config file options to adjust it and tell me if your card needs a different value. Include the name and model number of the card and what the correct numbers should be. This is so that I can correct the auto configuration of the driver.

If some svgalib application has problems, note that you can force the logical linewidth to the default value from the configfile. Probably this will lead to glitches in some 800x600 resolutions. You can inhibit these resolutions from the configfile as well. Apropos glitches, I found no guidelines as to what clockrates to use due to memory restrictions. I adjusted the driver, such that I get a stable pic in all resolutions. However sometimes the screen is disturbed by heavy video memory accesses. If you don't like that, reduce the clocks used with the maxclock16 or maxclock24 command, resp. This may of course lead to none of the predefined modes being used. Then you can try to define your own mode via the define command.

## 6. NOISY VIDEO SIGNALS
If you get some flicker or heavy noise on your screen, some fine tuning may be needed. My docs didn't give me hints as to what each card can stand. Especially DRAM cards may give problems (I've VRAM). In that case, use the fine tuning config commands and send me your results along with the output of mach32info(6). Then I can include them in my next release.

### Fine-tuning configuration commands
First you should think about the maxclock* configuration commands to reduce pixel clocks used for each color depth.

Especially important for DRAM cards is the video FIFO depth used to queue memory values for writing to the screen. Here is a command to set this value for the 8bpp modes:

vfifo8 number

where number is in range 0 - 15. The default is now 6. Since vfifo is of some impact to the speed of the card, tell me the lowest setting that satisfies your card.

For 16/24/32 modes, there are non-zero values preset from internal tables and the EEPROM, however you can enforce minimal vfifo values with:

vfifo16 number

vfifo24 number

vfifo32 number

blank number

where number is 4 * pixel_delay + blank_adjust where pixel_delay and blank_adjust are in range 0 .. 3. pixel_delay delays pixels before they are sent to the DAC and blank_adjust adjusts the blank pulse for type 2 DAC's. blank should be set correctly for each DAC type automatically. So use it only as a last resort.

latch number

where number is the sum of zero or more of the following numbers:

128

VRAM serial delay latch enable, DRAM latch bits 63 - 0 enable.

4096

Latch video memory data.

8192

Memory data delay latch enable for data bits 63 - 0.

16384

Memory full clock pulse enable.

Default is to switch all settings on (they are on on my card by default anyway).

Note that these commands may vanish again once they are no longer needed for debugging purposes.

There is no 320x200 mode in the EEPROM of the Mach32 at all, however I defined one in the default configuration file for you. This is the best thing I could get up on my card/screen. Note that it will probably have big borders on your screen, and black lines in between the pixel lines. This is because of the lack of low clocks < 16MHz on the Mach32 and the lack of a line doubling mode as VGA has. The Mach32 is not intended for such low resolutions. If you find a better mode or have an idea, please let me know. You can also just remove my timings from the default configuration file.

## 7. THE CONFIGURATION EEPROM
Ah yes, about the EEPROM, I figured out how to read out the Mach32 EEPROM. I did it by disassembling the BIOS routine mentioned in the docs. I then redid it in C. The driver will use everything it finds there.

Use the Mach32 install tools (they should have reached you together with your Mach32 VGA card) to setup your card/monitor combo correctly. The monitors setting from the config file (or default of 35kHz or something) will be obeyed by the driver nevertheless (for safety!).

As you probably know already, accessing the EEPROM causes some screen flickering. If this annoys you (or even worse your monitor) have a look at the mach32eeprom command described below. This allows you to put the data from the EEPROM into a file and which can be read whenever it is required.

Don't even think about changing the contents of the file. (There is an easily faked checksum in it.). Anyway the driver ensures (hopefully) that no damage can be caused.

Also, if some mode is not well aligned on your screen or you don't like it's sync frequency, consider using the Mach32 install utility (setup for custom monitor) and set one up interactively. If there is no valid faster (higher VSYNC) standard mode given in the EEPROM the driver will use that mode. You will find that this is fun compared with calculating video timings for /etc/XF86Config or /etc/vga/libvga.config.

However the install utility does restrict the maximum pixel depth for custom modes sometimes unneeded hard and the driver obeys that. (Hmm.. actually it should be smart enough to decide itself which pixel depth it can use in that mode.) Since the standard modes are usually only slightly shifted to one side a file with the configuration commands representing the standard modes is given in mach32/mach32.std-modes in the svgalib distribution. You can use these as a starting point.

But here are some real problems:

## 8. EEPROM WOES
I got 2 reports of people having problems with incorrect EEPROM checksums. Both had motherboards with onboard Mach32 VGA's from AST. I guessed a checksum algorithm from those reports and put this in the code in addition to the standard ATI style. Still I got a report of someone whose EEPROM was completely empty. If you have problems with checksums send me the output of mach32info(6) and I'll see what I can do.

By default svgalib writes a complaining message and ignores the contents. You can have svgalib ignore the checksum and contents with the configuration command

mach32eeprom ignore

Then you can decide to use the partial info that is still in it. Use

mach32eeprom ignore usetimings

to use the videomodes that are defined in the EEPROM (if no better modes are known by the driver). This is usually safe, because the driver knows which modes are safe for your hardware (if clocks, monitor and ramdac are configured correctly). You can also allow the driver to use the configuration for the linear frame buffer in the EEPROM:

mach32eeprom ignore useaperture

or

mach32eeprom ignore usetimings useaperture

However I discourage this because the driver will just enable what the EEPROM says about the aperture. Use mach32info(6) to check the address it will choose is safe. It might be better to use setuplinear to set up a 4MB aperture at a free address range.

## 9. THE MACH32EEPROM COMMAND
The mach32eeprom allows to work around these problems. Here is the complete description for this configuration command.

mach32eeprom filename

The filename has to begin with a "/". Unfortunately reading the EEPROM causes annoying screen flickering and is slow. To avoid this, specify a filename from which to read the contents of the EEPROM.

If the file cannot be read, the EEPROM is read out and the file is created. There is a very simple checksum put into this file. Although it can easily be fooled, don't change the file except you know very, very well what you are doing.

Also, as long as the file exists, changes in the Mach32's EEPROM are ignored. Delete the file to recreate an updated version on next use of svgalib. You should ensure that the permissions of the file don't allow normal users to change it. (This may happen if umask has a bad value when svgalib creates the file).

Example:

mach32eeprom /etc/vga/mach32.eeprom

Due to problems with some boards this command got heavily expanded:

mach32eeprom subcommand1 [subcommand2...]

At least one subcommand is needed. Valid subcommands are:

ignore

Don't complain about checksum and don't use any EEPROM contents.

useaperture

Use the configuration for the memoryaperture given in the EEPROM.

usetimings

Use videomodes found in the EEPROM of the board.

nofile

Forget about any filename that maybe was already configured. Don't read a file, don't create one.

file filename

Newstyle form to specify the filename; On contrary to the mach32eeprom filename form it can be mixed with any other mach32eeprom subcommand.

updatefile

Don't read the file, always read the EEPROM (except when ignore is given) and create an uptodate image of the EEPROM.

keepfile

Disable all previous updatefile commands.

compatible

Fall back to default behavior: If checksum on the EEPROM data is not ok, use nothing of the configuration data. If it is ok, configure everything as specified in the EEPROM.

The subcommands are intended to be used together and are performed in the order specified. For example: mach32eeprom ignore useaperture usetimings

will ignore the checksum of your EEPROM, but use its contents. Order is vital! So:

mach32eeprom useaperture usetimings ignore

won't use any configuration from your EEPROM. Be careful with the useaperture subcommand. Please see the EEPROM WOES section. Note that any non understood subcommand will terminate the mach32eeprom command silently! Use only one subcommand per mach32eeprom command to avoid this.

The mach32eeprom command is usually not allowed in the environment variable SVGALIB_CONFIG.

## 10. SETUP OF THE MEMORY APERTURE (LINEAR FRAMEBUFFER)
Due to poor design, Xfree86 insists on setting up the aperture itself. It doesn't reset the original settings at a VC switch once it runs. You should not start X for the first time after a boot as long as an svgalib application is running. This will result in pre X values being restored at a VC switch by svgalib. If you use svgalib and XF86_Mach32 together, run X first or at least do not start it while any svgalib appl. is still running. After X was started once you can use svgalib and X in all combinations w/o any problems. Xfree uses whatever address is given in the MEM_CFG Mach32 register for a 4MB aperture, even if the aperture is not already enabled and the value in this register is pointless garbage. This is IMHO a dangerous bug as some systems may work only with a 1MB aperture.

However, usage of a correct EEPROM circumvents any such problems. If you cannot use that, use mach32info (6) to find the address in MEM_CFG. Then, if it is a senseable setting for your system, enable a 4MB aperture at that address with setuplinear. Ensure that no other card or memory uses the address range you choose.

## 11. ACCELERATOR SUPPORT AND OTHER WEIRD FEATURES
This version now has support for all accelerator functions of svgalib. However they were intended for use with the cirrus chips. It may happen that at runtime they find they cannot emulate the function actually requested. Then you should disable the corresponding blit function (at least for that application) with the blit config command.

Data transfer between the host and the Mach32 is normally via I/O. This proved to be pretty slow. If a big enough aperture is available, a simple memory copy is used instead. This is usually much faster. You can change which method is used with the blit command. This I/O option affects only vga_imageblt(3). The other functions are incredible fast.

For type 2 DACS, there is support for 8 bit per color (instead of the normal 6) in the RGB triple in the color lookup table of the 256 color modes. This can be enabled by an application, if it supports it. The testaccel(6) demo uses it if supported by your hardware. You can use vga_ext_set(3) to use it from your programs.

## 12. RAMDACS
Mach32 Ramdacs are specified by a type in range 1 .. 5. This type can be queried from the Mach32 and then specifies how to set up the ramdac. A list of actual hardware chips used for each type exists, but is not of much use. The Mach32 will return a type and the ramdac will be completely hardware compatible to one of the given type.

Type 1 and 4 Dacs need different clock frequencies for high colormodes. For 32K/64K colormodes the frequencies have to be doubled and for 16M colors (type 4 only) they have to be tripled. I followed the ATI scheme and did this internally. However this means that for 32K/64K you can use only clocks for which the doubled frequencies can be generated as well.

This is no hard restriction as the 16 clocks of the Mach32 can be divided by 2. Thus if you setup some mode yourself try to use one of the divided clocks in your timings and I can use the undivided clocks internally.

It is a real restriction for 16M colors. ATI themself only supports 25MHz (640x480) here by use of a 75MHz clock. Depending on your clock chip other values may be usable as well. Even the doubled/tripled clocks have to be less than the magic 80 MHz. However the driver does all this itself. It may just happen that some of the predefined or one of your handmade mode-timings can't be used because the clock that is used cannot be doubled/tripled. Even though there is already some tolerance in the driver you may fix that by slighty changing the clock values that you set with the clocks command. But note that this will as well affect the ability of the driver to calculate video timings and thus it ability to check the monitor and DAC safety restrictions.

In addition (in complete contrast to my original ATI docs) RAMDAC 4 does not support RGB with blue byte first but only with red first. This required special handling and me adding a bunch of functions to all modules of svgalib and vgagl. The added functions are of lower performance than the usual functions. However most data has to be completely mangled, so I doubt that it can be done much faster. Sorry.

Of course, I might have forgotten to port some parts or even confused things. About bugs in the gl and drawing libs, please ask Harm. But then, I'm able to emulate a BGR ramdac on my card, so I should even be able to reproduce your problems.

Recently I hear often about type 6 ramdacs in non ATI Mach32 cards. There exists no info about these dacs, thus I cannot support them. The driver assumes unknown DACs can stand up to 80MHz in 256 color clut modes and does not touch the ramdac (that is, assumes it is in the 256 color mode already)

To get rid of the warning message you can use the

ramdac n

configuration command. It allows to explicitly set the type of the dac to n (in range 0 to 5). Ramdac 3 is the most dumbest ramdac possible, s.t. you can use it without any fear for your hardware.

ramdac dumb

is equivalent to ramdac 3.

ramdac auto

switches back to the default autodetection.

## 13. MEANING OF THE DETECTION MESSAGE FROM SVGALIB
Some programs (which do not switch it off) will show a

Using Mach32 version (sizeM at adrM (how), memK mem, DAC dactype)

line. This will show up in testlinear(6) etc but will probably scroll away when you use vgatest(6). In this line:

version

is the version of the driver (as of my counting, not the svgalib version).

size

is the size of the memory aperture. It can be 1 or 4 (1 will lead to not using the linear aperture if your card has more than 1MB memory, however applications can still use the 1MB aperture and page the video memory through it in 1MB steps). size can also be no if no aperture is setup at all.

adr

is the base address of the aperture in MB.

how

is autodetect if the aperture was setup this way already when the program started. It is setup when the the setting was enforced with a setuplinear configuration command. It is EEPROM when no aperture was detected, but parameters to set it up were found in the EEPROM.

mem

is the amount of memory the card reported to have.

dactype

is the type of the DAC that was detected. If a special ramdac type was set with the ramdac command a (set) will be displayed after dactype.

If mem, dactype and/or the chipset were enforced with chipset from the configuration file or vga_setchipsetandfeatures(3) a forced will be appended to the line.

## 14. CONCLUSIONS
A final word: I have an ATI ULTRA PRO/2MB/EISA with a Type 2 DAC. My monitor is an EIZO F550i-M. Everything I tried works on it like a charm. However, I couldn't try it with other machines myself and esp. other DAC's. Fortunately the Type 2 DAC is the worst to code. So I will probably have gotten the other DAC's right. But please be warned!

I did my very best to code the driver to support the other DAC's by just reading the docs. But i can't give any definitive guarantee for it to work or even not damaging your hardware. So please be careful!

Note that you will have to set the environment variable SVGALIB_MACH32 to ILLTRYIT if your DAC is not type 0, 2, 3 or 4. This will of course change if no one with a DAC equal to 1 or 5 has serious problems. If you have a different DAC, making patches to support your card will be much more helpful instead of just complaining. If you have a different DAC that works well tell me as well such that I can remove the need for SVGALIB_MACH32 in the next release. Still, even now, after years, I got no reports of a Mach32 card with a type 1 or 5 ramdac. Go figure.

Thank you for your audience and wishes you will enjoy this driver,

Michael.

## FILES
/etc/vga/libvga.config

/etc/vga/mach32.eeprom

## SEE ALSO
svgalib(7), libvga.config(5), mach32info(6).

## AUTHOR
The Mach32 driver and this documentation was written by Michael Weller <eowmob@exp-math.uni-essen.de>.


threedkit

package: svgalib

title: threedkit(7)

summary: a set of functions for 3D support.

text:
# threedkit(7)

## NAME
threedkit - a set of functions for 3D support.

## DESCRIPTION
The 3dkit consists mainly of the following triangle functions gl_striangle(3), gl_swtriangle(3), gl_triangle(3), gl_trigetcolorlookup(3), gl_trisetcolorlookup(3), gl_trisetdrawpoint(3), gl_wtriangle(3).

Beware, these functions are not a direct part of the svgalib library. Instead their source is part of svgalib and can be found in the threeDkit/ subdirectory of the original svgalib distribution. However, it is not installed in the system by default, s.t. it is unclear where you can find it if your svgalib was installed by some linux distribution.

In case of any such problem, simply get an svgalib distribution from the net. You even don't need to install it. Just make in the threeDkit/ subdirectory. As of this writing, svgalib-1.2.12.tar.gz is the latest version and can be retrieved by ftp from sunsite.unc.edu at /pub/Linux/libs/graphics and tsx-11.mit.edu at /pub/linux/sources/libs which will most probably be mirrored by a site close to you.

The functions are defined in the tri.o and triangl.o files (or their resp. sources) which you must link to your program.

## EXPLANATION ON 3DKIT.C
This is main engine for 3D rendering.

Program flow:

1.

The function called from outside of 3dkit.c is TD_drawsolid. This first calculates the rotation matrix from the camera rotation angles (see below for more details). It then allocates memory for the temporary array for holding temporary coords in subsequently called functions. It also sorts the surfaces from furthest to closest; according to the distance of the centre grid-point of each surface from the camera. It also establishes whether ROTATE_OBJECT option is on and zero's the camera position if so --- this is for displaying the object at the screen centre like in a 3D CAD package, as apposed to virtual reality where the object can be anywhere and the actual camera position can move.

In the case of ROTATE_OBJECT being on, although the camera position is zero, some distance has to be placed between the camera and the object (or else it would appear to be infinitely large on the screen). This is done using the variable s_cam which is initialized to distance which is set by the calling application. It then loops through each surface (ordering them in the way they were just sorted --- i.e. according to sortarray indexing) and calls one of five graphic routines to write the 3D surface to the hardware.

2.

Assume that TD_drawsolid then calls TD_drawmesh. Here, each surface grid point is first TD_translate'd into a 2D screen point and stored in the temp array. There are obviously w(idth)*h(eight) points in the grid. Following, each line from the 2D temp array is drawn on the screen. To draw the surface, the corner wishbone (two lines) from each grid square is drawn while advancing across and the down. After completing the scan, the furthest two edges of the surface must then be filled in, vis.:

_ _ _ _ _ _

|_|_|_|_|_|_

|_|_|_|_|_|_

|_|_|_|_|_|_

|_|_|_|_|_|_

|_|_|_|_|_|_

| | | | | |

To understand the object rotation, a knowledge of matrix multiplication is required. I once derived a camera rotation before I learned matrix computation. It amounted to the same thing, but was unnecessarily complicated to optimise.

3.

TD_translate called from TD_drawmesh (and others) converts from the 3D grid point coordinate to the 2D screen coordinate using: (a) the three camera position coordinates, (or the single camera distance value, s_cam, if ROTATE_OBJECT is set), and (b) the three camera rotation angles. However, the three camera rotation angles have already been converted into a rotation matrix when TD_calc_rotation_matrix was called by TD_draw_solid. To convert from a 3D coordinate to a 2D screen coordinate, the camera position (or more correctly, the position of the object from the camera) must first be added to each of the 3D grid coordinates. If the user has chosen to use 32 bit values for the discription of the surface, then these must be right shifted to the same size as the 16 bit case.

x, y and z now hold the 3D position of the object relative to the camera centre (or in these terms, the centre of the video screen RIGHT ON the screen). The vector [x y z] must now be multiplied by the rotation matrix. The xt value must also have the camera distance, s_cam, added to it in case the ROTATE_CAMERA is set (in which case x_cam, y_cam and z_cam (the camera position) will be zero and instead s_cam will have a value to provide the necessary object-camera distance). A test is also made as to whether this value is zero or negative. In the case, the point is too close to the camera, or behind the camera, and must not be drawn.

After the multiplication, the resulting vector [xt yt zt] has been rotated to be aligned with screen. The vector is now adjusted for perspective by dividing the yt and zt values (horizontal and vertical respectively) by the xt value (into the screen). Division is done by muldiv64 because the intermediate product is larger than 32 bits. xscale and yscale are factors that scale the image to size. posx and posy is just the centre of the screen, or more precisely:

The exact position of the pinhole camera viewing the object.

4.

TD_calc_rotation_matrix calculates the nine entries of the 3 by 3 matrix used in TD_translate. In order that only integer arithmetic is performed, these values are stored and used as integers. Since this matrix's entries are always between -1 and +1, they have to be integer left shifted to give them accuracy. TD_MULCONSTANT scales them to sufficient bits of accuracy before they are converted to integers. This also means that results (of multiplications with them) have to be scaled down by the same amount. This scaling is inherent in the final multiplication and division (muldiv64) done in the TD_translate function, so an extra division is not consumed.

The rotation matrix effectively rotates the vector by the Eulerian angles alpha, beta and gamma. These angles represent successive rotations about each of the 3D axes. You can test which angles do what by looking at the calling application. Their precise definitions are not all that important since you can get the keyboard to do the right thing with a little trial and error.

Intrisics of drawing non-transparent surfaces...

to be continued ?!

## SEE ALSO
vgagl(7), svgalib(7), gl_striangle(3), gl_swtriangle(3), gl_triangle(3), gl_trigetcolorlookup(3), gl_trisetcolorlookup(3), gl_trisetdrawpoint(3), gl_wtriangle(3), plane(6), wrapdemo(6).

## AUTHOR
This manual page was edited by Michael Weller <eowmob@exp-math.uni-essen.de>. The demos, the initial documentation and the whole threedkit stuff was done by Paul Sheer <psheer@icon.co.za>.

Paper mail:

Paul Sheer

P O BOX 890507

Lyndhurst

Johannesburg 2106

South Africa

Donations (by check or postal order) will be appreciated and will encourage further development of this software. However this is strictly on a voluntary basis where this software falls under the GNU LIBRARY GENERAL PUBLIC LICENSE.

branch: sisyphus


vgagl

title: vgagl(7)

text:
# vgagl(7)

## NAME
vgagl - a fast framebuffer-level graphics library based ion svgalib

## TABLE OF CONTENTS
0. Introduction

1. How to use vgagl

2. Description of vgagl functions

3. Macros defined in vgagl.h

## 0. INTRODUCTION
This is a fast framebuffer-level graphics library for linear 1, 2, 3 and 4 byte-per-pixel modes (256-color, hicolor, truecolor). It uses a limited number of functions from svgalib (libvga) for low-level hardware communication (the library is included in the svgalib shared image).

In particular, svgalib(7) maps the 64K VGA frame buffer window, and this library directly addresses the buffer. For SVGA modes that use more than 64K of screen memory, SVGA paging is required when writing to the physical screen; this is done automatically for most functions (at a certain cost).

Alternatively, any number of virtual screens of any type in system memory can be used, which can then be copied to the physical screen. There is also support for 4 bytes per pixel framebuffers (and copying them to a 3 bytes per pixel context), and limited planar 256 color mode support (copyscreen, aligned putbox).

The planar 256 color modes (available on all VGA cards) can now be used with a virtual screen, which is copied to the physical screen (with optional page-flipping).

Bitmaps are raw, with one (or more) bytes per pixel (like pixmaps in X), stored in row-major order. They are usually manipulated with the getbox and putbox functions.

vgagl does also make use of the graphic cards accelerator (if it is supported) in some situations.

A graphics context is just a structure that holds the size of the associated graphics screen, how it is organized, clipping status etc. You can define a custom virtual (system memory) graphics context of any size with the setcontextvirtual function. All operations work on the current context.

Any questions, bug-reports, additions, suggestions etc. are welcome.

## 1. HOW TO USE VGAGL
Programs that use vgagl must #include <vgagl.h>. Linking must be done with -lvgagl -lvga.

Functions in the vgagl library have the prefix gl_*. To initialize vgagl, the graphics context must be set. Example:

vga_setmode(G320x200x256);

gl_setcontextvga(G320x200x256);

In this example, the context is set to the physical screen. The context can be saved (only the screen type, not the contents) into a variable, e.g.

GraphicsContext physicalscreen;

gl_getcontext(&physicalscreen).

To define a virtual screen in system memory, use gl_setcontextvgavirtual(3):

gl_setcontextvgavirtual(G320x200x256)

which allocates space for a screen identical to 320x200x256 graphics mode, and makes this virtual screen the current graphics context.

The virtual screen can now be copied to the physical screen as follows:

gl_copyscreen(&physicalscreen);

Note that with a virtual screen in system memory, it is possible to add fast X-Window support to a program, using MITSHM to copy the framebuffer to the screen window.

## 2. DESCRIPTION OF VGAGL FUNCTIONS

### Context management
gl_getcontext(3), currentcontext(3)

get the current graphics contents..

gl_setcontext(3)

set a previously saved context.

gl_setcontextvga(3)

set the context to the physical screen.

gl_setcontextvgavirtual(3)

set the context to a virtual mode.

gl_setcontextvirtual(3)

define a virtual context.

gl_allocatecontext(3)

allocate a graphics context.

gl_freecontext(3)

free a virtual screen.

gl_setcontextwidth(3), gl_setcontextheight(3)

set the dimension of a context.

### Drawing primitives
gl_clearscreen(3)

clear the screen.

gl_rgbcolor(3)

return pixel value corresponding to an rgb color.

gl_setpixel(3), gl_setpixelrgb(3)

draw a pixel.

gl_getpixel(3)

return the color of a pixel.

gl_getpixelrgb(3)

store color components of a pixel.

gl_hline(3)

draw a horizontal line.

gl_line(3)

draw a line.

gl_circle(3)

draw a circle.

gl_fillbox(3)

fill a rectangular area.

### Copying of screen buffers and page flipping
gl_copyscreen(3)

copy the screen contents of contexts.

gl_setscreenoffset(3)

set a memory offset for copyscreen.

gl_setdisplaystart(3)

set the start of the screen are displayed.

gl_enablepageflipping(3)

enables automatic page flipping.

### Clipping
gl_disableclipping(3)

disables clipping.

gl_enableclipping(3)

enables clipping.

gl_setclippingwindow(3)

set the clipping window.

### Text drawing primitives
gl_setfont(3)

set the text font to be used.

gl_setfontcolors(3)

set the font colors.

gl_expandfont(3)

expand a packed pixel font.

gl_colorfont(3)

change the color of a font.

gl_setwritemode(3)

set the font writemode flags.

gl_write(3), gl_writen(3)

write a text string.

gl_printf(3)

formatted output to the graphics screen.

gl_font8x8(3)

a packed 8x8 pixel font.

### Pix- and Bitmap drawing
gl_getbox(3)

copy a rectangular pixmap from the screen to a buffer.

gl_copybox(3)

copy a rectangular screen area.

gl_copyboxfromcontext(3)

copy rectangular area from another context.

gl_copyboxtocontext(3)

copy a rectangular area to another context.

gl_putbox(3)

copy a pixmap to a rectangular area.

gl_putboxpart(3)

copy a partial pixmap to a rectangular area.

gl_putboxmask(3)

copy a masked pixmap to a rectangular area.

gl_putboxmaskcompiled(3)

copy a compiled masked pixmap to a rectangular area.

gl_compileboxmask(3)

compress a masked bitmap.

gl_compiledboxmasksize(3)

compute the size of a compiled masked box.

gl_scalebox(3)

scale a pixmap.

### Palette handling
gl_getpalettecolor(3), gl_getpalettecolors(3), gl_getpalette(3)

read the color palette.

gl_setpalettecolor(3), gl_setpalettecolors(3), gl_setpalette(3)

set the color palette.

gl_setrgbpalette(3)

set a 256-color RGB palette.

### Triangle primitives from threeDkit
gl_striangle(3)

draw a solid colored triangle.

gl_triangle(3)

draw a triangle with interpolated colors.

gl_swtriangle(3)

draw a solid pixmap mapped on a triangle.

gl_wtriangle(3)

draw a shadowed pixmap mapped on a triangle.

gl_trisetcolorlookup(3), gl_trigetcolorlookup(3)

manages a color lookup table for shadowing.

gl_trisetdrawpoint(3)

set a triangle drawing function.

## 3. MACROS DEFINED IN VGAGL.H:
WIDTH

The width in pixels of the current graphics context.

HEIGHT

Height in pixels.

BYTESPERPIXEL

Number of bytes per pixel (1, 2, 3 or 4).

BYTEWIDTH

Width of a scanline in bytes.

COLORS

Number of colors.

BITSPERPIXEL

Number of significant color bits.

VBUF

Address of the framebuffer.

__clip

Clipping flag.

__clipx1

__clipy1

Top-left corner of clipping window.

__clipx2

__clipy2

Bottom-right corner of clipping window.

## BUGS
For three bytes per pixel (true color) modes, it is possible that pixels cross a SVGA segment boundary. This should be correctly handled by most functions, but you never know. It can be avoided by using a logical scanline length that is a divisor of 65536 (a power of 2), like 1024 (as opposed to 960) for 320x200 and 2048 (1920) for 640x480. For 800x600, this is impractical (4096 as opposed to 2400 doesn't fit in 2MB). Alternatively, avoid those functions by using a virtual screen.

## SEE ALSO
svgalib(7), libvga.config(5), testgl(6), threedkit(7), currentcontext(3), gl_allocatecontext(3), gl_circle(3), gl_clearscreen(3), gl_colorfont(3), gl_compileboxmask(3), gl_compiledboxmasksize(3), gl_copybox(3), gl_copyboxfromcontext(3), gl_copyboxtocontext(3), gl_copyscreen(3), gl_disableclipping(3), gl_enableclipping(3), gl_enablepageflipping(3), gl_expandfont(3), gl_fillbox(3), gl_font8x8(3), gl_freecontext(3), gl_getbox(3), gl_getcontext(3), gl_getpalette(3), gl_getpalettecolor(3), gl_getpalettecolors(3), gl_getpixel(3), gl_getpixelrgb(3), gl_hline(3), gl_line(3), gl_putbox(3), gl_putboxmask(3), gl_putboxmaskcompiled(3), gl_putboxpart(3), gl_rgbcolor(3), gl_scalebox(3), gl_setclippingwindow(3), gl_setcontext(3), gl_setcontextheight(3), gl_setcontextvga(3), gl_setcontextvgavirtual(3), gl_setcontextvirtual(3), gl_setcontextwidth(3), gl_setdisplaystart(3), gl_setfont(3), gl_setfontcolors(3), gl_setpalette(3), gl_setpalettecolor(3), gl_setpalettecolors(3), gl_setpixel(3), gl_setpixelrgb(3), gl_setrgbpalette(3), gl_setscreenoffset(3), gl_setwritemode(3), gl_striangle(3), gl_swtriangle(3), gl_triangle(3), gl_trigetcolorlookup(3), gl_trisetcolorlookup(3), gl_trisetdrawpoint(3), gl_write(3), gl_writen(3), gl_wtriangle(3).

## AUTHOR
There are many authors of svgalib. This page was edited by Michael Weller <eowmob@exp-math.uni-essen.de>. The original documentation and most of vgagl was done by Harm Hanemaayer <H.Hanemaayer@inter.nl.net> though.


sway-ipc

package: sway

title: sway-ipc(7)

text:
# sway-ipc(7)

## NAME
sway-ipc - IPC protocol for sway

## DESCRIPTION
This details the interprocess communication (IPC) protocol for sway(1). This IPC protocol can be used to control or obtain information from a sway process.

The IPC protocol uses a UNIX socket as the method of communication. The path to the socket is stored in the environment variable SWAYSOCK and, for backwards compatibility with i3, I3SOCK. You can also retrieve the socket path by calling sway --get-socketpath.

## MESSAGE AND REPLY FORMAT
The format for messages and replies is:

<magic-string> <payload-length> <payload-type> <payload>

Where

<magic-string> is i3-ipc, for compatibility with i3

<payload-length> is a 32-bit integer in native byte order

<payload-type> is a 32-bit integer in native byte order For example, sending the exit command would look like the following hexdump:

```
00000000 | 69 33 2d 69 70 63 04 00 00 00 00 00 00 00 65 78 |i3-ipc........ex|
00000010 | 69 74                                           |it              |
```

The payload for replies will be a valid serialized JSON data structure.

## MESSAGES AND REPLIES
The following message types and their corresponding reply types are currently supported. For all replies, any properties not listed are subject to removal.

TYPE NUMBER

MESSAGE NAME

PURPOSE

0

RUN_COMMAND

Runs the payload as sway commands

1

GET_WORKSPACES

Get the list of current workspaces

2

SUBSCRIBE

Subscribe the IPC connection to the events listed in the payload

3

GET_OUTPUTS

Get the list of current outputs

4

GET_TREE

Get the node layout tree

5

GET_MARKS

Get the names of all the marks currently set

6

GET_BAR_CONFIG

Get the specified bar config or a list of bar config names

7

GET_VERSION

Get the version of sway that owns the IPC socket

8

GET_BINDING_MODES

Get the list of binding mode names

9

GET_CONFIG

Returns the config that was last loaded

10

SEND_TICK

Sends a tick event with the specified payload

11

SYNC

Replies failure object for i3 compatibility

12

GET_BINDING_STATE

Request the current binding state, e.g. the currently active binding mode name.

100

GET_INPUTS

Get the list of input devices

101

GET_SEATS

Get the list of seats

### 0. RUN_COMMAND
MESSAGE

Parses and runs the payload as sway commands

REPLY

An array of objects corresponding to each command that was parsed. Each object has the property success, which is a boolean indicating whether the command was successful. The object may also contain the properties error and parse_error. The error property is a human readable error message while parse_error is a boolean indicating whether the reason the command failed was because the command was unknown or not able to be parsed.

Example Reply:

```
[
	{
		"success": true
	},
	{
		"success": false,
		"parse_error": true,
		"error": "Invalid/unknown command"
	}
]
```

### 1. GET_WORKSPACES
MESSAGE

Retrieves the list of workspaces.

REPLY

The reply is an array of objects corresponding to each workspace. Each object has the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

num

integer

The workspace number or -1 for workspaces that do not start with a number

name

string

The name of the workspace

visible

boolean

Whether the workspace is currently visible on any output

focused

boolean

Whether the workspace is currently focused by the default seat (seat0)

urgent

boolean

Whether a window on the workspace has the urgent flag set

rect

object

The bounds of the workspace. It consists of x, y, width, and height

output

string

The name of the output that the workspace is on

Example Reply:

```
[
	{
		"num": 1,
		"name": "1",
		"visible": true,
		"focused": true,
		"rect": {
			"x": 0,
			"y": 23,
			"width": 1920,
			"height": 1057
		},
		"output": "eDP-1"
	},
]
```

### 2. SUBSCRIBE
MESSAGE

Subscribe this IPC connection to the event types specified in the message payload. The payload should be a valid JSON array of events. See the EVENTS section for the list of supported events.

REPLY

A single object that contains the property success, which is a boolean value indicating whether the subscription was successful or not.

Example Reply:

```
{
	"success": true
}
```

### 3. GET_OUTPUTS
MESSAGE

Retrieve the list of outputs

REPLY

An array of objects corresponding to each output. Each object has the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

name

string

The name of the output. On DRM, this is the connector

make

string

The make of the output

model

string

The model of the output

serial

string

The output's serial number as a hexadecimal string

active

boolean

Whether this output is active/enabled

dpms

boolean

(Deprecated, use power instead) Whether this output is on/off (via DPMS)

power

boolean

Whether this output is on/off

primary

boolean

For i3 compatibility, this will be false. It does not make sense in Wayland

scale

float

The scale currently in use on the output or -1 for disabled outputs

subpixel_hinting

string

The subpixel hinting current in use on the output. This can be rgb, bgr, vrgb, vbgr, or none

transform

string

The transform currently in use for the output. This can be normal, 90, 180, 270, flipped-90, flipped-180, or flipped-270

current_workspace

string

The workspace currently visible on the output or null for disabled outputs

modes

array

An array of supported mode objects. Each object contains width, height, and refresh

current_mode

object

An object representing the current mode containing width, height, and refresh

rect

object

The bounds for the output consisting of x, y, width, and height

hdr

boolean

Whether HDR is enabled

Example Reply:

```
[
	{
		"name": "HDMI-A-2",
		"make": "Unknown",
		"model": "NS-19E310A13",
		"serial": "0x00000001",
		"active": true,
		"primary": false,
		"scale": 1.0,
		"subpixel_hinting": "rgb",
		"transform": "normal",
		"current_workspace": "1",
		"modes": [
			{
				"width": 640,
				"height": 480,
				"refresh": 59940
			},
			{
				"width": 800,
				"height": 600,
				"refresh": 60317
			},
			{
				"width": 1024,
				"height": 768,
				"refresh": 60004
			},
			{
				"width": 1920,
				"height": 1080,
				"refresh": 60000
			}
		],
		"current_mode": {
			"width": 1920,
			"height": 1080,
			"refresh": 60000
		}
	}
]
```

### 4. GET_TREE
MESSAGE

Retrieve a JSON representation of the tree

REPLY

An array of objects that represent the current tree. Each object represents one node and will have the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

id

integer

The internal unique ID for this node

name

string

The name of the node such as the output name or window title. For the scratchpad, this will be __i3_scratch for compatibility with i3.

type

string

The node type. It can be root, output, workspace, con, or floating_con

border

string

The border style for the node. It can be normal, none, pixel, or csd

current_border_width

integer

Number of pixels used for the border width

layout

string

The node's layout. It can either be splith, splitv, stacked, tabbed, or output

orientation

string

The node's orientation. It can be vertical, horizontal, or none

percent

float

The percentage of the node's parent that it takes up or null for the root and other special nodes such as the scratchpad

rect

object

The absolute geometry of the node. The window decorations are excluded from this, but borders are included.

window_rect

object

The geometry of the content inside the node. These coordinates are relative to the node itself. Window decorations and borders are outside the window_rect

deco_rect

object

The geometry of the decorations for the node relative to the parent node

geometry

object

The natural geometry of the contents if it were to size itself

urgent

boolean

Whether the node or any of its descendants has the urgent hint set. Note: This may not exist when compiled without xwayland support

sticky

boolean

Whether the node is sticky (shows on all workspaces)

marks

array

List of marks assigned to the node

focused

boolean

Whether the node is currently focused by the default seat (seat0)

focus

array

Array of child node IDs in the current focus order

nodes

array

The tiling children nodes for the node

floating_nodes

array

The floating children nodes for the node

representation

string

(Only workspaces) A string representation of the layout of the workspace that can be used as an aid in submitting reproduction steps for bug reports

fullscreen_mode

integer

(Only containers and windows) The fullscreen mode of the node. 0 means none, 1 means full workspace, and 2 means global fullscreen

floating

string

Floating state of container. Can be either "auto_off" or "user_on"

scratchpad_state

string

Whether the window is in the scratchpad. Can be either "none" or "fresh"

app_id

string

(Only windows) For an xdg-shell window, the name of the application, if set. Otherwise, null

pid

integer

(Only windows) The PID of the application that owns the window

foreign_toplevel_identifier

string

(Only windows) The ext-foreign-toplevel-list-v1 toplevel identifier of this node.

visible

boolean

(Only windows) Whether the node is visible

shell

string

(Only windows) The shell of the window, such as xdg_shell or xwayland

inhibit_idle

boolean

(Only windows) Whether the window is inhibiting the idle state

idle_inhibitors

object

(Only windows) An object containing the state of the application and user idle inhibitors. application can be enabled or none. user can be focus, fullscreen, open, visible or none.

sandbox_engine

string

(Only windows) The associated sandbox engine (or null)

sandbox_app_id

string

(Only windows) The app ID provided by the associated sandbox engine (or null)

sandbox_instance_id

string

(Only windows) The instance ID provided by the associated sandbox engine (or null)

tag

string

(Only windows) For an xdg-shell window, tag of the toplevel, if set. Otherwise, null

window

integer

(Only xwayland windows) The X11 window ID for the xwayland window

window_properties

object

(Only xwayland windows) An object containing the title, class, instance, window_role, window_type, and transient_for for the window

Example Reply:

```
{
	"id": 1,
	"name": "root",
	"rect": {
		"x": 0,
		"y": 0,
		"width": 1920,
		"height": 1080
	},
	"focused": false,
	"focus": [
		3
	],
	"border": "none",
	"current_border_width": 0,
	"layout": "splith",
	"orientation": "horizontal",
	"percent": null,
	"window_rect": {
		"x": 0,
		"y": 0,
		"width": 0,
		"height": 0
	},
	"deco_rect": {
		"x": 0,
		"y": 0,
		"width": 0,
		"height": 0
	},
	"geometry": {
		"x": 0,
		"y": 0,
		"width": 0,
		"height": 0
	},
	"window": null,
	"urgent": false,
	"floating_nodes": [
	],
	"sticky": false,
	"type": "root",
	"nodes": [
		{
			"id": 2147483647,
			"name": "__i3",
			"rect": {
				"x": 0,
				"y": 0,
				"width": 1920,
				"height": 1080
			},
			"focused": false,
			"focus": [
				2147483646
			],
			"border": "none",
			"current_border_width": 0,
			"layout": "output",
			"orientation": "horizontal",
			"percent": null,
			"window_rect": {
				"x": 0,
				"y": 0,
				"width": 0,
				"height": 0
			},
			"deco_rect": {
				"x": 0,
				"y": 0,
				"width": 0,
				"height": 0
			},
			"geometry": {
				"x": 0,
				"y": 0,
				"width": 0,
				"height": 0
			},
			"window": null,
			"urgent": false,
			"floating_nodes": [
			],
			"sticky": false,
			"type": "output",
			"nodes": [
				{
					"id": 2147483646,
					"name": "__i3_scratch",
					"rect": {
						"x": 0,
						"y": 0,
						"width": 1920,
						"height": 1080
					},
					"focused": false,
					"focus": [
					],
					"border": "none",
					"current_border_width": 0,
					"layout": "splith",
					"orientation": "horizontal",
					"percent": null,
					"window_rect": {
						"x": 0,
						"y": 0,
						"width": 0,
						"height": 0
					},
					"deco_rect": {
						"x": 0,
						"y": 0,
						"width": 0,
						"height": 0
					},
					"geometry": {
						"x": 0,
						"y": 0,
						"width": 0,
						"height": 0
					},
					"window": null,
					"urgent": false,
					"floating_nodes": [
					],
					"sticky": false,
					"type": "workspace"
				}
			]
		},
		{
			"id": 3,
			"name": "eDP-1",
			"rect": {
				"x": 0,
				"y": 0,
				"width": 1920,
				"height": 1080
			},
			"focused": false,
			"focus": [
				4
			],
			"border": "none",
			"current_border_width": 0,
			"layout": "output",
			"orientation": "none",
			"percent": 1.0,
			"window_rect": {
				"x": 0,
				"y": 0,
				"width": 0,
				"height": 0
			},
			"deco_rect": {
				"x": 0,
				"y": 0,
				"width": 0,
				"height": 0
			},
			"geometry": {
				"x": 0,
				"y": 0,
				"width": 0,
				"height": 0
			},
			"window": null,
			"urgent": false,
			"floating_nodes": [
			],
			"sticky": false,
			"type": "output",
			"active": true,
			"primary": false,
			"make": "Unknown",
			"model": "0x38ED",
			"serial": "0x00000000",
			"scale": 1.0,
			"transform": "normal",
			"current_workspace": "1",
			"modes": [
				{
					"width": 1920,
					"height": 1080,
					"refresh": 60052
				}
			],
			"current_mode": {
				"width": 1920,
				"height": 1080,
				"refresh": 60052
			},
			"nodes": [
				{
					"id": 4,
					"name": "1",
					"rect": {
						"x": 0,
						"y": 23,
						"width": 1920,
						"height": 1057
					},
					"focused": false,
					"focus": [
						6,
						5
					],
					"border": "none",
					"current_border_width": 0,
					"layout": "splith",
					"orientation": "horizontal",
					"percent": null,
					"window_rect": {
						"x": 0,
						"y": 0,
						"width": 0,
						"height": 0
					},
					"deco_rect": {
						"x": 0,
						"y": 0,
						"width": 0,
						"height": 0
					},
					"geometry": {
						"x": 0,
						"y": 0,
						"width": 0,
						"height": 0
					},
					"window": null,
					"urgent": false,
					"floating_nodes": [
					],
					"sticky": false,
					"num": 1,
					"output": "eDP-1",
					"type": "workspace",
					"representation": "H[URxvt termite]",
					"nodes": [
						{
							"id": 5,
							"name": "urxvt",
							"rect": {
								"x": 0,
								"y": 23,
								"width": 960,
								"height": 1057
							},
							"focused": false,
							"focus": [
							],
							"border": "normal",
							"current_border_width": 2,
							"layout": "none",
							"orientation": "none",
							"percent": 0.5,
							"window_rect": {
								"x": 2,
								"y": 0,
								"width": 956,
								"height": 1030
							},
							"deco_rect": {
								"x": 0,
								"y": 0,
								"width": 960,
								"height": 25
							},
							"geometry": {
								"x": 0,
								"y": 0,
								"width": 1124,
								"height": 422
							},
							"window": 4194313,
							"urgent": false,
							"floating_nodes": [
							],
							"sticky": false,
							"type": "con",
							"fullscreen_mode": 0,
							"pid": 23959,
							"app_id": null,
							"visible": true,
							"shell": "xwayland",
							"inhibit_idle": true,
							"idle_inhibitors": {
								"application": "none",
								"user": "visible",
							},
							"window_properties": {
								"class": "URxvt",
								"instance": "urxvt",
								"title": "urxvt",
								"transient_for": null
							},
							"nodes": [
							]
						},
						{
							"id": 6,
							"name": "",
							"rect": {
								"x": 960,
								"y": 23,
								"width": 960,
								"height": 1057
							},
							"focused": true,
							"focus": [
							],
							"border": "normal",
							"current_border_width": 2,
							"layout": "none",
							"orientation": "none",
							"percent": 0.5,
							"window_rect": {
								"x": 2,
								"y": 0,
								"width": 956,
								"height": 1030
							},
							"deco_rect": {
								"x": 0,
								"y": 0,
								"width": 960,
								"height": 25
							},
							"geometry": {
								"x": 0,
								"y": 0,
								"width": 817,
								"height": 458
							},
							"window": null,
							"urgent": false,
							"floating_nodes": [
							],
							"sticky": false,
							"type": "con",
							"fullscreen_mode": 0,
							"pid": 25370,
							"app_id": "termite",
							"visible": true,
							"shell": "xdg_shell",
							"inhibit_idle": false,
							"idle_inhibitors": {
								"application": "none",
								"user": "fullscreen",
							},
							"nodes": [
							]
						}
					]
				}
			]
		}
	]
}
```

### 5. GET_MARKS
MESSAGE

Retrieve the currently set marks

REPLY

An array of marks currently set. Since each mark can only be set for one container, this is a set so each value is unique and the order is undefined.

Example Reply:

```
[
	"one",
	"test"
]
```

### 6. GET_BAR_CONFIG (WITHOUT A PAYLOAD)
MESSAGE

When sending without a payload, this retrieves the list of configured bar IDs

REPLY

An array of bar IDs, which are strings

Example Reply:

```
[
	"bar-0",
	"bar-1"
]
```

### 6. GET_BAR_CONFIG (WITH A PAYLOAD)
MESSAGE

When sent with a bar ID as the payload, this retrieves the config associated with the bar ID specified in the payload. This is used by swaybar, but could also be used for third-party bars

REPLY

An object that represents the configuration for the bar with the bar ID sent as the payload. The following properties exist, with more information about their values in sway-bar(5):

PROPERTY

DATA TYPE

DESCRIPTION

id

string

The bar ID

mode

string

The mode for the bar. It can be dock, hide, or invisible

position

string

The bar's position. It can currently either be bottom or top

status_command

string

The command which should be run to generate the status line

font

string

The font to use for the text on the bar

workspace_buttons

boolean

Whether to display the workspace buttons on the bar

workspace_min_width

integer

Minimum width in px for the workspace buttons on the bar

binding_mode_indicator

boolean

Whether to display the current binding mode on the bar

verbose

boolean

For i3 compatibility, this will be the boolean value false.

colors

object

An object containing the #RRGGBBAA colors to use for the bar. See below for more information

gaps

object

An object representing the gaps for the bar consisting of top, right, bottom, and left.

bar_height

integer

The absolute height to use for the bar or 0 to automatically size based on the font

status_padding

integer

The vertical padding to use for the status line

status_edge_padding

integer

The horizontal padding to use for the status line when at the end of an output

The colors object contains the following properties, which are all strings containing the #RRGGBBAA representation of the color:

PROPERTY

DESCRIPTION

background

The color to use for the bar background on unfocused outputs

statusline

The color to use for the status line text on unfocused outputs

separator

The color to use for the separator text on unfocused outputs

focused_background

The color to use for the background of the bar on the focused output

focused_statusline

The color to use for the status line text on the focused output

focused_separator

The color to use for the separator text on the focused output

focused_workspace_text

The color to use for the text of the focused workspace button

focused_workspace_bg

The color to use for the background of the focused workspace button

focused_workspace_border

The color to use for the border of the focused workspace button

active_workspace_text

The color to use for the text of the workspace buttons for the visible workspaces on unfocused outputs

active_workspace_bg

The color to use for the background of the workspace buttons for the visible workspaces on unfocused outputs

active_workspace_border

The color to use for the border of the workspace buttons for the visible workspaces on unfocused outputs

inactive_workspace_text

The color to use for the text of the workspace buttons for workspaces that are not visible

inactive_workspace_bg

The color to use for the background of the workspace buttons for workspaces that are not visible

inactive_workspace_border

The color to use for the border of the workspace buttons for workspaces that are not visible

urgent_workspace_text

The color to use for the text of the workspace buttons for workspaces that contain an urgent window

urgent_workspace_bg

The color to use for the background of the workspace buttons for workspaces that contain an urgent window

urgent_workspace_border

The color to use for the border of the workspace buttons for workspaces that contain an urgent window

binding_mode_text

The color to use for the text of the binding mode indicator

binding_mode_bg

The color to use for the background of the binding mode indicator

binding_mode_border

The color to use for the border of the binding mode indicator

Example Reply:

```
{
	"id": "bar-0",
	"mode": "dock",
	"position": "top",
	"status_command": "while date +'%Y-%m-%d %l:%M:%S %p'; do sleep 1; done",
	"font": "monospace 10",
	"gaps": {
		"top": 0,
		"right": 0,
		"bottom": 0,
		"left": 0
	},
	"bar_height": 0,
	"status_padding": 1,
	"status_edge_padding": 3,
	"workspace_buttons": true,
	"workspace_min_width": 0,
	"binding_mode_indicator": true,
	"verbose": false,
	"pango_markup": false,
	"colors": {
		"background": "#323232ff",
		"statusline": "#ffffffff",
		"separator": "#666666ff",
		"focused_background": "#323232ff",
		"focused_statusline": "#ffffffff",
		"focused_separator": "#666666ff",
		"focused_workspace_border": "#4c7899ff",
		"focused_workspace_bg": "#285577ff",
		"focused_workspace_text": "#ffffffff",
		"inactive_workspace_border": "#32323200",
		"inactive_workspace_bg": "#32323200",
		"inactive_workspace_text": "#5c5c5cff",
		"active_workspace_border": "#333333ff",
		"active_workspace_bg": "#5f676aff",
		"active_workspace_text": "#ffffffff",
		"urgent_workspace_border": "#2f343aff",
		"urgent_workspace_bg": "#900000ff",
		"urgent_workspace_text": "#ffffffff",
		"binding_mode_border": "#2f343aff",
		"binding_mode_bg": "#900000ff",
		"binding_mode_text": "#ffffffff"
	},
}
```

### 7. GET_VERSION
MESSAGE

Retrieve version information about the sway process

REPLY

An object containing the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

major

integer

The major version of the sway process

minor

integer

The minor version of the sway process

patch

integer

The patch version of the sway process

human_readable

string

A human readable version string that will likely contain more useful information such as the git commit short hash and git branch

loaded_config_file_name

string

The path to the loaded config file

Example Reply:

```
{
	"human_readable": "1.0-rc1-117-g2f7247e0 (Feb 24 2019, branch 'master')",
	"major": 1,
	"minor": 0,
	"patch": 0,
	"loaded_config_file_name": "/home/redsoxfan/.config/sway/config"
}
```

### 8. GET_BINDING_MODES
MESSAGE

Retrieve the list of binding modes that are currently configured

REPLY

An array of strings, with each string being the name of a binding mode. This will always contain at least one mode (currently default), which is the default binding mode

Example Reply:

```
[
	"default",
	"resize",
]
```

### 9. GET_CONFIG
MESSAGE

Retrieve the contents of the config that was last loaded

REPLY

An object with a single string property containing the contents of the config

Example Reply:

```
{
	"config": "set $mod Mod4\nbindsym $mod+q exit\n"
}
```

### 10. SEND_TICK
MESSAGE

Issues a TICK event to all clients subscribing to the event to ensure that all events prior to the tick were received. If a payload is given, it will be included in the TICK event

REPLY

A single object contains the property success, which is a boolean value indicating whether the TICK event was sent.

Example Reply:

```
{
	"success": true
}
```

### 11. SYNC
MESSAGE

For i3 compatibility, this command will just return a failure object since it does not make sense to implement in sway due to the X11 nature of the command. If you are curious about what this IPC command does in i3, refer to the i3 documentation.

REPLY

A single object that contains the property success, which is set to the boolean value false.

Exact Reply:

```
{
	"success": false
}
```

### 12. GET_BINDING_STATE
MESSAGE

Returns the currently active binding mode.

REPLY

A single object that contains the property name, which is set to the currently active binding mode as a string.

Example Reply:

```
{
	"name": "default"
}
```

### 100. GET_INPUTS
MESSAGE

Retrieve a list of the input devices currently available

REPLY

An array of objects corresponding to each input device. Each object has the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

identifier

string

The identifier for the input device

name

string

The human readable name for the device

vendor

integer

The vendor code for the input device

product

integer

The product code for the input device

type

string

The device type. Currently this can be keyboard, pointer, touch, tablet_tool, tablet_pad, or switch

xkb_active_layout_name

string

(Only keyboards) The name of the active keyboard layout

xkb_layout_names

array

(Only keyboards) A list a layout names configured for the keyboard

xkb_active_layout_index

integer

(Only keyboards) The index of the active keyboard layout

scroll_factor

floating

(Only pointers) Multiplier applied on scroll event values.

libinput

object

(Only libinput devices) An object describing the current device settings. See below for more information

The libinput object describes the device configuration for libinput devices. Only properties that are supported for the device will be added to the object. In addition to the possible options listed, all string properties may also be unknown, in the case that a new option is added to libinput. See sway-input(5) for information on the meaning of the possible values. The following properties will be included for devices that support them:

PROPERTY

DATA TYPE

DESCRIPTION

send_events

string

Whether events are being sent by the device. It can be enabled, disabled, or disabled_on_external_mouse

tap

string

Whether tap to click is enabled. It can be enabled or disabled

tap_button_map

string

The finger to button mapping in use for tapping. It can be lmr or lrm

tap_drag

string

Whether tap-and-drag is enabled. It can be enabled or disabled

tap_drag_lock

string

Whether drag-lock is enabled. It can be enabled, disabled or enabled_sticky

accel_speed

double

The pointer-acceleration in use

accel_profile

string

The acceleration profile in use. It can be none, flat, or adaptive

natural_scroll

string

Whether natural scrolling is enabled. It can be enabled or disabled

left_handed

string

Whether left-handed mode is enabled. It can be enabled or disabled

click_method

string

The click method in use. It can be none, button_areas, or clickfinger

click_button_map

string

The finger to button mapping in use for clickfinger. It can be lmr or lrm

middle_emulation

string

Whether middle emulation is enabled. It can be enabled or disabled

scroll_method

string

The scroll method in use. It can be none, two_finger, edge, or on_button_down

scroll_button

int

The scroll button to use when scroll_method is on_button_down. This will be given as an input event code

scroll_button_lock

string

Whether scroll button lock is enabled. It can be enabled or disabled

dwt

string

Whether disable-while-typing is enabled. It can be enabled or disabled

dwtp

string

Whether disable-while-trackpointing is enabled. It can be enabled or_disabled_

calibration_matrix

array

An array of 6 floats representing the calibration matrix for absolute devices such as touchscreens

Example Reply:

```
[
	{
		"identifier": "1:1:AT_Translated_Set_2_keyboard",
		"name": "AT Translated Set 2 keyboard",
		"vendor": 1,
		"product": 1,
		"type": "keyboard",
		"xkb_active_layout_name": "English (US)",
		"libinput": {
			"send_events": "enabled"
		}
	},
	{
		"identifier": "1267:5:Elan_Touchpad",
		"name": "Elan Touchpad",
		"vendor": 1267,
		"product": 5,
		"type": "pointer",
		"libinput": {
			"send_events": "enabled",
			"tap": "enabled",
			"tap_button_map": "lmr",
			"tap_drag": "enabled",
			"tap_drag_lock": "disabled",
			"accel_speed": 0.0,
			"accel_profile": "none",
			"natural_scroll", "disabled",
			"left_handed": "disabled",
			"click_method": "button_areas",
			"middle_emulation": "disabled",
			"scroll_method": "edge",
			"dwt": "enabled",
			"dwtp": "enabled"
		}
	},
	{
		"identifier": "3034:22494:USB2.0_VGA_UVC_WebCam:_USB2.0_V",
		"name": "USB2.0 VGA UVC WebCam: USB2.0 V",
		"vendor": 3034,
		"product": 22494,
		"type": "keyboard",
		"xkb_active_layout_name": "English (US)",
		"libinput": {
			"send_events": "enabled"
		}
	},
	{
		"identifier": "0:3:Sleep_Button",
		"name": "Sleep Button",
		"vendor": 0,
		"product": 3,
		"type": "keyboard",
		"xkb_active_layout_name": "English (US)",
		"libinput": {
			"send_events": "enabled"
		}
	},
	{
		"identifier": "0:5:Lid_Switch",
		"name": "Lid Switch",
		"vendor": 0,
		"product": 5,
		"type": "switch",
		"libinput": {
			"send_events": "enabled"
		}
	},
	{
		"identifier": "0:6:Video_Bus",
		"name": "Video Bus",
		"vendor": 0,
		"product": 6,
		"type": "keyboard",
		"xkb_active_layout_name": "English (US)",
		"libinput": {
			"send_events": "enabled"
		}
	},
	{
		"identifier": "0:1:Power_Button",
		"name": "Power Button",
		"vendor": 0,
		"product": 1,
		"type": "keyboard",
		"xkb_active_layout_name": "English (US)",
		"libinput": {
			"send_events": "enabled"
		}
	}
]
```

### 101. GET_SEATS
MESSAGE

Retrieve a list of the seats currently configured

REPLY

An array of objects corresponding to each seat. There will always be at least one seat. Each object has the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

name

string

The unique name for the seat

capabilities

integer

The number of capabilities that the seat has

focus

integer

The id of the node currently focused by the seat or 0 when the seat is not currently focused by a node (i.e. a surface layer or xwayland unmanaged has focus)

devices

array

An array of input devices that are attached to the seat. Currently, this is an array of objects that are identical to those returned by GET_INPUTS

Example Reply:

```
[
	{
		"name": "seat0",
		"capabilities": 3,
		"focus": 7,
		"devices": [
			{
				"identifier": "1:1:AT_Translated_Set_2_keyboard",
				"name": "AT Translated Set 2 keyboard",
				"vendor": 1,
				"product": 1,
				"type": "keyboard",
				"xkb_active_layout_name": "English (US)",
				"libinput": {
					"send_events": "enabled"
				}
			},
			{
				"identifier": "1267:5:Elan_Touchpad",
				"name": "Elan Touchpad",
				"vendor": 1267,
				"product": 5,
				"type": "pointer",
				"libinput": {
					"send_events": "enabled",
					"tap": "enabled",
					"tap_button_map": "lmr",
					"tap_drag": "enabled",
					"tap_drag_lock": "disabled",
					"accel_speed": 0.0,
					"accel_profile": "none",
					"natural_scroll", "disabled",
					"left_handed": "disabled",
					"click_method": "button_areas",
					"middle_emulation": "disabled",
					"scroll_method": "edge",
					"dwt": "enabled",
					"dwtp": "enabled"
				}
			},
			{
				"identifier": "3034:22494:USB2.0_VGA_UVC_WebCam:_USB2.0_V",
				"name": "USB2.0 VGA UVC WebCam: USB2.0 V",
				"vendor": 3034,
				"product": 22494,
				"type": "keyboard",
				"xkb_active_layout_name": "English (US)",
				"libinput": {
					"send_events": "enabled"
				}
			},
			{
				"identifier": "0:3:Sleep_Button",
				"name": "Sleep Button",
				"vendor": 0,
				"product": 3,
				"type": "keyboard",
				"xkb_active_layout_name": "English (US)",
				"libinput": {
					"send_events": "enabled"
				}
			},
			{
				"identifier": "0:5:Lid_Switch",
				"name": "Lid Switch",
				"vendor": 0,
				"product": 5,
				"type": "switch",
				"libinput": {
					"send_events": "enabled"
				}
			},
			{
				"identifier": "0:6:Video_Bus",
				"name": "Video Bus",
				"vendor": 0,
				"product": 6,
				"type": "keyboard",
				"xkb_active_layout_name": "English (US)",
				"libinput": {
					"send_events": "enabled"
				}
			},
			{
				"identifier": "0:1:Power_Button",
				"name": "Power Button",
				"vendor": 0,
				"product": 1,
				"type": "keyboard",
				"xkb_active_layout_name": "English (US)",
				"libinput": {
					"send_events": "enabled"
				}
			}
		]
	}
]
```

## EVENTS
Events are a way for clients to get notified of changes to sway. A client can subscribe to any events it wants to be notified of changes for. The event is sent in the same format as a reply. The following events are currently available:

EVENT TYPE

NAME

DESCRIPTION

0x80000000

workspace

Sent whenever an event involving a workspace occurs such as initialization of a new workspace or another workspace gaining focus

0x80000001

output

Sent when outputs are updated

0x80000002

mode

Sent whenever the binding mode changes

0x80000003

window

Sent whenever an event involving a window occurs such as it being reparented, focused, or closed

0x80000004

barconfig_update

Sent whenever a bar config changes

0x80000005

binding

Sent when a configured binding is executed

0x80000006

shutdown

Sent when the ipc shuts down because sway is exiting

0x80000007

tick

Sent when an ipc client sends a SEND_TICK message

0x80000014

bar_state_update

Sent when the visibility of a bar should change due to a modifier

0x80000015

input

Sent when something related to input devices changes

### 0x80000000. WORKSPACE
Sent whenever a change involving a workspace occurs. The event consists of a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

change

string

The type of change that occurred. See below for more information

current

object

An object representing the affected workspace or null for reload changes

old

object

For a focus change, this will be an object representing the workspace being switched from. Otherwise, it is null

The following change types are currently available:

TYPE

DESCRIPTION

init

The workspace was created

empty

The workspace is empty and is being destroyed since it is not visible

focus

The workspace was focused. See the old property for the previous focus

move

The workspace was moved to a different output

rename

The workspace was renamed

urgent

A window on the workspace has had its urgency hint set or all urgency hints for windows on the workspace have been cleared

reload

The configuration file has been reloaded

Example Event:

```
{
	"change": "init",
	"old": null,
	"current": {
		"id": 10,
		"name": "2",
		"rect": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"focused": false,
		"focus": [
		],
		"border": "none",
		"current_border_width": 0,
		"layout": "splith",
		"percent": null,
		"window_rect": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"deco_rect": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"geometry": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"window": null,
		"urgent": false,
		"floating_nodes": [
		],
		"num": 2,
		"output": "eDP-1",
		"type": "workspace",
		"representation": null,
		"nodes": [
		]
	}
}
```

### 0x80000001. OUTPUT
Sent whenever an output is added, removed, or its configuration is changed. The event is a single object with the property change, which is a string containing the reason for the change. Currently, the only value for change is unspecified.

Example Event:

```
{
	"change": "unspecified"
}
```

### 0x80000002. MODE
Sent whenever the binding mode changes. The event consists of a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

change

string

The binding mode that became active

pango_markup

boolean

Whether the mode should be parsed as pango markup

Example Event:

```
{
	"change": "default",
	"pango_markup": false
}
```

### 0x80000003. WINDOW
Sent whenever a change involving a window occurs. The event consists of a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

change

string

The type of change that occurred. See below for more information

container

object

An object representing the affected window

The following change types are currently available:

TYPE

DESCRIPTION

new

The window was created

close

The window was closed

focus

The window was focused

title

The window's title has changed

fullscreen_mode

The window's fullscreen mode has changed

move

The window has been reparented in the tree

floating

The window has become floating or is no longer floating

urgent

The window's urgency hint has changed status

mark

A mark has been added or removed from the window

Example Event:

```
{
	"change": "new",
	"container": {
		"id": 12,
		"name": null,
		"rect": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"focused": false,
		"focus": [
		],
		"border": "none",
		"current_border_width": 0,
		"layout": "none",
		"percent": 0.0,
		"window_rect": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"deco_rect": {
			"x": 0,
			"y": 0,
			"width": 0,
			"height": 0
		},
		"geometry": {
			"x": 0,
			"y": 0,
			"width": 1124,
			"height": 422
		},
		"window": 4194313,
		"urgent": false,
		"floating_nodes": [
		],
		"type": "con",
		"pid": 19787,
		"app_id": null,
		"window_properties": {
			"class": "URxvt",
			"instance": "urxvt",
			"transient_for": null
		},
		"nodes": [
		]
	}
}
```

### 0x80000004. BARCONFIG_UPDATE
Sent whenever a config for a bar changes. The event is identical to that of GET_BAR_CONFIG when a bar ID is given as a payload. See 6. GET_BAR_CONFIG (WITH A PAYLOAD) above for more information.

### 0x80000005. BINDING
Sent whenever a binding is executed. The event is a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

change

string

The change that occurred for the binding. Currently this will only be run

command

string

The command associated with the binding

event_state_mask

array

An array of strings that correspond to each modifier key for the binding

input_code

integer

For keyboard bindcodes, this is the key code for the binding. For mouse bindings, this is the X11 button number, if there is an equivalent. In all other cases, this will be 0.

symbol

string

For keyboard bindsyms, this is the bindsym for the binding. Otherwise, this will be null

input_type

string

The input type that triggered the binding. This is either keyboard or mouse

Example Event:

```
{
	"change": "run",
	"binding": {
		"command": "workspace 2",
		"event_state_mask": [
			"Mod4"
		],
		"input_code": 0,
		"symbol": "2",
		"input_type": "keyboard"
	}
}
```

### 0x80000006. SHUTDOWN
Sent whenever the IPC is shutting down. The event is a single object with the property change, which is a string containing the reason for the shutdown. Currently, the only value for change is exit, which is issued when sway is exiting.

Example Event:

```
{
	"change": "exit"
}
```

### 0x80000007. TICK
Sent when first subscribing to tick events or by a SEND_TICK message. The event is a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

first

boolean

Whether this event was triggered by subscribing to the tick events

payload

string

The payload provided in a SEND_TICK message, if any. Otherwise, an empty string

Example Event:

```
{
	"first": true
	"payload": ""
}
```

### 0x80000014. BAR_STATE_UPDATE
Sent when the visibility of a bar changes due to a modifier being pressed. The event is a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

id

string

The bar ID affected

visible_by_modifier

boolean

Whether the bar should be made visible due to a modifier being pressed

Example Event:

```
{
	"id": "bar-0",
	"visible_by_modifier": true
}
```

### 0x80000015. INPUT
Sent when something related to input devices changes. The event is a single object with the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

change

string

What has changed

input

object

An object representing the input that is identical to the ones GET_INPUTS gives

The following change types are currently available:

TYPE

DESCRIPTION

added

The input device became available

removed

The input device is no longer available

xkb_keymap

(Keyboards only) The keymap for the keyboard has changed

xkb_layout

(Keyboards only) The effective layout in the keymap has changed

libinput_config

(libinput device only) A libinput config option for the device changed

Example Event:

```
{
	"change": "xkb_layout",
	"input": {
		"identifier": "1:1:AT_Translated_Set_2_keyboard",
		"name": "AT Translated Set 2 keyboard",
		"vendor": 1,
		"product": 1,
		"type": "keyboard",
		"xkb_layout_names": [
			"English (US)",
			"English (Dvorak)"
		],
		"xkb_active_layout_index": 1,
		"xkb_active_layout_name": "English (Dvorak)",
		"libinput": {
			"send_events": "enabled"
		}
	}
}
```

## SEE ALSO
sway(1) sway(5) sway-bar(5) swaymsg(1) sway-input(5) sway-output(5)


swaybar-protocol

title: swaybar-protocol(7)

text:
# swaybar-protocol(7)

## NAME
swaybar-protocol - JSON status line protocol for swaybar

## SUMMARY
swaybar defines the following JSON protocol to specify what information is displayed in the status line on the right side of swaybar. The protocol comprises a header, that is a JSON object, followed by a newline (0x0A), followed by an infinite JSON array that represents the information to display. All communication is done by writing the status line to standard output and reading events from standard input.

## HEADER
The header is a JSON object with support for the following properties (only version is required):

PROPERTY

DATA TYPE

DEFAULT

DESCRIPTION

version

integer

-

The protocol version to use. Currently, this must be 1

click_events

boolean

false

Whether to receive click event information to standard input

cont_signal

integer

SIGCONT

The signal that swaybar should send to continue processing

stop_signal

integer

SIGSTOP

The signal that swaybar should send to stop processing

### MINIMAL HEADER

```
{
	"version": 1
}
```

### FULL HEADER

```
{
	"version": 1,
	"click_events": true,
	"cont_signal": 18,
	"stop_signal": 19
}
```

## BODY
The body is an infinite array, where each element of the array is a representation of the status line at the time that the element was written. Each element of the array is itself an array of JSON objects, where each object represents a block in the status line. Each block can have the following properties (only full_text is required):

PROPERTY

DATA TYPE

DESCRIPTION

full_text

string

The text that will be displayed. If missing, the block will be skipped.

short_text

string

If given and the text needs to be shortened due to space, this will be displayed instead of full_text

color

string

The text color to use in #RRGGBBAA or #RRGGBB notation

background

string

The background color for the block in #RRGGBBAA or #RRGGBB notation

border

string

The border color for the block in #RRGGBBAA or #RRGGBB notation

border_top

integer

The height in pixels of the top border. The default is 1

border_bottom

integer

The height in pixels of the bottom border. The default is 1

border_left

integer

The width in pixels of the left border. The default is 1

border_right

integer

The width in pixels of the right border. The default is 1

min_width

integer or string

The minimum width to use for the block. This can either be given in pixels or a string can be given to allow for it to be calculated based on the width of the string.

align

string

If the text does not span the full width of the block, this specifies how the text should be aligned inside of the block. This can be left (default), right, or center.

name

string

A name for the block. This is only used to identify the block for click events. If set, each block should have a unique name and instance pair.

instance

string

The instance of the name for the block. This is only used to identify the block for click events. If set, each block should have a unique name and instance pair.

urgent

boolean

Whether the block should be displayed as urgent. Currently swaybar utilizes the colors set in the sway config for urgent workspace buttons. See sway-bar(5) for more information on bar color configuration.

separator

boolean

Whether the bar separator should be drawn after the block. See sway-bar(5) for more information on how to set the separator text.

separator_block_width

integer

The amount of pixels to leave blank after the block. The separator text will be displayed centered in this gap. The default is 9 pixels.

markup

string

The type of markup to use when parsing the text for the block. This can either be pango or none (default).

Other properties may be given and swaybar will ignore any property that it does not know. It is recommended to prefix any custom properties with an underscore to make it easier to distinguish them from protocol properties.

### BODY EXAMPLE

```
[
	[
		{
			"full_text": "25%",
			"min_width": "100%",
			"urgent": false
		},
		{
			"full_text": "Thu 30 May 2019 02:15:15"
		}
	],
	[
		{
			"full_text": "20%",
			"min_width": "100%",
			"urgent": false
		},
		{
			"full_text": "Thu 30 May 2019 02:20:52"
		}
	],
	[
		{
			"full_text": "15%",
			"min_width": "100%",
			"urgent": true
		},
		{
			"full_text": "Thu 30 May 2019 02:25:41"
		}
	],
	...
```

### FULL BLOCK EXAMPLE

```
{
	"full_text": "Thu 30 May 2019 02:09:15",
	"short_text": "02:09",
	"color": "#ccccccff",
	"background": "#111111ff",
	"border": "#222222ff",
	"border_top": 1,
	"border_bottom": 1,
	"border_left": 1,
	"border_right": 1,
	"min_width": 100,
	"align": "center",
	"name": "clock",
	"instance": "edt",
	"urgent": false,
	"separator": true,
	"separator_block_width": 5,
	"markup": "none"
}
```

## CLICK EVENTS
If requested in the header, swaybar will write a JSON object, that can be read from standard in, when the user clicks on a block. The event object will have the following properties:

PROPERTY

DATA TYPE

DESCRIPTION

name

string

The name of the block, if set

instance

string

The instance of the block, if set

x

integer

The x location that the click occurred at

y

integer

The y location that the click occurred at

button

integer

The x11 button number for the click. If the button does not have an x11 button mapping, this will be 0.

event

integer

The event code that corresponds to the button for the click

relative_x

integer

The x location of the click relative to the top-left of the block

relative_y

integer

The y location of the click relative to the top-left of the block

width

integer

The width of the block in pixels

height

integer

The height of the block in pixels

Differences from i3bar's protocol:

- button may be 0 for buttons that do not have x11 button mappings

- event has been introduced to allow for non-x11 buttons to be represented

- The modifiers property is not currently added by swaybar

### EXAMPLE

```
{
	"name": "clock",
	"instance": "edt",
	"x": 1900,
	"y": 10,
	"button": 1,
	"event": 274,
	"relative_x": 100,
	"relative_y": 8,
	"width": 120,
	"height": 18
}
```

## SEE ALSO
sway-bar(5)