screen

package
v0.4.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package screen provides screen capture backends for X11 and Wayland.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Probe 

func Probe() []probe.Result

Probe returns availability details for every screen backend in priority order.

func ProbeRuntime added in v0.1.8 

func ProbeRuntime(rt env.Runtime) []probe.Result

ProbeRuntime returns availability details for rt in backend priority order.

func Resolution 

func Resolution(sc Screenshotter) (int, int, error)

Resolution is a convenience wrapper that uses context.Background().

func ResolutionWithContext added in v0.1.6 

func ResolutionWithContext(ctx context.Context, sc Screenshotter) (int, int, error)

ResolutionWithContext returns the screen resolution of sc using the provided context. If sc implements Resolver directly, that is used. Otherwise, a full-output grab (zero rect) is tried with ctx.

func SetWlrCacheTTL added in v0.1.6 

func SetWlrCacheTTL(d time.Duration)

Types

type ExtCaptureBackend 

type ExtCaptureBackend struct {
	// contains filtered or unexported fields
}

ExtCaptureBackend captures the screen using ext_image_copy_capture_manager_v1. This protocol is detected by probing compositor globals at runtime; it is available where the compositor advertises ext_image_copy_capture_manager_v1. Do not assume specific compositor versions — rely solely on protocol presence.

func NewExtCaptureBackend 

func NewExtCaptureBackend() (*ExtCaptureBackend, error)

NewExtCaptureBackend returns an ExtCaptureBackend if the compositor advertises the full ext-image-copy stack needed for output capture, otherwise an error.

func NewExtCaptureBackendForSocket added in v0.1.8 

func NewExtCaptureBackendForSocket(sock string) (*ExtCaptureBackend, error)

NewExtCaptureBackendForSocket returns an ExtCaptureBackend for sock if the compositor advertises the full ext-image-copy stack needed for capture.

func (*ExtCaptureBackend) Close 

func (b *ExtCaptureBackend) Close() error

func (*ExtCaptureBackend) Grab 

func (b *ExtCaptureBackend) Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)

Grab captures the full output then returns the cropped rect.

func (*ExtCaptureBackend) GrabFullHash added in v0.1.7 

func (b *ExtCaptureBackend) GrabFullHash(ctx context.Context) (uint32, error)

GrabFullHash returns a CRC32 checksum of the entire screen. Bypasses intermediate image allocation by hashing the raw buffer directly.

func (*ExtCaptureBackend) GrabRegionHash added in v0.2.0 

func (b *ExtCaptureBackend) GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)

GrabRegionHash computes a CRC32 fingerprint for rect using the raw shared-memory buffer so no intermediate image allocation is needed.

type GnomeShellScreenshotBackend 

type GnomeShellScreenshotBackend struct {
	// contains filtered or unexported fields
}

GnomeShellScreenshotBackend captures the screen through GNOME Shell's native org.gnome.Shell.Screenshot D-Bus service. GNOME Shell restricts this service to trusted callers unless the shell is running in unsafe mode.

func NewGnomeShellScreenshotBackend 

func NewGnomeShellScreenshotBackend() (*GnomeShellScreenshotBackend, error)

NewGnomeShellScreenshotBackend returns a backend when GNOME Shell's screenshot service is reachable and the current process is allowed to call it. A 1x1 probe screenshot is performed at construction time so callers can fall back to the portal when unsafe mode is disabled.

func NewGnomeShellScreenshotBackendForBus added in v0.1.8 

func NewGnomeShellScreenshotBackendForBus(addr string) (*GnomeShellScreenshotBackend, error)

NewGnomeShellScreenshotBackendForBus returns a backend for the session bus at addr when GNOME Shell's screenshot service is reachable and authorized.

func (*GnomeShellScreenshotBackend) Close 

func (b *GnomeShellScreenshotBackend) Close() error

func (*GnomeShellScreenshotBackend) Grab 

func (b *GnomeShellScreenshotBackend) Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)

Grab captures rect using GNOME Shell's native screenshot service. A zero rect requests a full-screen capture; a non-empty rect uses ScreenshotArea.

func (*GnomeShellScreenshotBackend) GrabFullHash added in v0.1.7 

func (b *GnomeShellScreenshotBackend) GrabFullHash(ctx context.Context) (uint32, error)

GrabFullHash returns a fast pixel hash of the entire screen.

func (*GnomeShellScreenshotBackend) GrabRegionHash added in v0.2.0 

func (b *GnomeShellScreenshotBackend) GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)

func (*GnomeShellScreenshotBackend) Resolution 

func (b *GnomeShellScreenshotBackend) Resolution() (int, int, error)

type KWinShotBackend 

type KWinShotBackend struct {
	// contains filtered or unexported fields
}

KWinShotBackend captures the screen via org.kde.KWin.ScreenShot2.

func NewKWinShotBackend 

func NewKWinShotBackend() (*KWinShotBackend, error)

NewKWinShotBackend returns a KWinShotBackend if org.kde.KWin is reachable on the session bus and the process is authorized to capture the screen. A 1×1 probe grab is performed at construction time to verify authorization; if KDE has not granted capture permission, the constructor returns an error so the caller can fall back to another backend (e.g. the portal).

func NewKWinShotBackendForBus added in v0.1.8 

func NewKWinShotBackendForBus(addr string) (*KWinShotBackend, error)

NewKWinShotBackendForBus opens a KWin screenshot backend on the session bus at addr and verifies that the caller is authorized to capture the screen.

func (*KWinShotBackend) Close 

func (b *KWinShotBackend) Close() error

Close closes the D-Bus connection held by the backend.

func (*KWinShotBackend) Grab 

func (b *KWinShotBackend) Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)

Grab captures rect using CaptureArea. An empty rect requests the active screen capture path. KWin writes pixel data to a Unix pipe; the D-Bus reply carries format metadata in an a{sv}. We close our write-end copy after the synchronous call returns (KWin has already written + closed its dup'd copy by then), then drain the read end.

func (*KWinShotBackend) GrabFullHash added in v0.1.7 

func (b *KWinShotBackend) GrabFullHash(ctx context.Context) (uint32, error)

GrabFullHash returns a fast pixel hash of the active screen.

func (*KWinShotBackend) GrabRegionHash added in v0.2.0 

func (b *KWinShotBackend) GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)

GrabRegionHash computes a CRC32 pixel fingerprint for rect. For KWin this falls back to Grab + PixelHash so the hash stays consistent with GrabFullHash.

func (*KWinShotBackend) Resolution added in v0.4.0 

func (b *KWinShotBackend) Resolution() (int, int, error)

Resolution returns the active screen dimensions.

type PortalDBusBackend 

type PortalDBusBackend struct {
	// contains filtered or unexported fields
}

PortalDBusBackend captures the screen via the xdg-desktop-portal Screenshot interface (org.freedesktop.portal.Screenshot). Each Grab call takes a full workspace screenshot and returns the cropped region. No PipeWire required.

The compositor may show a one-time consent dialog on first use; once granted the permission is remembered. Sandboxed (Flatpak) environments may require additional portal permissions.

func NewPortalDBusBackend 

func NewPortalDBusBackend() (*PortalDBusBackend, error)

NewPortalDBusBackend verifies that the xdg-desktop-portal Screenshot interface is reachable on the session bus.

func NewPortalDBusBackendForBus added in v0.1.8 

func NewPortalDBusBackendForBus(addr string) (*PortalDBusBackend, error)

NewPortalDBusBackendForBus verifies that the xdg-desktop-portal Screenshot interface is reachable on the session bus at addr.

func (*PortalDBusBackend) Close 

func (b *PortalDBusBackend) Close() error

func (*PortalDBusBackend) Grab 

func (b *PortalDBusBackend) Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)

Grab takes a full workspace screenshot via the portal and returns the requested rectangle. The portal may show a consent dialog on first use.

func (*PortalDBusBackend) GrabFullHash added in v0.1.7 

func (b *PortalDBusBackend) GrabFullHash(ctx context.Context) (uint32, error)

GrabFullHash returns a fast pixel hash of the entire screen.

func (*PortalDBusBackend) GrabRegionHash added in v0.2.0 

func (b *PortalDBusBackend) GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)

type Resolver 

type Resolver interface {
	Resolution() (width, height int, err error)
}

Resolver reports the output resolution. Backends that track output geometry (e.g. via wl_output mode events) implement this directly. For backends that don't, Resolution() falls back to a full-screen grab.

type Screenshotter 

type Screenshotter interface {
	Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)
	// GrabFullHash returns a fast pixel hash of the entire screen.
	// Backends should optimize this to avoid intermediate image allocations.
	GrabFullHash(ctx context.Context) (uint32, error)
	// GrabRegionHash returns a fast pixel hash for the specified rectangle.
	// Implementations should avoid allocating an image or doing BGRA->RGBA
	// decoding when possible (use raw buffer hashing).
	GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)
	Close() error
}

Screenshotter captures a rectangular region of the screen.

func Open 

func Open() (Screenshotter, error)

Open returns the best available Screenshotter for the current environment.

func OpenRuntime added in v0.1.8 

func OpenRuntime(rt env.Runtime) (Screenshotter, error)

OpenRuntime returns the best available Screenshotter for rt.

type WlrScreencopyBackend 

type WlrScreencopyBackend struct {
	// contains filtered or unexported fields
}

func NewWlrScreencopyBackend 

func NewWlrScreencopyBackend() (*WlrScreencopyBackend, error)

func NewWlrScreencopyBackendForSocket added in v0.1.8 

func NewWlrScreencopyBackendForSocket(sock string) (*WlrScreencopyBackend, error)

func NewWlrScreencopyBackendWithConnector added in v0.1.6 

func NewWlrScreencopyBackendWithConnector(sock string, connect func(string) (*wl.Context, error), ttl time.Duration) *WlrScreencopyBackend

NewWlrScreencopyBackendWithConnector constructs a backend with an injectable connector and TTL (used by tests). Use NewWlrScreencopyBackend for normal use.

func (*WlrScreencopyBackend) Close 

func (b *WlrScreencopyBackend) Close() error

func (*WlrScreencopyBackend) Grab 

func (b *WlrScreencopyBackend) Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)

func (*WlrScreencopyBackend) GrabFullHash added in v0.1.7 

func (b *WlrScreencopyBackend) GrabFullHash(ctx context.Context) (uint32, error)

func (*WlrScreencopyBackend) GrabRegionHash added in v0.2.0 

func (b *WlrScreencopyBackend) GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)

func (*WlrScreencopyBackend) Resolution 

func (b *WlrScreencopyBackend) Resolution() (int, int, error)

type X11Backend 

type X11Backend struct {
	// contains filtered or unexported fields
}

On composited sessions (KDE/GNOME Wayland via XWayland) the root window is not directly readable with XGetImage. This backend automatically uses the Composite extension (NameWindowPixmap) when available, falling back to a direct root-window GetImage for plain X11 sessions.

On Wayland, only X11/XWayland window content is visible through this path; native Wayland surfaces require Wayland capture protocols or portals.

func NewX11Backend 

func NewX11Backend(displayName string) (*X11Backend, error)

NewX11Backend opens a connection to the X11 display specified by displayName (e.g. ":0"). Pass an empty string to use the DISPLAY environment variable.

func (*X11Backend) Close 

func (b *X11Backend) Close() error

Close closes the X11 connection.

func (*X11Backend) Grab 

func (b *X11Backend) Grab(ctx context.Context, rect image.Rectangle) (image.Image, error)

Grab captures the pixels inside rect. On composited displays it snapshots the root via NameWindowPixmap so that the actual composited framebuffer is captured rather than the bare root pixmap.

func (*X11Backend) GrabFullHash added in v0.1.7 

func (b *X11Backend) GrabFullHash(ctx context.Context) (uint32, error)

GrabFullHash returns a CRC32 checksum of the entire screen.

func (*X11Backend) GrabRegionHash added in v0.2.0 

func (b *X11Backend) GrabRegionHash(ctx context.Context, rect image.Rectangle) (uint32, error)

GrabRegionHash returns a fast CRC32 hash for the specified rect. It uses XGetImage on the requested rectangle to avoid an intermediate image decode.

func (*X11Backend) Resolution added in v0.2.2 

func (b *X11Backend) Resolution() (int, int, error)

Resolution returns the screen dimensions from the X11 screen info.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.