Recommended picom configuration

This page aims to document a few recommended picom rules and configuration options that may be useful.

Shadows

If you enable shadows then here are here are a few recommended rules.

shadow-exclude = [
  "! name~=''",
  "class_g = 'dusk'",
  "class_g = 'systray'",
  "_NET_WM_OPAQUE_REGION@:c",
  "_NET_WM_STATE@:32a *= '_NET_WM_STATE_HIDDEN'",
  "_IS_FLOATING@:32c = 0",
  "_NET_WM_BYPASS_COMPOSITOR@:c",
];

Reasoning:

"! name~=''",

This is to skip shadows for windows that do not have a window title. This might be widgets or some other kind of special window.

"class_g = 'dusk'",

This prevents the compositor from drawing shadows on the bar(s) in dusk. This comes down to personal preference and is highlighted here for documentation purposes. Given that the bars do not have a window title they will be explicitly excluded due to the name filter above.

"class_g = 'systray'",

This is to prevent the compositor from drawing shadows for the systray window in dusk.

"_NET_WM_OPAQUE_REGION@:c",

Some windows use the _NET_WM_OPAQUE_REGION property to indicate that they have opaque regions, which typically means that they also have transparent regions. In such cases the window may be drawing its own shadows or it may have a unique form. In any case it is better not to let the compositor draw shadows for such windows as it will typically not look good.

"_NET_WM_STATE@:32a *= '_NET_WM_STATE_HIDDEN'",

This is in the context of windows that are hidden / minimized. No need to expend resources drawing shadows for these.

"_IS_FLOATING@:32c = 0",

This prevents picom from drawing shadows for windows that are tiled. This means that shadows are drawn for floating windows only. This comes down to personal preference of course.

"_NET_WM_BYPASS_COMPOSITOR@:c",

Some windows use the _NET_WM_BYPASS_COMPOSITOR property to indicate that they do not want the compositor to interfere. In principle having this in the exclude list should be redundant as the compositor should be taking this property into account anyway, but there is no harm in explicitly including this in the rules.

Rounded corners

If you apply rounded corners then here are here are a few recommended rules.

rounded-corners-exclude = [
  "window_type = 'dock'",
  "window_type = 'desktop'",
  "class_g = 'dusk'",
  "class_g = 'systray'",
  "_NET_WM_BYPASS_COMPOSITOR@:c",
];

Reasoning:

"window_type = 'dock'",

This prevents the compositor from applying rounded corners on dock applications (having the _NET_WM_WINDOW_TYPE_DOCK property). This generally refers to applications that "dock" onto the edge of the screen or to other windows.

"window_type = 'desktop'",

This prevents the compositor from applying rounded corners on desktop applications (having the _NET_WM_WINDOW_TYPE_DESKTOP) property. This generally refers to programs that run on the desktop. An example of this would be programs offering desktop icons; as in being able to add folders and icons on the desktop itself.

The picom configuration documents that windows with the desktop property will never be drawn with shadows. It is likely that this also applies to rounded corners and that this rule is redundant.

"class_g = 'dusk'",

This is to prevent the compositor from applying rounded corners to the bar(s) in dusk. This comes down to personal preference and is highlighted here for documentation purposes.

"class_g = 'systray'",

This is to prevent the compositor from applying rounded corners to the systray window in dusk.

"_NET_WM_BYPASS_COMPOSITOR@:c",

Same as for the shadows. Redundant but explicitly defined for awareness.

Blur

blur-background-exclude = [
  "window_type = 'desktop'",
  "_GTK_FRAME_EXTENTS@:c",
  "class_g = 'dusk'",
  "class_g = 'systray'",
  "class_g = 'deepin-screen-recorder'",
  "_NET_WM_OPAQUE_REGION@:c",
  "_NET_WM_BYPASS_COMPOSITOR@:c",
];

Reasoning:

"window_type = 'desktop'",

This prevents the compositor from applying blur on programs that run on the desktop (e.g. like desktop icons).

"_GTK_FRAME_EXTENTS@:c",

This is in the context of GTK applications that draws their own shadows (something that extends beyond the frame of the window).

"class_g = 'dusk'",

This prevents the compositor from blurring transparent bar(s) in dusk. This comes down to personal preference and is highlighted here for documentation purposes.

"class_g = 'systray'",

This prevents the compositor from blurring the background of the transparent systray window in dusk.

"class_g = 'deepin-screen-recorder'",

This is program specific, but included here as the Deepin Screen Recorder was found to be practically unusable if e.g. dual kawase blur was applied to the the overlay for the selection tool.

"_NET_WM_OPAQUE_REGION@:c",

If a window indicates that it has opaque regions (and thus by inference has fully transparent regions) then it will typically have a bespoke shape or draw its own shadows. Applying blur in such cases will not look good hence the exclusion.

"_NET_WM_BYPASS_COMPOSITOR@:c",

Same as for the shadows. Redundant but explicitly defined for awareness.

Fullscreen applications

# Unredirect all windows if a full-screen opaque window is detected,
# to maximize performance for full-screen windows. Known to cause flickering
# when redirecting/unredirecting windows.
#
unredir-if-possible = true;

For fullscreen applications (e.g. videos or games) it is recommended to enable the unredir-if-possible option. This allows for the compositor to not interfere with the fullscreen program (as otherwise this can affect performance).

---

Back to Guides.