cef2gtk

package module
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: May 14, 2026 License: MIT Imports: 16 Imported by: 0

README

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 backends

NewView() uses BackendAuto: it tries gdk-dmabuf first and falls back to glarea if GDK DMABUF construction is unavailable. Use NewViewWithOptions or env overrides for diagnostics:

view := cef2gtk.NewViewWithOptions(cef2gtk.ViewOptions{Backend: cef2gtk.BackendGDKDMABUF})

Environment overrides:

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

Recommended local checks:

GSK_RENDERER=vulkan PUREGO_CEF2GTK_BACKEND=gdk-dmabuf go run ./examples/simple-browser
GSK_RENDERER=ngl PUREGO_CEF2GTK_BACKEND=gdk-dmabuf go run ./examples/simple-browser
PUREGO_CEF2GTK_BACKEND=glarea go run ./examples/simple-browser

Usage sketch

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

view := cef2gtk.NewView()
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()
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: 1})

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

Development

The module depends on the published github.com/bnema/puregotk module. During local puregotk development, you can temporarily add your own replace github.com/bnema/puregotk => ../puregotk directive.

rtk make check

Documentation

Overview

Package cef2gtk provides a GTK4 widget bridge for purego-cef accelerated off-screen rendering.

The project is Wayland-only and GPU-first. It is intended to use CEF accelerated OSR shared textures/DMABUFs; software OnPaint rendering is a diagnostic/error path, not a product renderer.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInputNotAttached = errors.New("input bridge is not attached")
View Source 
var ErrNilView = errors.New("nil View")
View Source 
var ErrViewNotInitialized = errors.New("view not initialized")

Functions

func ConfigureCommandLine 

func ConfigureCommandLine(commandLine cef.CommandLine, _ CommandLineOptions)

ConfigureCommandLine configures the CEF command line for Wayland accelerated rendering. It is intended to be called from App.OnBeforeCommandLineProcessing.

func ConfigureWindowInfo 

func ConfigureWindowInfo(info *cef.WindowInfo, opts WindowInfoOptions)

ConfigureWindowInfo configures CEF window info for accelerated windowless rendering with shared textures.

Types

type Backend 

type Backend string

Backend selects the GTK presentation backend used by a View. 

const (
	// BackendAuto tries the GDK DMABUF backend first and falls back to GLArea
	// when GDK DMABUF construction is unavailable.
	BackendAuto Backend = "auto"
	// BackendGDKDMABUF presents CEF DMABUF frames as GDK textures.
	BackendGDKDMABUF Backend = "gdk-dmabuf"
	// BackendGLArea presents CEF DMABUF frames through GtkGLArea/EGL/OpenGL.
	BackendGLArea Backend = "glarea"
)

func (Backend) String 

func (b Backend) String() string

String returns the environment/API spelling for b.

type CommandLineOptions 

type CommandLineOptions struct{}

CommandLineOptions configures CEF command-line setup for the GTK bridge.

type DiagnosticEvent 

type DiagnosticEvent struct {
	Time    time.Time
	Kind    string
	Message string
}

DiagnosticEvent records notable rendering-path events and failures.

type Diagnostics 

type Diagnostics struct {
	Backend                 string
	AcceleratedPaints       int
	AcceleratedPaintErrors  int
	UnsupportedPaints       int
	ImportFailures          int
	RenderFailures          int
	TexturesBuilt           int
	TextureBuildFailures    int
	FDDupFailures           int
	UnsupportedFormats      int
	PaintableSwaps          int
	PendingFrame            bool
	PendingScheduled        bool
	PendingAge              time.Duration
	PendingSourceID         uint
	PendingReschedules      int
	PendingScheduleFailures int
	PendingIdleCallbacks    int
	Events                  []DiagnosticEvent
}

Diagnostics is a snapshot of View rendering diagnostics. Events contains the most recent diagnostic events, capped to avoid unbounded growth.

type DurationStats 

type DurationStats = internalprofile.DurationStats

DurationStats aggregates duration samples for one profiling window.

type GCStats 

type GCStats = internalprofile.GCStats

GCStats summarizes Go runtime GC state for one profiling window.

type Hooks 

type Hooks struct {
	OnUnsupportedPaint     func()
	OnError                func(error)
	OnTextSelectionChanged func(selectedText string, selectedRange *cef.Range)
}

Hooks contains optional callbacks invoked by the public CEF render adapter.

type InputOptions 

type InputOptions struct {
	// Scale is the HiDPI scale factor applied to pointer coordinates. Values <= 0 use 1.
	Scale int32
	// OnMiddleClick is invoked when GTK receives a middle-button press. Returning
	// true consumes the event before it is forwarded to CEF.
	OnMiddleClick func(x, y float64) bool
	// SelectionText returns the current browser selection for explicit clipboard
	// shortcuts. When set with OnClipboardShortcut, Ctrl+C/Ctrl+X can be mirrored
	// to application-level clipboard orchestration before forwarding to CEF.
	SelectionText func() string
	// OnClipboardShortcut is invoked for explicit Ctrl+C/Ctrl+X shortcuts when
	// SelectionText returns non-empty text. action is "copy" or "cut".
	OnClipboardShortcut func(action, text string)
}

InputOptions configures GTK-to-CEF input forwarding.

type Options 

type Options struct {
	// RenderingMode must be RenderingModeAcceleratedDMABUF. It defaults to that
	// mode when left empty.
	RenderingMode RenderingMode
}

Options configures a View.

func (Options) Validate 

func (o Options) Validate() error

Validate verifies that the options request the supported accelerated path.

type ProfileOptions 

type ProfileOptions struct {
	Enabled    bool
	Interval   time.Duration
	OnSnapshot func(ProfileSnapshot)
	Writer     io.Writer
}

ProfileOptions configures development-only render profiling for a View.

type ProfileSnapshot 

type ProfileSnapshot = internalprofile.Snapshot

ProfileSnapshot contains one profiling window of render-pipeline metrics.

type RenderingMode 

type RenderingMode string

RenderingMode selects the rendering pipeline used by the GTK bridge. 

const (
	// RenderingModeAcceleratedDMABUF uses CEF accelerated OSR shared textures
	// imported through Wayland DMABUF/EGL and rendered by GtkGLArea.
	RenderingModeAcceleratedDMABUF RenderingMode = "accelerated-dmabuf"
)

type View 

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

View is a GTK-backed CEF OSR view.

func NewView 

func NewView() *View

NewView creates an accelerated CEF view using BackendAuto or the PUREGO_CEF2GTK_BACKEND override when it is set.

func NewViewWithOptions 

func NewViewWithOptions(opts ViewOptions) *View

NewViewWithOptions creates an accelerated CEF view with explicit options. When PUREGO_CEF2GTK_BACKEND is set, it intentionally overrides opts.Backend for diagnostics and deployment-level backend selection.

func (*View) AddSizeObserver 

func (v *View) AddSizeObserver(fn func(width, height int32)) func()

AddSizeObserver registers a callback invoked on the GTK thread when the view observes a positive size change. It returns a function that unregisters the observer. If a real positive size has already been observed, the callback is invoked immediately with that size; the synthetic Size() fallback is not emitted as an observer event. Register and unregister from the GTK thread.

func (*View) AttachInput 

func (v *View) AttachInput(host cef.BrowserHost, opts InputOptions) error

AttachInput attaches GTK event controllers to the view and forwards input to host. Call from the GTK/main thread; GTK controller attachment is not goroutine-safe.

func (*View) Backend 

func (v *View) Backend() Backend

Backend returns the selected presentation backend.

func (*View) ConfigureProfiling 

func (v *View) ConfigureProfiling(opts ProfileOptions) error

ConfigureProfiling enables or disables development-only render profiling. When enabled, snapshots are emitted at opts.Interval through opts.OnSnapshot and/or opts.Writer. Rendering continues if snapshot writing fails.

func (*View) Destroy 

func (v *View) Destroy() error

Destroy releases GL resources owned by the view. Call on the GTK main thread; it disconnects GTK signal handlers and is not safe for concurrent use.

func (*View) DetachInput 

func (v *View) DetachInput() error

DetachInput removes input controllers attached by AttachInput.

func (*View) DeviceScaleFactor 

func (v *View) DeviceScaleFactor() float32

DeviceScaleFactor returns the last GTK scale factor observed for the view. Values <= 0 are normalized to 1.

func (*View) Diagnostics 

func (v *View) Diagnostics() Diagnostics

Diagnostics returns a point-in-time diagnostics snapshot.

func (*View) GLArea 

func (v *View) GLArea() *gtk.GLArea

GLArea returns the underlying GtkGLArea for the GLArea backend.

func (*View) HasFocus 

func (v *View) HasFocus() bool

HasFocus reports whether the underlying GTK widget currently has focus. Call on the GTK main thread.

func (*View) PrepareOnGTKThread 

func (v *View) PrepareOnGTKThread() error

PrepareOnGTKThread initializes renderer resources. Call on GTK main thread.

func (*View) RenderHandler 

func (v *View) RenderHandler(hooks Hooks) cef.RenderHandler

RenderHandler returns a CEF render handler adapter for this view.

func (*View) SetCursorFromName 

func (v *View) SetCursorFromName(name string)

SetCursorFromName applies a named cursor to the underlying GTK widget. Call on the GTK main thread.

func (*View) SetInputHost 

func (v *View) SetInputHost(host cef.BrowserHost) error

SetInputHost updates the CEF browser host used by the attached input bridge. Must be called on the GTK/main thread. Returns ErrInputNotAttached when v.input is nil. Callers must call AttachInput first.

func (*View) Size 

func (v *View) Size() (int32, int32)

Size returns the last positive widget size observed on the GTK thread. Before the widget has a real size, CEF requires a non-zero fallback, so Size returns 1x1.

func (*View) Widget 

func (v *View) Widget() *gtk.Widget

Widget returns the GtkWidget for packing into GTK containers.

type ViewOptions 

type ViewOptions struct {
	// Backend selects the renderer backend. Empty defaults to BackendAuto.
	Backend Backend
	// Profile optionally enables development render profiling during construction.
	Profile ProfileOptions
}

ViewOptions configures NewViewWithOptions.

func (ViewOptions) Validate 

func (o ViewOptions) Validate() error

Validate verifies that the requested backend is supported by the option schema.

type WindowInfoOptions 

type WindowInfoOptions struct {
	// Parent is the native parent window handle passed to CEF.
	Parent uintptr
}

WindowInfoOptions configures CEF window-info setup for the GTK bridge.

Source Files

View all Source files

Directories

Path Synopsis
cmd
probe-gtk-egl command
probe-import-copy command
examples
simple-browser command
internal
cefadapter
Package cefadapter converts purego-cef callback data into internal models.
 Package cefadapter converts purego-cef callback data into internal models.
cutil
dmabuf
Package dmabuf models borrowed Linux DMABUF frames received from CEF.
 Package dmabuf models borrowed Linux DMABUF frames received from CEF.
egl
Package egl contains small EGL helpers shared by GTK/GL probing and rendering.
 Package egl contains small EGL helpers shared by GTK/GL probing and rendering.
gl
Package gl contains purego OpenGL helpers used by the accelerated renderer.
 Package gl contains purego OpenGL helpers used by the accelerated renderer.
gtkgdk
Package gtkgdk renders CEF accelerated-paint DMABUF frames through GDK textures.
 Package gtkgdk renders CEF accelerated-paint DMABUF frames through GDK textures.
gtkgl
Package gtkgl contains GtkGLArea context probing helpers shared by probes and renderers.
 Package gtkgl contains GtkGLArea context probing helpers shared by probes and renderers.
profile

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.