main b0c82ee

GTK4 widget bridge for CEF with OSR.

purego-cef2gtk

GTK4 widget bridge for purego-cef accelerated off-screen rendering.

Status

Early bootstrap. The renderer is Wayland-only and GPU-first:

  • CEF accelerated OSR with shared textures/DMABUFs
  • GTK4 GdkDmabufTextureBuilder + GtkPicture/GtkGraphicsOffload backend for GTK/GSK rendering
  • GTK4 GtkGLArea EGL/OpenGL import-and-copy backend as fallback/debug path
  • no X11 target
  • no --disable-gpu or software rendering fallback
  • CEF OnPaint is treated as a diagnostic/error path, not as a renderer

Renderer stacks

NewView() defaults to the Vulkan GPU stack and fails during view setup if the selected stack cannot be constructed. Use ResolveRenderStack to choose a coherent stack explicitly:

plan, err := cef2gtk.ResolveRenderStack(cef2gtk.RenderStackVulkan) // or RenderStackEGL
if err != nil {
    return err
}
cef2gtk.ConfigureRenderStackEnvironment(plan) // call before GTK initialization
cef2gtk.ConfigureCommandLine(commandLine, cef2gtk.CommandLineOptions{RenderStackPlan: plan})
view := cef2gtk.NewViewWithOptions(cef2gtk.ViewOptions{RenderStackPlan: plan})

Supported stacks:

  • vulkan: GDK DMABUF presentation with ANGLE Vulkan and GSK Vulkan.
  • egl: GtkGLArea presentation with ANGLE GL/EGL and GSK OpenGL.

Environment overrides remain available as diagnostics/backcompat escape hatches:

PUREGO_CEF2GTK_BACKEND=gdk-dmabuf|glarea
PUREGO_CEF2GTK_ANGLE_BACKEND=vulkan|gl-egl|none
PUREGO_CEF2GTK_OSR_BACKING_SCALE=auto|on|off

PUREGO_CEF2GTK_OSR_BACKING_SCALE=auto enables the Linux accelerated-OSR HiDPI compatibility path only when the GTK surface scale is greater than 1. In that mode CEF receives a device-sized OSR view rect with a 1x screen scale, because current CEF shared-texture OSR builds can otherwise report a fractional device_scale_factor while still emitting 1x/logical DMABUF frames.

Applications that expose page zoom must scale their user-facing zoom by (*View).PageZoomCompensation() (one CSS pixel per logical pixel) before converting it to CEF's logarithmic zoom level, and divide CEF zoom readback by the same factor. The method returns 1 when CEF's normal logical OSR contract is in effect. User zoom itself stays a user-facing value: the compensation changes with the observed output scale and must not be persisted. Recompute it and reapply the page zoom from an AddSizeObserver callback, which also runs when the effective scale changes without a logical-size change.

Recommended local checks:

GSK_RENDERER=vulkan PUREGO_CEF2GTK_BACKEND=gdk-dmabuf go run ./examples/simple-browser
GSK_RENDERER=opengl PUREGO_CEF2GTK_BACKEND=glarea PUREGO_CEF2GTK_ANGLE_BACKEND=gl-egl go run ./examples/simple-browser

Usage sketch

plan, err := cef2gtk.ResolveRenderStack(cef2gtk.RenderStackVulkan)
if err != nil {
    return err
}

cef2gtk.ConfigureRenderStackEnvironment(plan) // before GTK initialization

// In cef.App.OnBeforeCommandLineProcessing:
cef2gtk.ConfigureCommandLine(commandLine, cef2gtk.CommandLineOptions{RenderStackPlan: plan})

view := cef2gtk.NewViewWithOptions(cef2gtk.ViewOptions{RenderStackPlan: plan})
window.SetChild(view.Widget())
window.Present()
view.Widget().Realize()
if err := view.PrepareOnGTKThread(); err != nil {
    return err
}

info := cef.NewWindowInfo()
// After the GTK widget/surface is realized, extract its native platform handle
// with the appropriate GTK/platform API and pass that handle as Parent.
cef2gtk.ConfigureWindowInfo(&info, cef2gtk.WindowInfoOptions{Parent: /* realized native handle */})
settings := cef.NewBrowserSettings()
cef2gtk.ConfigureBrowserSettings(&settings, cef2gtk.BrowserSettingsOptions{WindowlessFrameRate: 144})
client := cef.NewClient(myClient{render: view.RenderHandler(cef2gtk.Hooks{})})
cef.BrowserHostCreateBrowser(&info, client, "https://example.com/", &settings, nil, nil)

// In OnAfterCreated(browser cef.Browser), attach the BrowserHost:
_ = view.AttachInput(browser.GetHost(), cef2gtk.InputOptions{Scale: 0})

Inertial scrolling

Touchpad inertia and wheel smoothing are opt-in per InputOptions.Scroll:

_ = view.AttachInput(host, cef2gtk.InputOptions{
    Scroll: cef2gtk.ScrollOptions{TouchpadInertia: true, WheelSmoothing: true},
})

Zero values keep direct scroll behavior. Touchpad motion tracks input directly; a valid release decays exponentially and stops on retouch, modifiers, press, focus loss, hide, host replacement, or detach. Wheel bursts interpolate accepted impulses across frames; Ctrl/Alt/Meta-modified input always bypasses animation with direct physical delivery. Synthetic output never passes through OnScroll or navigation recognition.

Cancellation splits immediate invalidation from GTK cleanup: InvalidateScroll retires motion from any thread and returns the retired epoch; CancelScrollEpoch cleans up that epoch on the GTK thread without touching newer sessions. CancelScroll does both inline on the GTK thread. Already-submitted CEF events cannot be retracted.

All engine timestamps share one monotonic clock so event intervals stay live whether or not GTK frames render between input events.

For diagnosis, PUREGO_CEF2GTK_SCROLL_TRACE=1 enables a bounded (2000-line) stderr trace of input events (both monotonic and GDK timestamps, units, deltas, coordinates, modifiers), tick lifecycle, engine decisions with discarded quantities, and per-burst submission totals. It never logs page content or URLs.

See examples/simple-browser for a complete accelerated-only GTK+CEF setup.

Development

The module depends on the published github.com/bnema/puregotk module fork.

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 1

Tags 35

↑↓ moveenter openesc close