egl

package
v0.30.21 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package egl provides EGL (EGL) context management for OpenGL ES on Linux.

EGL is the native interface for OpenGL ES on Linux, supporting:

  • X11 displays (via EGL_PLATFORM_X11_KHR)
  • Wayland displays (via EGL_PLATFORM_WAYLAND_KHR)
  • Surfaceless contexts (via EGL_PLATFORM_SURFACELESS_MESA)

This implementation uses github.com/go-webgpu/goffi for Pure Go FFI without requiring CGO.

FFI error handling follows ADR-049 three-tier strategy: 

Tier 1 (creation/submit): check both FFI error and API result code
Tier 2 (void/hot path): infallible by GPU API contract — Vulkan §6.6, WebGPU §21.2
Tier 3 (platform syscalls): use errno for diagnostics (Wayland, X11, Win32)

Enterprise reference: Rust wgpu-hal returns () for all draw/destroy/barrier commands.

EGL calls are Tier 2: EGL errors are reported via eglGetError(), not FFI return values. EGLBoolean returns are checked after the call, not at the FFI transport level.

Package egl provides EGL bindings for OpenGL context management.

This file adds libwayland-egl.so bindings for creating EGL window surfaces on Wayland. Unlike X11 where eglCreateWindowSurface takes the raw X11 Window handle, Wayland requires an intermediate wl_egl_window object.

Enterprise reference: Rust wgpu-hal egl.rs:1390-1533 (configure), SDL3 SDL_waylandwindow.c:2978.

Index

Constants

View Source 
const (
	DefaultDisplay  EGLNativeDisplayType = 0
	NoContext       EGLContext           = 0
	NoDisplay       EGLDisplay           = 0
	NoSurface       EGLSurface           = 0
	DontCare        EGLInt               = -1
	Unknown         EGLInt               = -1
	NoNativeDisplay EGLNativeDisplayType = 0
	NoNativeWindow  EGLNativeWindowType  = 0
)

EGL constants - Special values

Variables

This section is empty.

Functions

func GetEGLDisplay 

func GetEGLDisplay(nativeDisplay uintptr) (EGLDisplay, WindowKind, *DisplayOwner, error)

GetEGLDisplay returns an EGL display for the detected platform. nativeDisplay is the platform-specific native display handle:

  • Wayland: the app's wl_display* — must NOT be 0, otherwise EGL opens a second wl_display connection and wl_surface proxies will mismatch on configure.
  • X11: the X11 Display* (0 = use DISPLAY env var via OpenX11Display).
  • Surfaceless: ignored.

func GetGLProcAddress 

func GetGLProcAddress(name string) unsafe.Pointer

GetGLProcAddress returns the address of an OpenGL function. It uses eglGetProcAddress to load both core and extension functions. Returns unsafe.Pointer for compatibility with goffi-based GL context.

func GetProcAddress 

func GetProcAddress(procname string) uintptr

GetProcAddress returns the address of an EGL or client API extension function.

func HasPlatformWindowSurface added in v0.29.3 

func HasPlatformWindowSurface() bool

HasPlatformWindowSurface reports whether eglCreatePlatformWindowSurface (EGL 1.5) is available. When true, CreatePlatformWindowSurface should be preferred over CreateWindowSurface on Wayland for spec-correct void* native window handling.

func HasSurfacelessSupport added in v0.6.1 

func HasSurfacelessSupport() bool

HasSurfacelessSupport checks if Mesa surfaceless platform is available.

func HasSwapBuffersWithDamage added in v0.26.1 

func HasSwapBuffersWithDamage() bool

HasSwapBuffersWithDamage reports whether the EGL_KHR_swap_buffers_with_damage extension was successfully loaded and is available for use.

func HasWaylandEGL added in v0.29.3 

func HasWaylandEGL() bool

HasWaylandEGL reports whether libwayland-egl.so was loaded successfully.

func Init 

func Init() error

Init loads the EGL library and initializes function pointers.

func InitWaylandEGL added in v0.29.3 

func InitWaylandEGL() bool

InitWaylandEGL loads libwayland-egl.so and prepares CIFs. Safe to call multiple times; only the first call does work.

func QueryClientExtensions added in v0.6.1 

func QueryClientExtensions() string

QueryClientExtensions returns EGL client extensions available without a display. This MUST be called with EGL_NO_DISPLAY to get client extensions. EGL client extensions are extensions that can be queried before display initialization.

func QueryString 

func QueryString(dpy EGLDisplay, name EGLInt) string

QueryString returns a string describing properties of the EGL client or display.

func WlEGLWindowCreate added in v0.29.3 

func WlEGLWindowCreate(wlSurface uintptr, width, height int32) uintptr

WlEGLWindowCreate creates a wl_egl_window from a wl_surface. Returns 0 on failure.

func WlEGLWindowDestroy added in v0.29.3 

func WlEGLWindowDestroy(eglWindow uintptr)

WlEGLWindowDestroy destroys a wl_egl_window.

func WlEGLWindowResize added in v0.29.3 

func WlEGLWindowResize(eglWindow uintptr, width, height, dx, dy int32)

WlEGLWindowResize resizes a wl_egl_window.

Types

type Context 

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

Context wraps an EGL rendering context with its display, config, and surface.

func NewContext 

func NewContext(config ContextConfig) (*Context, error)

NewContext creates a new EGL context with automatic platform detection. It detects the window system (X11, Wayland, or Surfaceless) and creates an appropriate EGL context.

func (*Context) Config 

func (c *Context) Config() EGLConfig

Config returns the EGL config handle.

func (*Context) CreateWindowSurface added in v0.29.11 

func (c *Context) CreateWindowSurface(nativeWindow uintptr) (EGLSurface, error)

CreateWindowSurface creates an EGL window surface for presentation. The surface shares this context's display and config.

func (*Context) Destroy 

func (c *Context) Destroy()

Destroy releases the context and its associated resources. Order matters: EGL resources first, then the native display connection. Closing the native display (e.g. XCloseDisplay) before eglTerminate would cause EGL to access a freed connection.

func (*Context) Display 

func (c *Context) Display() EGLDisplay

Display returns the EGL display handle.

func (*Context) EGLContext 

func (c *Context) EGLContext() EGLContext

EGLContext returns the EGL context handle.

func (*Context) MakeCurrent 

func (c *Context) MakeCurrent() error

MakeCurrent makes this context current on the pbuffer (headless rendering).

func (*Context) MakeCurrentSurface added in v0.29.11 

func (c *Context) MakeCurrentSurface(surface EGLSurface) error

MakeCurrentSurface makes this context current on a window surface (for Present).

func (*Context) Pbuffer 

func (c *Context) Pbuffer() EGLSurface

Pbuffer returns the pbuffer surface.

func (*Context) WindowKind 

func (c *Context) WindowKind() WindowKind

WindowKind returns the detected window system type.

type ContextConfig 

type ContextConfig struct {
	// GLVersionMajor is the major OpenGL version (e.g., 3 for OpenGL 3.3).
	GLVersionMajor int
	// GLVersionMinor is the minor OpenGL version (e.g., 3 for OpenGL 3.3).
	GLVersionMinor int
	// CoreProfile requests a core profile context (vs compatibility).
	CoreProfile bool
	// Debug enables debug context with validation.
	Debug bool
	// GLES requests OpenGL ES instead of desktop OpenGL.
	GLES bool
	// Surfaceless creates a context without a surface (headless rendering).
	Surfaceless bool
	// NativeDisplay is the native display handle to use for EGL display creation.
	// On Wayland: must be the app's wl_display* — passing 0 causes EGL to open
	// a second connection, which makes wl_surface proxies mismatched on configure.
	// On X11: the X11 Display*. Zero uses the default display.
	NativeDisplay uintptr
}

ContextConfig holds configuration options for creating an EGL context.

func DefaultContextConfig 

func DefaultContextConfig() ContextConfig

DefaultContextConfig returns a sensible default context configuration. Creates an OpenGL 3.3 core profile context.

type DisplayOwner 

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

DisplayOwner manages the lifetime of a native display connection. It ensures the display is properly closed when the owner is destroyed.

func OpenX11Display 

func OpenX11Display() *DisplayOwner

OpenX11Display opens an X11 display connection. Returns nil if X11 libraries are not available or display cannot be opened.

func TestWaylandDisplay 

func TestWaylandDisplay() *DisplayOwner

TestWaylandDisplay tests if a Wayland display connection is available. Returns nil if Wayland libraries are not available or display cannot be opened. This function connects and immediately disconnects to test availability.

func (*DisplayOwner) Close 

func (d *DisplayOwner) Close()

Close closes the native display connection and unloads the library.

func (*DisplayOwner) Display 

func (d *DisplayOwner) Display() uintptr

Display returns the native display pointer.

func (*DisplayOwner) Kind 

func (d *DisplayOwner) Kind() WindowKind

Kind returns the window system type.

type EGLAttrib 

type EGLAttrib uintptr

EGLAttrib represents an attribute value (EGL 1.5+).

type EGLBoolean 

type EGLBoolean uint32

EGLBoolean represents a boolean value (EGL_TRUE or EGL_FALSE). 

const (
	False EGLBoolean = 0
	True  EGLBoolean = 1
)

EGL constants - Boolean values

func BindAPI 

func BindAPI(api EGLEnum) EGLBoolean

BindAPI sets the current rendering API.

func ChooseConfig 

func ChooseConfig(dpy EGLDisplay, attribList *EGLInt, configs *EGLConfig, configSize EGLInt, numConfig *EGLInt) EGLBoolean

ChooseConfig returns EGL frame buffer configurations that match specified attributes.

func DestroyContext 

func DestroyContext(dpy EGLDisplay, ctx EGLContext) EGLBoolean

DestroyContext destroys an EGL rendering context.

func DestroySurface 

func DestroySurface(dpy EGLDisplay, surface EGLSurface) EGLBoolean

DestroySurface destroys an EGL surface.

func GetConfigAttrib 

func GetConfigAttrib(dpy EGLDisplay, config EGLConfig, attribute EGLInt, value *EGLInt) EGLBoolean

GetConfigAttrib returns information about an EGL frame buffer configuration.

func Initialize 

func Initialize(dpy EGLDisplay, major *EGLInt, minor *EGLInt) EGLBoolean

Initialize initializes an EGL display connection.

func MakeCurrent 

func MakeCurrent(dpy EGLDisplay, draw EGLSurface, read EGLSurface, ctx EGLContext) EGLBoolean

MakeCurrent binds context to the current rendering thread and surfaces.

func SwapBuffers 

func SwapBuffers(dpy EGLDisplay, surface EGLSurface) EGLBoolean

SwapBuffers posts EGL surface color buffer to a native window.

func SwapBuffersWithDamage added in v0.26.1 

func SwapBuffersWithDamage(dpy EGLDisplay, surface EGLSurface, rects *int32, nRects int32) EGLBoolean

SwapBuffersWithDamage presents the EGL surface with damage rectangle hints. rects is a packed array of int32 quadruples {x, y, width, height} using bottom-left origin (EGL convention — caller must Y-flip from top-left). nRects is the number of rectangles (NOT the number of ints). Returns False on failure.

Falls back to SwapBuffers when EGL_KHR_swap_buffers_with_damage is not available or nRects is 0.

func SwapInterval 

func SwapInterval(dpy EGLDisplay, interval EGLInt) EGLBoolean

SwapInterval specifies the minimum number of video frames between buffer swaps.

func Terminate 

func Terminate(dpy EGLDisplay) EGLBoolean

Terminate terminates an EGL display connection.

type EGLConfig 

type EGLConfig uintptr

EGLConfig represents an EGL frame buffer configuration.

type EGLContext 

type EGLContext uintptr

EGLContext represents an EGL rendering context.

func CreateContext 

func CreateContext(dpy EGLDisplay, config EGLConfig, shareContext EGLContext, attribList *EGLInt) EGLContext

CreateContext creates a new EGL rendering context.

func GetCurrentContext 

func GetCurrentContext() EGLContext

GetCurrentContext returns the current EGL rendering context.

type EGLDisplay 

type EGLDisplay uintptr

EGLDisplay represents an EGL display connection.

func GetCurrentDisplay 

func GetCurrentDisplay() EGLDisplay

GetCurrentDisplay returns the current EGL display connection.

func GetDisplay 

func GetDisplay(displayID EGLNativeDisplayType) EGLDisplay

GetDisplay returns an EGL display connection.

func GetPlatformDisplay 

func GetPlatformDisplay(platform EGLEnum, nativeDisplay uintptr, attribList *EGLAttrib) EGLDisplay

GetPlatformDisplay returns an EGL display connection for a specific platform (EGL 1.5). Falls back to GetDisplay if EGL 1.5 is not available.

type EGLEnum 

type EGLEnum uint32

EGLEnum represents an enumeration value. 

const (
	OpenGLESAPI EGLEnum = 0x30A0
	OpenVGAPI   EGLEnum = 0x30A1
	OpenGLAPI   EGLEnum = 0x30A2
)

EGL constants - API identifiers 

const (
	PlatformX11KHR          EGLEnum = 0x31D5
	PlatformWaylandKHR      EGLEnum = 0x31D8
	PlatformSurfacelessMesa EGLEnum = 0x31DD
	PlatformAngleAngle      EGLEnum = 0x3202
)

EGL constants - Platform types (EGL 1.5 and extensions)

type EGLInt 

type EGLInt int32

EGLInt represents a 32-bit signed integer. 

const (
	Success           EGLInt = 0x3000
	NotInitialized    EGLInt = 0x3001
	BadAccess         EGLInt = 0x3002
	BadAlloc          EGLInt = 0x3003
	BadAttribute      EGLInt = 0x3004
	BadConfig         EGLInt = 0x3005
	BadContext        EGLInt = 0x3006
	BadCurrentSurface EGLInt = 0x3007
	BadDisplay        EGLInt = 0x3008
	BadMatch          EGLInt = 0x3009
	BadNativePixmap   EGLInt = 0x300A
	BadNativeWindow   EGLInt = 0x300B
	BadParameter      EGLInt = 0x300C
	BadSurface        EGLInt = 0x300D
	ContextLost       EGLInt = 0x300E
)

EGL constants - Errors (returned by eglGetError) 

const (
	BufferSize            EGLInt = 0x3020
	AlphaSize             EGLInt = 0x3021
	BlueSize              EGLInt = 0x3022
	GreenSize             EGLInt = 0x3023
	RedSize               EGLInt = 0x3024
	DepthSize             EGLInt = 0x3025
	StencilSize           EGLInt = 0x3026
	ConfigCaveat          EGLInt = 0x3027
	ConfigID              EGLInt = 0x3028
	Level                 EGLInt = 0x3029
	MaxPbufferHeight      EGLInt = 0x302A
	MaxPbufferPixels      EGLInt = 0x302B
	MaxPbufferWidth       EGLInt = 0x302C
	NativeRenderable      EGLInt = 0x302D
	NativeVisualID        EGLInt = 0x302E
	NativeVisualType      EGLInt = 0x302F
	Samples               EGLInt = 0x3031
	SampleBuffers         EGLInt = 0x3032
	SurfaceType           EGLInt = 0x3033
	TransparentType       EGLInt = 0x3034
	TransparentBlueValue  EGLInt = 0x3035
	TransparentGreenValue EGLInt = 0x3036
	TransparentRedValue   EGLInt = 0x3037
	None                  EGLInt = 0x3038
	BindToTextureRGB      EGLInt = 0x3039
	BindToTextureRGBA     EGLInt = 0x303A
	MinSwapInterval       EGLInt = 0x303B
	MaxSwapInterval       EGLInt = 0x303C
	LuminanceSize         EGLInt = 0x303D
	AlphaMaskSize         EGLInt = 0x303E
	ColorBufferType       EGLInt = 0x303F
	RenderableType        EGLInt = 0x3040
	Conformant            EGLInt = 0x3042
)

EGL constants - Config attributes 

const (
	Height               EGLInt = 0x3056
	Width                EGLInt = 0x3057
	LargestPbuffer       EGLInt = 0x3058
	TextureFormat        EGLInt = 0x3080
	TextureTarget        EGLInt = 0x3081
	MipmapTexture        EGLInt = 0x3082
	MipmapLevel          EGLInt = 0x3083
	RenderBuffer         EGLInt = 0x3086
	VGColorspace         EGLInt = 0x3087
	VGAlphaFormat        EGLInt = 0x3088
	HorizontalResolution EGLInt = 0x3090
	VerticalResolution   EGLInt = 0x3091
	PixelAspectRatio     EGLInt = 0x3092
	SwapBehavior         EGLInt = 0x3093
	MultisampleResolve   EGLInt = 0x3099
)

EGL constants - Surface attributes 

const (
	ContextMajorVersion                  EGLInt = 0x3098
	ContextMinorVersion                  EGLInt = 0x30FB
	ContextOpenGLProfileMask             EGLInt = 0x30FD
	ContextOpenGLResetNotification       EGLInt = 0x31BD
	ContextOpenGLCoreProfileBit          EGLInt = 0x00000001
	ContextOpenGLCompatibilityProfileBit EGLInt = 0x00000002
	ContextOpenGLDebug                   EGLInt = 0x31B0
	ContextOpenGLForwardCompatible       EGLInt = 0x31B1
	ContextOpenGLRobustAccess            EGLInt = 0x31B2
	NoResetNotification                  EGLInt = 0x31BE
	LoseContextOnReset                   EGLInt = 0x31BF
)

EGL constants - Context attributes 

const (
	OpenGLESBit  EGLInt = 0x0001
	OpenVGBit    EGLInt = 0x0002
	OpenGLES2Bit EGLInt = 0x0004
	OpenGLBit    EGLInt = 0x0008
	OpenGLES3Bit EGLInt = 0x0040
)

EGL constants - Renderable type mask bits 

const (
	PbufferBit               EGLInt = 0x0001
	PixmapBit                EGLInt = 0x0002
	WindowBit                EGLInt = 0x0004
	VGColorspaceLinearBit    EGLInt = 0x0020
	VGAlphaFormatPreBit      EGLInt = 0x0040
	MultisampleResolveBoxBit EGLInt = 0x0200
	SwapBehaviorPreservedBit EGLInt = 0x0400
)

EGL constants - Surface type mask bits 

const (
	Vendor     EGLInt = 0x3053
	Version    EGLInt = 0x3054
	Extensions EGLInt = 0x3055
	ClientAPIs EGLInt = 0x308D
)

EGL constants - QueryString targets 

const (
	RGBBuffer       EGLInt = 0x308E
	LuminanceBuffer EGLInt = 0x308F
)

EGL constants - Color buffer type 

const (
	ContextFlagsKHR                      EGLInt = 0x30FC
	ContextOpenGLDebugBitKHR             EGLInt = 0x0001
	ContextOpenGLRobustAccessExt         EGLInt = 0x30BF
	PlatformAngleNativePlatformTypeAngle EGLInt = 0x348F
	PlatformAngleDebugLayersEnabled      EGLInt = 0x3451
	GLColorspaceKHR                      EGLInt = 0x309D
	GLColorspaceSRGBKHR                  EGLInt = 0x3089
)

EGL constants - Extension-specific 

const (
	BufferPreserved EGLInt = 0x3094
	BufferDestroyed EGLInt = 0x3095
)

EGL constants - Swap behavior 

const (
	SingleBuffer EGLInt = 0x3085
	BackBuffer   EGLInt = 0x3084
)

EGL constants - Back buffer 

const (
	ContextClientType    EGLInt = 0x3097
	ContextClientVersion EGLInt = 0x3098
)

EGL constants - QueryContext targets

func GetError 

func GetError() EGLInt

GetError returns the last EGL error.

type EGLNativeDisplayType 

type EGLNativeDisplayType uintptr

EGLNativeDisplayType represents a native platform display.

type EGLNativePixmapType 

type EGLNativePixmapType uintptr

EGLNativePixmapType represents a native platform pixmap.

type EGLNativeWindowType 

type EGLNativeWindowType uintptr

EGLNativeWindowType represents a native platform window.

type EGLSurface 

type EGLSurface uintptr

EGLSurface represents an EGL rendering surface.

func CreatePbufferSurface 

func CreatePbufferSurface(dpy EGLDisplay, config EGLConfig, attribList *EGLInt) EGLSurface

CreatePbufferSurface creates a new EGL pixel buffer surface.

func CreatePlatformWindowSurface added in v0.29.3 

func CreatePlatformWindowSurface(dpy EGLDisplay, config EGLConfig, nativeWindow uintptr, attribList *EGLAttrib) EGLSurface

CreatePlatformWindowSurface creates a new EGL window surface using the EGL 1.5 platform-aware API. Takes void* native window instead of EGLNativeWindowType. On Wayland: nativeWindow is wl_egl_window*. Attribs use EGLAttrib (pointer-sized). Rust wgpu-hal egl.rs:1485 uses this when EGL 1.5 is available. Falls back to CreateWindowSurface when EGL 1.5 is not available.

func CreateWindowSurface 

func CreateWindowSurface(dpy EGLDisplay, config EGLConfig, win EGLNativeWindowType, attribList *EGLInt) EGLSurface

CreateWindowSurface creates a new EGL window surface.

type WindowKind 

type WindowKind int

WindowKind represents the type of window system. 

const (
	// WindowKindX11 represents X11 window system.
	WindowKindX11 WindowKind = iota
	// WindowKindWayland represents Wayland window system.
	WindowKindWayland
	// WindowKindSurfaceless represents surfaceless (headless) rendering.
	WindowKindSurfaceless
	// WindowKindUnknown represents unknown window system.
	WindowKindUnknown
)

func DetectWindowKind 

func DetectWindowKind() WindowKind

DetectWindowKind detects the available window system. Priority order:

  1. If no DISPLAY/WAYLAND_DISPLAY set AND surfaceless available -> Surfaceless (for CI)
  2. Wayland (if WAYLAND_DISPLAY is set and works)
  3. X11 (if DISPLAY is set and works)
  4. Surfaceless (final fallback)

func (WindowKind) String 

func (w WindowKind) String() string

String returns the string representation of WindowKind.

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.