diff --git a/docs/PROTOCOLS.md b/docs/PROTOCOLS.md index 26e0091..977ca28 100644 --- a/docs/PROTOCOLS.md +++ b/docs/PROTOCOLS.md @@ -1,19 +1,19 @@ The components communicate between each other using window properties -and ClientMessages. These protocols can also be utilized by other +and `ClientMessage`s. These protocols can also be utilized by other clients to streamline their interaction with the window manager and to provide a better experience to the user. When implementing new protocols, properties extending the data model -of client windows are to be preffered over ClientMessages implementing +of client windows are to be preffered over `ClientMessage`s implementing actions. # Renderer Implemented by: [`glass-renderer`](../glass-renderer) -Window rendering is implemented by the compositor, glass-renderer. It -is controlled by properties both on individual client windows and on -the root window. +Window rendering is implemented by the compositor, `glass-renderer`. +It is controlled by properties both on individual client windows and +on the root window. ## Shader programs @@ -27,20 +27,20 @@ corresponds to the window id and coordinates of that window. ### Shader property mapping All window properties are available to the shader code as uniforms. -You must specify the right type as well as item count, e.g. "vec4 -MY_PROP" corresponds to MY_PROP being of type XA_FLOAT and having 4 -items. Windows and atoms are mapped to int. Uniforms for properties +You must specify the right type as well as item count, e.g. `vec4 +MY_PROP` corresponds to `MY_PROP` being of type `XA_FLOAT` and having +4 items. Windows and atoms are mapped to int. Uniforms for properties that are not set on a window, are set to 0 for integers, and NaN for floats. -Root window properties are available with the prefix "root_", e.g. -"int root__NET_ACTIVE_WINDOW" corresponds to the _NET_ACTIVE_WINDOW +Root window properties are available with the prefix `root_`, e.g. +`int root__NET_ACTIVE_WINDOW` corresponds to the `_NET_ACTIVE_WINDOW` property on the root window. ### Shader atom mapping Atom values are also available as integer uniforms, so that properties -of type atom can be compared to them, their names prefixed by "atom_", -e.g. "int atom__NET_WM_STATE_MODAL" for the atom _NET_WM_STATE_MODAL. +of type atom can be compared to them, their names prefixed by `atom_`, +e.g. `int atom__NET_WM_STATE_MODAL` for the atom `_NET_WM_STATE_MODAL`. ### Complex property types For some more complex types, the mapping is less straight forward, and @@ -51,35 +51,42 @@ All texture uniforms come with a corresponding int uniform with the suffix enabled that is set to 1 when the property is set on the window, and 0 otherwize. -#### WM_HINTS icons +#### `WM_HINTS` icons -WM_HINTS icons are mapped as two textures - one for the alpha channel, +`WM_HINTS` icons are mapped as two textures - one for the alpha channel, one for the color: +``` uniform sampler2D WM_HINTS_icon; uniform sampler2D WM_HINTS_icon_mask; uniform int WM_HINTS_icon_enabled; uniform int WM_HINTS_icon_mask_enabled; +``` -#### _NET_WM_ICON icons +#### `_NET_WM_ICON` icons -_NET_WM_ICON icons are mapped to textures +`_NET_WM_ICON` icons are mapped to textures +``` uniform sampler2D _NET_WM_ICON; uniform int _NET_WM_ICON_enabled; +``` -#### IG_SVG +#### `IG_SVG` -To be able to render the SVG at full resolution at any zoom level an +To be able to render an SVG at full resolution at any zoom level an SVG can not just be a texture - it would be too big when you zoom in enough. Instead, it comes as a texture and transformation vector to offset and scale the texture: +``` uniform sampler2D IG_CONTENT; uniform vec4 IG_CONTENT_transform; +``` To render the texture correctly, you should do something like this +``` mat4 transform_mat = transpose(mat4( 1./IG_CONTENT_transform[2], 0., 0., -IG_CONTENT_transform[0]/IG_CONTENT_transform[2], 0., 1./IG_CONTENT_transform[3], 0., -IG_CONTENT_transform[1]/IG_CONTENT_transform[3], @@ -88,40 +95,51 @@ To render the texture correctly, you should do something like this )); vec4 texture_coord = transform_mat * vec4(window_coord, 0, 1.); fragColor = texture(IG_CONTENT, texture_coord.xy).rgba; +``` +#### `IG_ITEM` + +Properties of type `IG_ITEM` should contain a single window reference +(as if of type `WINDOW`). Whenever a property of this type is +encountered while rendering a window (this includes properties +inherited from the root window), this references window is rendered +(recursing). During this recursive rendering, the properties of the +parent window are available to the shader with a `parent_` prefix, +e.g. `parent_IG_COORDS`. The intention is to allow for rendering +window decorations like buttons. ## Window properties -* IG_SHADER atom - the shader to use to render this window. -* IG_COORDS float[4] - Coordinates for the window on the desktop. A +* `IG_SHADER ATOM` - the shader to use to render this window. +* `IG_COORDS FLOAT[4]` - Coordinates for the window on the desktop. A client can change these to move and resize a window. -* IG_SIZE int[2] - horizontal and vertical resolution of the window in +* `IG_SIZE INTEGER[2]` - horizontal and vertical resolution of the window in pixels. A client can change these to change the window resolution without automatically resizing the window. A ConfigureRequest however, changes both resolution and size (proportionally). -* IG_LAYER atom - the desktop layer to place this window in -* DISPLAYSVG string - svg xml source code for an image to render +* `IG_LAYER ATOM` - the desktop layer to place this window in +* `IG_CONTENT IG_SVG` - svg xml source code for an image to render instead of the window. Note: This rendering will support infinite zoom. ## ROOT properties -* IG_SHADERS atom[any] - a list of shader programs. Each program needs - yo be further specified with the next three properties - * shader_GEOMETRY string - geometry shader source code - * shader_VERTEX string vertex shader source code - * shader_FRAGMENT string fragment shader source code -* IG_VIEWS atom[any] - a list of layers to display. Each layer needs +* `IG_SHADERS ATOM[any]` - a list of shader programs. Each program needs + to be further specified with the next three properties + * `shader_GEOMETRY STRING` - geometry shader source code + * `shader_VERTEX STRING` - vertex shader source code + * `shader_FRAGMENT STRING` fragment shader source code +* `IG_VIEWS ATOM[any]` - a list of layers to display. Each layer needs to be further specified with the next two properties - * layer_LAYER atom - layer name to match on IG_LAYER on windows - * layer_VIEW float[4] - left,bottom,width,height of layer viewport + * `layer_LAYER ATOM` - layer name to match on IG_LAYER on windows + * `layer_VIEW FLOAT[4]` - left,bottom,width,height of layer viewport (zoom and pan) -* IG_ANIMATE window - event destination for animation events +* `IG_ANIMATE WINDOW` - event destination for animation events -The user should make sure to provide a shader called IG_SHADER_DEFAULT. +The user should make sure to provide a shader called `IG_SHADER_DEFAULT`. -The user should make sure to provide a view called IG_VIEW_MENU -matching the window LAYER IG_LAYER_MENU, with a viewport of 0,0,1,0.75 +The user should make sure to provide a view called `IG_VIEW_MENU` +matching the window LAYER `IG_LAYER_MENU`, with a viewport of 0,0,1,0.75 (or whatever aspect ration your screen is). This layer will be used to display override redirect windows, such as popup-menus. @@ -130,6 +148,7 @@ corresponding to the other one (typically set to 1.0) and the current screen asp Example root properties: +``` IG_VIEWS=[IG_VIEW_DESKTOP, IG_VIEW_OVERLAY, IG_VIEW_MENU] IG_VIEW_MENU_VIEW=[0.0, 0.0, 1.0, 0.75] @@ -139,25 +158,27 @@ Example root properties: IG_VIEW_MENU_LAYER=IG_LAYER_MENU IG_VIEW_OVERLAY_LAYER=IG_LAYER_OVERLAY IG_VIEW_DESKTOP_LAYER=IG_LAYER_DESKTOP +``` # Animator Implemented by: [`glass-animator`](../glass-animator) -Animations are implemented by glass-animator and controlled by setting -window properties and sending ClientMessages. +Animations are implemented by `glass-animator` and controlled by setting +window properties and sending `ClientMessage`s. -To animate the value of the property 'prop' from its current value to -a new value, the property prop_ANIMATE should be set to the new value +To animate the value of the property `prop` from its current value to +a new value, the property `prop_ANIMATE` should be set to the new value on the same window. The animation is then started by sending a -ClientMessage with the following properties: +`ClientMessage` with the following properties: + + * `window` - The window pointed to by the `IG_ANIMATE` property of + the root window + * `type` - `IG_ANIMATE` + `data[0] WINDOW` - window with the property to animate + `data[1] ATOM` - the property to animate, `prop` + `data[2] FLOAT` - animation time in seconds - window = The window pointed to by the IG_ANIMATE property of the - root window - type = "IG_ANIMATE" - data[0] window = window with the property to animate - data[1] atom = the property to animate, 'prop' - data[2] float = animation time in seconds # Coordinate systems @@ -171,17 +192,20 @@ Window coordinates are for the top left corner of windows. Width and height are in the same units as x and y. Therefore, the coordinates occupied by a window ranges from ]x..x+w[,]y-h..y[. -# About the FLOAT datatype +# About the `FLOAT` datatype -The FLOAT datatype is encoded as a 32 bit float stored in a 32 bit +The `FLOAT` datatype is encoded as a 32 bit float stored in a 32 bit item in properties and events according to the normal 32 bit item -rules of XGetWindowProperty etc - that is, it is stored on the X +rules of `XGetWindowProperty` etc - that is, it is stored on the X server in network byte order, and converted to/from local byte order -by Xlib. Note: On 64 bit platforms, XGetWindowProperty returns an -array of long, which are 64, not 32 bits each. That means that the -whole array CAN NOT be casted to an array of float, but each array -item must be reinterpreted separately: +by `Xlib`. + +WARNING: On 64 bit platforms, `XGetWindowProperty` returns an array of +long, which are 64, not 32 bits each. That means that the whole array +CAN NOT be casted to an array of float, but each array item must be +reinterpreted separately: +``` float items[nr_items]; XGetWindowProperty( display, window, property_name_atom, 0, @@ -192,6 +216,7 @@ item must be reinterpreted separately: for (int i = 0; i < nr_items; i++) { items[i] = *(float *) (i + (long *) prop_return); } +``` # Application ID:s @@ -209,5 +234,5 @@ and used in its stead. When ever the application opens a new window, all environment variables read at startup as per above, will be set as properties on -the window. Additionally, the property WM_COMMAND will be set to the +the window. Additionally, the property `WM_COMMAND` will be set to the argv of the application. \ No newline at end of file