oswin

package
v1.2.4 Latest Latest
Warning

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

 Go to latest Published: Mar 2, 2021 License: BSD-3-Clause Imports: 16 Imported by: 20

Documentation

Overview

Package oswin provides interfaces for OS-specific GUI hardware for portable two-dimensional graphics and input events.

The App interface provides a top-level, single-instance struct that knows about specific hardware, and can create new Window and Texture objects that are hardware-specific and provide the primary GUI interface. It is always available as oswin.TheApp.

Events are communicated through the Window -- see EventType and Event in event.go for all the different types.

The driver package creates the App, via its Main function, which is designed to be called by the program's main function. There can be multiple different drivers, but currently OpenGL on top of the glfw cross-platform library (i.e., the glos driver) is the only one supported. See internal/*driver for older shiny-based drivers that are completely OS-specific and do not require cgo for Windows and X11 platforms (but do require it for mac). These older drivers are no longer compatible with the current GPU-based 3D rendering system in gi and gi3d.

package gi/gimain provides the Main method used to initialize the oswin driver that implements the oswin interfaces, and start the main event processing loop.

See examples in gi/examples directory for current example code.

Index

Constants

View Source 
const (
	Over = draw.Over
	Src  = draw.Src
)

These draw.Op constants are provided so that users of this package don't have to explicitly import "image/draw".

Variables

View Source 
var InitScreenLogicalDPIFunc func()

InitScreenLogicalDPIFunc is a function that can be set to initialize the screen LogicalDPI values based on user preferences etc. Called just before first window is opened.

View Source 
var KiT_EventType = kit.Enums.AddEnum(EventTypeN, kit.NotBitFlag, nil)
View Source 
var KiT_Platforms = kit.Enums.AddEnum(PlatformsN, kit.NotBitFlag, nil)
View Source 
var KiT_ScreenOrientation = kit.Enums.AddEnum(ScreenOrientationN, kit.NotBitFlag, nil)
View Source 
var KiT_WindowFlags = kit.Enums.AddEnum(WindowFlagsN, kit.BitFlag, nil)

Functions

func LogicalFmPhysicalDPI 

func LogicalFmPhysicalDPI(logScale, pdpi float32) float32

LogicalFmPhysicalDPI computes the logical DPI used in actual screen scaling based on the given logical DPI scale factor (logScale), and also makes it a multiple of 6 to make normal font sizes look best.

func SendCustomEvent 

func SendCustomEvent(win Window, data interface{})

SendCustomEvent sends a new custom event to given window, with given data -- constructs the event and sends it. For other params you can follow these steps yourself..

func WindowFlagsToBool 

func WindowFlagsToBool(flags int64) (dialog, modal, tool, fullscreen bool)

Types

type App 

type App interface {
	// Platform returns the platform type -- can use this for conditionalizing
	// behavior in minor, simple ways
	Platform() Platforms

	// Name is the overall name of the application -- used for specifying an
	// application-specific preferences directory, etc
	Name() string

	// SetName sets the application name -- defaults to GoGi if not otherwise set
	SetName(name string)

	// NScreens returns the number of different logical and/or physical
	// screens managed under this overall screen hardware
	NScreens() int

	// Screen returns screen for given screen number, or nil if not a
	// valid screen number.
	Screen(scrN int) *Screen

	// ScreenByName returns screen for given screen name, or nil if not a
	// valid screen name.
	ScreenByName(name string) *Screen

	// NoScreens returns true if there are no active screens currently
	// (e.g., for a closed laptop with no external monitor attached)
	// The previous list of Screens is retained so this is the check.
	NoScreens() bool

	// NWindows returns the number of windows open for this app.
	NWindows() int

	// Window returns given window in list of windows opened under this screen
	// -- list is not in any guaranteed order, but typically in order of
	// creation (see also WindowByName) -- returns nil for invalid index.
	Window(win int) Window

	// WindowByName returns given window in list of windows opened under this
	// screen, by name -- nil if not found.
	WindowByName(name string) Window

	// WindowInFocus returns the window currently in focus (receiving keyboard
	// input) -- could be nil if none are.
	WindowInFocus() Window

	// ContextWindow returns the window passed as context for clipboard, cursor, etc calls.
	ContextWindow() Window

	// NewWindow returns a new Window for this screen. A nil opts is valid and
	// means to use the default option values.
	NewWindow(opts *NewWindowOptions) (Window, error)

	// NewTexture returns a new oswin-level GPU Texture for the given window.
	// This Texture will automatically be Activate()'d.
	// See also gpu.TheGPU.NewTexture2D for creating textures for GPU 3D-specific uses.
	NewTexture(win Window, size image.Point) Texture

	// ClipBoard returns the clip.Board handler for the system, in context of given window.
	ClipBoard(win Window) clip.Board

	// Cursor returns the cursor.Cursor handler for the system, in context of given window.
	Cursor(win Window) cursor.Cursor

	// PrefsDir returns the OS-specific preferences directory: Mac: ~/Library,
	// Linux: ~/.config, Windows: ?
	PrefsDir() string

	// GoGiPrefsDir returns the GoGi preferences directory: PrefsDir + GoGi --
	// ensures that the directory exists first.
	GoGiPrefsDir() string

	// AppPrefsDir returns the application-specific preferences directory:
	// PrefsDir + App.Name --ensures that the directory exists first.
	AppPrefsDir() string

	// FontPaths returns the default system font paths.
	FontPaths() []string

	// About is an informative message about the app.  Can use HTML
	// formatting, including links.
	About() string

	// SetAbout sets the about info.
	SetAbout(about string)

	// OpenURL opens the given URL in the user's default browser.  On Linux
	// this requires that xdg-utils package has been installed -- uses
	// xdg-open command.
	OpenURL(url string)

	// OpenFiles returns file names that have been set to be open at startup.
	OpenFiles() []string

	// SetQuitReqFunc sets the function that is called whenever there is a
	// request to quit the app (via a OS or a call to QuitReq() method).  That
	// function can then adjudicate whether and when to actually call Quit.
	SetQuitReqFunc(fun func())

	// SetQuitCleanFunc sets the function that is called whenever app is
	// actually about to quit (irrevocably) -- can do any necessary
	// last-minute cleanup here.
	SetQuitCleanFunc(fun func())

	// QuitReq is a quit request, triggered either by OS or user call (e.g.,
	// via Quit menu action) -- calls function previously-registered by
	// SetQuitReqFunc, which is then solely responsible for actually calling
	// Quit.
	QuitReq()

	// IsQuitting returns true when the app is actually quitting -- it is set
	// to true just before the QuitClean function is called, and before all
	// the windows are closed.
	IsQuitting() bool

	// QuitClean calls the function setup in SetQuitCleanFunc and does other
	// app cleanup -- called on way to quitting.
	QuitClean()

	// Quit closes all windows and exits the program.
	Quit()

	// RunOnMain runs given function on main thread (where main event loop is running)
	// Some functions (GUI-specific etc) must run on this initial main thread for the
	// overall app.
	RunOnMain(f func())

	// GoRunOnMain runs given function on main thread and returns immediately
	// Some functions (GUI-specific etc) must run on this initial main thread for the
	// overall app.
	GoRunOnMain(f func())

	// SendEmptyEvent sends an empty, blank event to global event processing
	// system, which has the effect of pushing the system along during cases when
	// the event loop needs to be "pinged" to get things moving along.
	// See also similar method on Window.
	SendEmptyEvent()

	// PollEvents tells the main event loop to check for any gui events right now.
	// Call this periodically from longer-running functions to ensure
	// GUI responsiveness.
	PollEvents()
}

App represents the overall OS GUI hardware, and creates Images, Textures and Windows, appropriate for that hardware / OS, and maintains data about the physical screen(s) 

var TheApp App

TheApp is the current oswin App -- only ever one in effect

type CustomEvent 

type CustomEvent struct {
	EventBase
	Data     interface{}
	PosAvail bool        `desc:"set to true if position is available"`
	Where    image.Point `desc:"position info if relevant -- set PosAvail"`
	Focus    bool        `desc:"set to true if this event should be sent to widget in focus"`
}

CustomEvent is a user-specified event that can be sent and received as needed, and contains a Data field for arbitrary data, and optional position and focus parameters

func (CustomEvent) HasPos 

func (ce CustomEvent) HasPos() bool

func (CustomEvent) OnFocus 

func (ce CustomEvent) OnFocus() bool

func (CustomEvent) OnWinFocus added in v1.1.3 

func (ce CustomEvent) OnWinFocus() bool

func (CustomEvent) Pos 

func (ce CustomEvent) Pos() image.Point

func (CustomEvent) String 

func (ce CustomEvent) String() string

func (CustomEvent) Type 

func (ce CustomEvent) Type() EventType

type DrawOptions 

type DrawOptions struct {
	// FlipY means flip the Y (vertical) axis of the source when rendering into destination,
	// relative to the default orientation of the source as determined by its BotZero setting.
	FlipY bool
}

DrawOptions are optional arguments to Draw.

type Drawer 

type Drawer interface {
	// Draw draws the sub-Texture defined by src and sr to the destination (the
	// method receiver). src2dst defines how to transform src coordinates to
	// dst coordinates. For example, if src2dst is the matrix
	//
	// m00 m01 m02
	// m10 m11 m12
	// 0   0   1
	//
	// then the src-space point (sx, sy) maps to the dst-space point
	// (m00*sx + m01*sy + m02, m10*sx + m11*sy + m12).
	// Must be called with a valid gpu context and on proper thread for that context.
	Draw(src2dst mat32.Mat3, src Texture, sr image.Rectangle, op draw.Op, opts *DrawOptions)

	// DrawUniform is like Draw except that the src is a uniform color instead
	// of a Texture.
	// Must be called with a valid gpu context and on proper thread for that context.
	DrawUniform(src2dst mat32.Mat3, src color.Color, sr image.Rectangle, op draw.Op, opts *DrawOptions)

	// Copy copies the sub-Texture defined by src and sr to the destination
	// (the method receiver), such that sr.Min in src-space aligns with dp in dst-space.
	// Must be called with a valid gpu context and on proper thread for that context.
	Copy(dp image.Point, src Texture, sr image.Rectangle, op draw.Op, opts *DrawOptions)

	// Scale scales the sub-Texture defined by src and sr to the destination
	// (the method receiver), such that sr in src-space is mapped to dr in
	// dst-space.
	// Must be called with a valid gpu context and on proper thread for that context.
	Scale(dr image.Rectangle, src Texture, sr image.Rectangle, op draw.Op, opts *DrawOptions)

	// Fill fills that part of the destination (the method receiver) defined by
	// dr with the given color.
	//
	// When filling a Window, there will not be any visible effect until
	// Publish is called.
	// Must be called with a valid gpu context and on proper thread for that context.
	Fill(dr image.Rectangle, src color.Color, op draw.Op)
}

Drawer is something you can Draw Textures on (i.e., a Window or another Texture).

Draw is the most general purpose of this interface's methods. It supports arbitrary affine transformations, such as translations, scales and rotations.

Copy and Scale are more specific versions of Draw. The affected dst pixels are an axis-aligned rectangle, quantized to the pixel grid. Copy copies pixels in a 1:1 manner, Scale is more general. They have simpler parameters than the full matrix used by Draw.

When drawing on a Window, there will not be any visible effect until Publish is called.

Draw automatically takes into account the Y-axis orientation of the destination and source textures.

If the destination is a Window, then its Y=0 is always at the bottom.

If the destination is a Texture, its BotZero parameter determines whether Y=0 is at the bottom or top -- the default is Y=0 at the top, which is true for textures loaded from images files or rendered with that standard.

The source texture also has its own BotZero parameter, so that determines whether it is flipped relative to the destination during the rendering.

Finally, if the FlipY option is passed, the source is flipped relative to that determined by the default rules above.

type Event 

type Event interface {
	fmt.Stringer

	// Type returns the type of event associated with given event
	Type() EventType

	// HasPos returns true if the event has a window position where it takes place
	HasPos() bool

	// Pos returns the position in raw display dots (pixels) where event took place -- needed for sending events to the right place
	Pos() image.Point

	// OnFocus returns true if the event operates only on focus item (e.g., keyboard events)
	OnFocus() bool

	// OnWinFocus returns true if the event operates only when the window has focus
	OnWinFocus() bool

	// Time returns the time at which the event was generated, in UnixNano nanosecond units
	Time() time.Time

	// IsProcessed returns whether this event has already been processed
	IsProcessed() bool

	// SetProcessed marks the event as having been processed
	SetProcessed()

	// Init sets the time to now, and any other init -- done just prior to event delivery
	Init()

	// SetTime sets the event time to Now
	SetTime()
}

Event is the interface for oswin GUI events. also includes Stringer to get a string description of the event

type EventBase 

type EventBase struct {
	// GenTime records the time when the event was first generated, using more
	// efficient nptime struct
	GenTime nptime.Time

	// Processed indicates if the event has been processed by an end receiver,
	// and thus should no longer be processed by other possible receivers.
	// Atomic operations are used to encode a 0 or 1, so it is an int32.
	Processed int32
}

EventBase is the base type for events -- records time and whether event has been processed by a receiver of the event -- in which case it is skipped

func (*EventBase) ClearProcessed added in v1.0.5 

func (ev *EventBase) ClearProcessed()

func (*EventBase) Init 

func (ev *EventBase) Init()

func (EventBase) IsProcessed 

func (ev EventBase) IsProcessed() bool

func (EventBase) OnWinFocus added in v1.1.3 

func (ev EventBase) OnWinFocus() bool

func (*EventBase) SetProcessed 

func (ev *EventBase) SetProcessed()

func (*EventBase) SetTime 

func (ev *EventBase) SetTime()

SetTime sets the event time to Now

func (EventBase) String 

func (ev EventBase) String() string

func (EventBase) Time 

func (ev EventBase) Time() time.Time

type EventDeque 

type EventDeque interface {
	// Send adds an event to the end of the deque. They are returned by
	// NextEvent in FIFO order.
	Send(event Event)

	// SendFirst adds an event to the start of the deque. They are returned by
	// NextEvent in LIFO order, and have priority over events sent via Send.
	SendFirst(event Event)

	// NextEvent returns the next event in the deque. It blocks until such an
	// event has been sent.
	NextEvent() Event

	// PollEvent returns the next event in the deque if available, returns true
	// returns false and does not wait if no events currently available
	PollEvent() (Event, bool)
}

EventDeque is an infinitely buffered double-ended queue of events.

type EventType 

type EventType int64

EventType determines which type of GUI event is being sent -- need this for indexing into different event signalers based on event type, and sending event type in signals -- critical to break up different event types into the right categories needed for different types of widgets -- e.g., most do not need move or scroll events, so those are separated. 

const (
	// MouseEvent includes all mouse button actions, but not move or drag
	MouseEvent EventType = iota

	// MouseMoveEvent is when the mouse is moving but no button is down
	MouseMoveEvent

	// MouseDragEvent is when the mouse is moving and there is a button down
	MouseDragEvent

	// MouseScrollEvent is for mouse scroll wheel events
	MouseScrollEvent

	// MouseFocusEvent is for mouse focus (enter / exit of widget area) --
	// generated by gi.Window based on mouse move events
	MouseFocusEvent

	// MouseHoverEvent is for mouse hover -- generated by gi.Window based on
	// mouse events
	MouseHoverEvent

	// KeyEvent for key pressed or released -- fine-grained data about each
	// key as it happens
	KeyEvent

	// KeyChordEvent is only generated when a non-modifier key is released,
	// and it also contains a string representation of the full chord,
	// suitable for translation into keyboard commands, emacs-style etc
	KeyChordEvent

	// TouchEvent is a generic touch-based event
	TouchEvent

	// MagnifyEvent is a touch-based magnify event (e.g., pinch)
	MagnifyEvent

	// RotateEvent is a touch-based rotate event
	RotateEvent

	// WindowEvent reports any changes in the window size, orientation,
	// iconify, close, open, paint -- these are all "internal" events
	// from OS to GUI system, and not sent to widgets
	WindowEvent

	// WindowResizeEvent is specifically for window resize events which need
	// special treatment -- this is an internal event not sent to widgets
	WindowResizeEvent

	// WindowPaintEvent is specifically for window paint events which need
	// special treatment -- this is an internal event not sent to widgets
	WindowPaintEvent

	// WindowShowEvent is a synthetic event sent to widget consumers,
	// sent *only once* when window is shown for the very first time
	WindowShowEvent

	// WindowFocusEvent is a synthetic event sent to widget consumers,
	// sent when window focus changes (action is Focus / DeFocus)
	WindowFocusEvent

	// DNDEvent is for the Drag-n-Drop (DND) drop event
	DNDEvent
	// DNDMoveEvent is when the DND position has changed
	DNDMoveEvent
	// DNDFocusEvent is for Enter / Exit events of the DND into / out of a given widget
	DNDFocusEvent

	// OSEvent is an operating system generated event (app level typically)
	OSEvent
	// OSOpenFilesEvent is an event telling app to open given files
	OSOpenFilesEvent

	// CustomEventType is a user-defined event with a data interface{} field
	CustomEventType

	// number of event types
	EventTypeN
)

func (*EventType) FromString 

func (i *EventType) FromString(s string) error

func (EventType) String 

func (i EventType) String() string
type MainMenu interface {
	// Window returns the window that this menu is attached to.
	Window() Window

	// SetWindow sets the window associated with this main menu.
	SetWindow(win Window)

	// SetFunc sets the callback function that is called whenever a menu item is selected.
	SetFunc(fun func(win Window, title string, tag int))

	// Triggered is called when a menu item is triggered via OS -- calls
	// callback function set in SetFunc.
	Triggered(win Window, title string, tag int)

	// Menu returns the menu pointer for the main menu associated with window.
	// only for READ ONLY purposes -- use StartUpdate when starting to update it.
	Menu() Menu

	// SetMenu sets the menu as the main menu for the window -- generally call this
	// in response to a window.FocusEvent, after building the menu
	SetMenu()

	// StartUpdate locks the menu pointer for the main menu associated with window.
	// only for READ ONLY purposes -- use StartUpdate when starting to update it.
	StartUpdate() Menu

	// EndUpdate unlocks the current update -- must be matched with StartUpdate
	EndUpdate(men Menu)

	// Reset resets all items on given menu -- do this before updating.
	Reset(men Menu)

	// AddSubMenu adds a sub-menu of given title / label to given menu.
	AddSubMenu(men Menu, title string) Menu

	// AddItem adds a menu item of given title / label, shortcut, and tag to
	// given menu.  Callback function set by SetFunc will be called when menu
	// item is selected.
	AddItem(men Menu, title string, shortcut string, tag int, active bool) MenuItem

	// AddSeparator adds a separator menu item.
	AddSeparator(men Menu)

	// ItemByTitle finds menu item by title on given menu -- does not iterate
	// over sub-menus, so that needs to be done manually.
	ItemByTitle(men Menu, title string) MenuItem

	// ItemByTag finds menu item by tag on given menu -- does not iterate
	// over sub-menus, so that needs to be done manually.
	ItemByTag(men Menu, tag int) MenuItem

	// SetItemActive sets the active status of given item.
	SetItemActive(mitem MenuItem, active bool)
}

MainMenu supports the OS-specific main menu associated with a window. 

type Menu uintptr

Menu is a pointer to an OS-specific menu structure. 

type MenuItem uintptr

MenuItem is a pointer to an OS-specific menu item structure.

type NewWindowOptions 

type NewWindowOptions struct {
	// Size specifies the dimensions of the new window, either in raw pixels
	// or std 96 dpi pixels depending on StdPixels. If Width or Height are
	// zero, a driver-dependent default will be used for each zero value
	// dimension
	Size image.Point

	// StdPixels means use standardized "pixel" units for the window size (96
	// per inch), not the actual underlying raw display dot pixels
	StdPixels bool

	// Pos specifies the position of the window, if non-zero -- always in
	// device-specific raw pixels
	Pos image.Point

	// Title specifies the window title.
	Title string

	// Flags can be set using WindowFlags to request different types of windows
	Flags int64
}

NewWindowOptions are optional arguments to NewWindow.

func (*NewWindowOptions) Fixup 

func (o *NewWindowOptions) Fixup()

Fixup fills in defaults and updates everything based on current screen and window context Specific hardware can fine-tune this as well, in driver code

func (*NewWindowOptions) GetTitle 

func (o *NewWindowOptions) GetTitle() string

GetTitle returns a sanitized form of o.Title. In particular, its length will not exceed 4096, and it may be further truncated so that it is valid UTF-8 and will not contain the NUL byte.

o may be nil, in which case "" is returned.

func (*NewWindowOptions) SetDialog 

func (o *NewWindowOptions) SetDialog()

func (*NewWindowOptions) SetFullscreen 

func (o *NewWindowOptions) SetFullscreen()

func (*NewWindowOptions) SetModal 

func (o *NewWindowOptions) SetModal()

func (*NewWindowOptions) SetTool 

func (o *NewWindowOptions) SetTool()

type Platforms 

type Platforms int32

Platforms are all the supported platforms for OSWin 

const (
	// MacOS is a mac desktop machine (aka Darwin)
	MacOS Platforms = iota

	// LinuxX11 is a Linux OS machine running X11 window server
	LinuxX11

	// Windows is a Microsoft Windows machine
	Windows

	PlatformsN
)

func (*Platforms) FromString 

func (i *Platforms) FromString(s string) error

func (Platforms) String 

func (i Platforms) String() string

type Screen 

type Screen struct {
	// ScreenNumber is the index of this screen in the list of screens
	// maintained under Screen.
	ScreenNumber int

	// Geometry contains the geometry of the screen in window manager
	// size units, which may not be same as raw pixels
	Geometry image.Rectangle

	// DevicePixelRatio is a factor that scales the screen's
	// "natural" pixel coordinates into actual device pixels.
	// On OS-X  it is backingScaleFactor = 2.0 on "retina"
	DevicePixelRatio float32

	//	PixSize is the number of actual pixels in the screen
	// computed as Size * DevicePixelRatio
	PixSize image.Point

	// PhysicalSize is the actual physical size of the screen, in mm.
	PhysicalSize image.Point

	// LogicalDPI is the logical dots per inch of the screen,
	// which is used for all rendering -- subject to zooming
	// effects etc -- see the gi/units package for translating
	// into various other units.
	LogicalDPI float32

	// PhysicalDPI is the physical dots per inch of the screen,
	// for generating true-to-physical-size output, for example
	// see the gi/units package for translating into various other
	// units.
	PhysicalDPI float32

	// Color depth of the screen, in bits.
	Depth int

	// Refresh rate in Hz
	RefreshRate float32

	Orientation        ScreenOrientation
	NativeOrientation  ScreenOrientation
	PrimaryOrientation ScreenOrientation

	Name         string
	Manufacturer string
	Model        string
	SerialNumber string
}

Screen contains data about each physical and / or logical screen

type ScreenOrientation 

type ScreenOrientation int32

ScreenOrientation is the orientation of the device screen. 

const (
	// OrientationUnknown means device orientation cannot be determined.
	//
	// Equivalent on Android to Configuration.ORIENTATION_UNKNOWN
	// and on iOS to:
	//	UIDeviceOrientationUnknown
	//	UIDeviceOrientationFaceUp
	//	UIDeviceOrientationFaceDown
	OrientationUnknown ScreenOrientation = iota

	// Portrait is a device oriented so it is tall and thin.
	//
	// Equivalent on Android to Configuration.ORIENTATION_PORTRAIT
	// and on iOS to:
	//	UIDeviceOrientationPortrait
	//	UIDeviceOrientationPortraitUpsideDown
	Portrait

	// Landscape is a device oriented so it is short and wide.
	//
	// Equivalent on Android to Configuration.ORIENTATION_LANDSCAPE
	// and on iOS to:
	//	UIDeviceOrientationLandscapeLeft
	//	UIDeviceOrientationLandscapeRight
	Landscape

	ScreenOrientationN
)

func (*ScreenOrientation) FromString 

func (i *ScreenOrientation) FromString(s string) error

func (ScreenOrientation) String 

func (i ScreenOrientation) String() string

type Texture 

type Texture interface {
	// Name returns the name of the texture (filename without extension
	// by default)
	Name() string

	// SetName sets the name of the texture
	SetName(name string)

	// Open loads texture image from file.
	// Format inferred from filename -- JPEG and PNG supported by default.
	// Generally call this prior to doing Activate --
	// if Activate()'d, then must be called with a valid gpu context
	// and on proper thread for that context.
	Open(path string) error

	// Image returns the current image -- typically as an *image.RGBA.
	// This is the image that was last set using Open, SetImage, or GrabImage.
	// Use GrabImage to get the current GPU-side image, e.g., for rendering targets.
	Image() image.Image

	// GrabImage retrieves the current contents of the Texture, e.g., if it has been
	// used as a rendering target (Y axis flipped so top = 0).  Returns nil if not initialized.
	// Must be called with a valid gpu context and on proper thread for that context.
	// Returned image points to single internal image.RGBA used for this texture --
	// copy before modifying and to retain values.
	GrabImage() image.Image

	// SetImage sets entire contents of the Texture from given image
	// (including setting the size of the texture from that of the img).
	// This is most efficiently done using an image.RGBA, but other
	// formats will be converted as necessary.  Image Y axis is automatically
	// flipped when transferred up to the texture, so texture has bottom = 0.
	// Can be called prior to doing Activate(), in which case the image
	// pixels will then initialize the GPU version of the texture.
	// (most efficient case for standard GPU / 3D usage).
	// If called after Activate then the image is copied up to the GPU
	// and texture is left in an Activate state.
	// If Activate()'d, then must be called with a valid gpu context
	// and on proper thread for that context.
	SetImage(img image.Image) error

	// ImageFlipY flips the Y axis from a source image.RGBA into a dest.
	// both must be the same size else it panics.  This utility function
	// is needed for GrabImage and is made avail for general use here.
	ImageFlipY(dest, src *image.RGBA)

	// SetSubImage uploads the sub-Image defined by src and sr to the texture.
	// such that sr.Min in src-space aligns with dp in dst-space.
	// The textures's contents are overwritten; the draw operator
	// is implicitly draw.Src. Texture must be Activate'd to the GPU for this
	// to proceed -- if Activate() has not yet been called, it will be (on texture 0).
	// Must be called with a valid gpu context and on proper thread for that context.
	SetSubImage(dp image.Point, src image.Image, sr image.Rectangle) error

	// Size returns the size of the texture
	Size() image.Point

	// SetSize sets the size of the texture.
	// If texture has been Activate'd, then this resizes the GPU side as well.
	// If Activate()'d, then must be called with a valid gpu context
	// and on proper thread for that context.
	SetSize(size image.Point)

	// Bounds returns the bounds of the Texture's image. It is equal to
	// image.Rectangle{Max: t.Size()}.
	Bounds() image.Rectangle

	// BotZero returns true if this texture has the Y=0 pixels at the bottom
	// of the image.  Otherwise, Y=0 is at the top, which is the default
	// for most images loaded from files.
	BotZero() bool

	// SetBotZero sets whether this texture has the Y=0 pixels at the bottom
	// of the image.  Otherwise, Y=0 is at the top, which is the default
	// for most images loaded from files.
	SetBotZero(botzero bool)

	// Activate establishes the GPU resources and handle for the
	// texture, using the given texture number (0-31 range).
	// If an image has already been set for this texture, then it is
	// copied up to the GPU at this point -- otherwise the texture
	// is nil initialized.
	// Must be called with a valid gpu context and on proper thread for that context.
	Activate(texNo int)

	// IsActive returns true if texture has already been Activate'd
	// and thus exists on the GPU
	IsActive() bool

	// Handle returns the GPU handle for the texture -- only
	// valid after Activate.
	Handle() uint32

	// Transfer copies current image up to the GPU, activating on given
	// texture number.  Returns false if there is no image to transfer.
	// Must be called with a valid gpu context and on proper thread for that context.
	Transfer(texNo int) bool

	// Delete deletes the GPU resources associated with this texture
	// (requires Activate to re-establish a new one).
	// Should be called prior to Go object being deleted
	// (ref counting can be done externally).
	// Must be called with a valid gpu context and on proper thread for that context.
	Delete()

	// ActivateFramebuffer creates a gpu.Framebuffer for rendering onto
	// this texture (if not already created) and activates it for
	// rendering.  The gpu.Texture2D interface can provide direct access
	// to the created framebuffer.
	// Call gpu.TheGPU.RenderToWindow() or DeActivateFramebuffer
	// to return to window rendering.
	// Must be called with a valid gpu context and on proper thread for that context.
	ActivateFramebuffer()

	// DeActivateFramebuffer de-activates this texture's framebuffer
	// for rendering (just calls gpu.TheGPU.RenderToWindow())
	// Must be called with a valid gpu context and on proper thread for that context.
	DeActivateFramebuffer()

	// DeleteFramebuffer deletes this Texture's framebuffer
	// created during ActivateFramebuffer.
	// Must be called with a valid gpu context and on proper thread for that context.
	DeleteFramebuffer()

	// FrameDepthAt return depth (0-1) at given pixel location from texture used as a framebuffer
	// Must be called with a valid gpu context and on proper thread for that context.
	FrameDepthAt(x, y int) (float32, error)

	Drawer
}

Texture is a pixel buffer on the GPU, and is synonymous with the gpu.Texture2D interface.

It must be defined here at the oswin level because it provides the updatable backing for a Window: you render to a Texture which is then drawn to the window during PublishTex().

Images can be uploaded to Textures, and Textures can be drawn on Windows. Textures can also be drawn onto Textures, and can grab rendered output from 3D graphics rendering (e.g., via gpu.FrameBuffer and gi3d packages).

Unlike Window, the Drawer interface for Texture does *not* manage the TheApp.RunOnMain and context Activate steps needed to set GPU context properly - these must be done prior to calling any of those routines. Also, a 0,0 = top, left coordinate system is assumed for all Draw routines, but when drawing onto a Texture, its 0,0 is actually bottom, left, so that is managed internally to preserve the same overall coordinate system.

Please use the gpu.Texture2D version for GPU-based texture uses (3D rendering) for greater clarity.

For GPU-level uses, a Texture can be created and configured prior to calling Activate(), which is when the GPU-side version of the texture is created and configured. Window-backing Textures are always Activated and are automatically resized etc along with their parent window.

type Window 

type Window interface {

	// Name returns the name of the window -- name is used strictly for
	// internal tracking and finding of windows -- see Title for the displayed
	// title of the window.
	Name() string

	// SetName sets the name of the window.
	SetName(name string)

	// Title returns the current title of the window, which is displayed in the GUI.
	Title() string

	// SetTitle sets the current title of the window, which is displayed in the GUI.
	SetTitle(title string)

	// Size returns the current size of the window, in raw underlying dots / pixels.
	// This includes any high DPI factors that may not be used in OS window sizing
	//  (see WinSize for that size).
	Size() image.Point

	// WinSize returns the current size of the window, in OS-specific window manager
	// units that may not include any high DPI factors.
	WinSize() image.Point

	// Position returns the current left-top position of the window relative to
	// underlying screen, in OS-specific window manager coordinates.
	Position() image.Point

	// SetSize sets the size of the window, in OS-specific window manager
	// units that may not include any high DPI factors (DevPixRatio)
	// (i.e., the same units as returned in WinSize)
	SetSize(sz image.Point)

	// SetPixSize sets the size of the window, in actual pixel units.
	// Divides by DevPixRatio before calling SetSize.
	SetPixSize(sz image.Point)

	// SetPos sets the position of the window, in OS window manager
	// coordinates, which may be different from Size() coordinates
	// that reflect high DPI
	SetPos(pos image.Point)

	// SetGeom sets the position and size in one call -- use this if doing
	// both because sequential calls to SetPos and SetSize might fail on some
	// platforms.  Uses OS-specific window manager units that may not include
	// any high DPI factors (DevPixRatio)
	// (i.e., the same units as returned in WinSize, Pos())
	SetGeom(pos image.Point, sz image.Point)

	// Raise requests that the window be at the top of the stack of windows,
	// and receive focus.  If it is iconified, it will be de-iconified.  This
	// is the only supported mechanism for de-iconifying.
	Raise()

	// Minimize requests that the window be iconified, making it no longer
	// visible or active -- rendering should not occur for minimized windows.
	Minimize()

	// PhysicalDPI is the physical dots per inch of the window, for generating
	// true-to-physical-size output, for example -- see the gi/units package for
	// translating into various other units.
	PhysicalDPI() float32

	// LogicalDPI returns the current logical dots-per-inch resolution of the
	// window, which should be used for most conversion of standard units --
	// physical DPI can be found in the Screen.
	LogicalDPI() float32

	// SetLogicalDPI sets the current logical dots-per-inch resolution of the
	// window, which should be used for most conversion of standard units --
	// physical DPI can be found in the Screen.
	SetLogicalDPI(dpi float32)

	// Screen returns the screen for this window, with all the relevant
	// information about its properties.
	Screen() *Screen

	// Parent returns the parent object of a given window -- for GoGi it is a
	// gi.Window but could be something else in other frameworks.
	Parent() interface{}

	// SetParent sets the parent object of a given window -- for GoGi it is a
	// gi.Window but could be something else in other frameworks.
	SetParent(par interface{})

	// MainMenu returns the OS-level main menu for this window -- this is
	// currently for MacOS only -- returns nil for others.
	MainMenu() MainMenu

	// Flags returns the bit flags for this window's properties set according
	// to WindowFlags bits.
	Flags() int64

	// IsDialog returns true if this is a dialog window.
	IsDialog() bool

	// IsModal returns true if this is a modal window (blocks input to other windows).
	IsModal() bool

	// IsTool returns true if this is a tool window.
	IsTool() bool

	// IsFullscreen returns true if this is a fullscreen window.
	IsFullscreen() bool

	// IsMinimized returns true if this window is minimized.  See also IsVisible()
	IsMinimized() bool

	// IsFocus returns true if this window is focused (will receive keyboard input etc).
	IsFocus() bool

	// IsClosed returns true if this window has been closed (but some threads
	// may have not received the news yet)
	IsClosed() bool

	// IsVisible returns true if this window is not closed or minimized and
	// there are active screens
	IsVisible() bool

	// SetCloseReqFunc sets the function that is called whenever there is a
	// request to close the window (via a OS or a call to CloseReq() method).  That
	// function can then adjudicate whether and when to actually call Close.
	SetCloseReqFunc(fun func(win Window))

	// SetCloseCleanFunc sets the function that is called whenever window is
	// actually about to close (irrevocably) -- can do any necessary
	// last-minute cleanup here.
	SetCloseCleanFunc(fun func(win Window))

	// CloseReq is a close request, triggered either by OS or user call (e.g.,
	// via Close menu action) -- calls function previously-registered by
	// SetCloseReqFunc, which is then solely responsible for actually calling
	// Close.
	CloseReq()

	// CloseClean calls the function setup in SetCloseCleanFunc and does other
	// window cleanup -- called on way to closing.
	CloseClean()

	// Close requests that the window be closed. The behavior of the Window
	// after this, whether calling its methods or passing it as an argument,
	// is undefined.  See App.Quit methods to quit overall app.
	Close()

	// RunOnWin runs given function on the window's own separate goroutine
	RunOnWin(f func())

	// GoRunOnWin runs given function on the window's unique locked thread
	// and returns immediately.
	GoRunOnWin(f func())

	// Activate() sets this window as the current render target for gpu rendering
	// functions, and the current context for gpu state (equivalent to
	// MakeCurrentContext on OpenGL).
	// If it returns false, then window is not visible / valid and
	// nothing further should happen.
	// Must call this on app main thread using oswin.TheApp.RunOnMain
	//
	// oswin.TheApp.RunOnMain(func() {
	//    if !win.Activate() {
	//        return
	//    }
	//    // do GPU calls here
	// })
	//
	Activate() bool

	// DeActivate() clears the current render target and gpu rendering context.
	// Generally more efficient to NOT call this and just be sure to call
	// Activate where relevant, so that if the window is already current context
	// no switching is required.
	// Must call this on app main thread using oswin.TheApp.RunOnMain
	DeActivate()

	// Publish does the equivalent of SwapBuffers on OpenGL: pushes the
	// current rendered back-buffer to the front (and ensures that any
	// ongoing rendering has completed) (see also PublishTex)
	Publish()

	// PublishTex draws the current WinTex texture to the window and then
	// calls Publish() -- this is the typical update call.
	PublishTex()

	// SendEmptyEvent sends an empty, blank event to this window, which just has
	// the effect of pushing the system along during cases when the window
	// event loop needs to be "pinged" to get things moving along..
	SendEmptyEvent()

	// WinTex() returns the current Texture of the same size as the window that
	// is typically used to update the window contents.
	// Use the various Drawer and SetSubImage methods to update this Texture, and
	// then call PublishTex() to update the window.
	// This Texture is automatically resized when the window is resized, and
	// when that occurs, existing contents are lost -- a full update of the
	// Texture at the current size is required at that point.
	WinTex() Texture

	// SetWinTexSubImage calls SetSubImage on WinTex with given parameters.
	// convenience routine that activates the window context and runs on the
	// window's thread.
	SetWinTexSubImage(dp image.Point, src image.Image, sr image.Rectangle) error

	// Handle returns the driver-specific handle for this window.
	// Currently, for all platforms, this is *glfw.Window, but that
	// cannot always be assumed.  Only provided for unforeseen emergency use --
	// please file an Issue for anything that should be added to Window
	// interface.
	Handle() interface{}

	// OSHandle returns the OS-specific underlying window handle:
	// MacOS: NSWindow*, Windows:  HWND, LinuxX11: X11Window
	OSHandle() uintptr

	// Sets the mouse position to given values
	SetMousePos(x, y float64)

	// Sets the mouse cursor to be enabled (true by default) or disabled (false).
	// If disabled, setting raw to true will enable raw mouse movement
	// which can provide better control in a game environment (not avail on Mac).
	SetCursorEnabled(enabled, raw bool)

	EventDeque

	Drawer
}

Window is a double-buffered OS-specific hardware window.

It provides basic GPU support functions, and is currently implemented via OpenGL on top of glfw cross-platform window mgmt toolkit (see driver/glos). A Vulkan-based implementation is also planned.

The Window maintains a Texture of the same dimensions, as WinTex(), which is used for updating the window contents. Call SetSubImage or the various Draw methods on the WinTex() to update the window contents, and PublishTex() to update the window display with the current Texture.

The Drawer interface methods can also be called to render textures directly into the window backbuffer, and Publish() called to swap buffers. Direct rendering to the window can also be accomplished via the oswin/gpu interfaces -- call Activate() on the window to make it the current context and render target (equivalent to MakeCurrentContext OpenGL call).

Each window has a separate goroutine where Publish() is actually executed.

IMPORTANT: ALL GPU (e.g., OPENGL) CALLS MUST USE oswin.TheApp.RunOnMain() to execute on the main thread!!

type WindowBase 

type WindowBase struct {
	Nm          string
	Titl        string
	Pos         image.Point
	WnSize      image.Point // window-manager coords
	PxSize      image.Point // pixel size
	DevPixRatio float32
	PhysDPI     float32
	LogDPI      float32
	Par         interface{}
	Flag        int64
}

WindowBase provides a base-level implementation of the generic data aspects of the window, including maintaining the current window size and dpi

func (*WindowBase) Flags 

func (w *WindowBase) Flags() int64

func (*WindowBase) IsDialog 

func (w *WindowBase) IsDialog() bool

func (*WindowBase) IsFocus 

func (w *WindowBase) IsFocus() bool

func (*WindowBase) IsFullscreen 

func (w *WindowBase) IsFullscreen() bool

func (*WindowBase) IsMinimized 

func (w *WindowBase) IsMinimized() bool

func (*WindowBase) IsModal 

func (w *WindowBase) IsModal() bool

func (*WindowBase) IsTool 

func (w *WindowBase) IsTool() bool

func (WindowBase) Name 

func (w WindowBase) Name() string

func (WindowBase) Parent 

func (w WindowBase) Parent() interface{}

func (*WindowBase) SetName 

func (w *WindowBase) SetName(name string)

func (*WindowBase) SetParent 

func (w *WindowBase) SetParent(parent interface{})

func (WindowBase) Title 

func (w WindowBase) Title() string

type WindowFlags 

type WindowFlags int32

WindowFlags contains all the binary properties of a window -- by default with no other relevant flags a window is a main top-level window. 

const (
	// Dialog indicates that this is a temporary, pop-up window.
	Dialog WindowFlags = iota

	// Modal indicates that this dialog window blocks events going to other
	// windows until it is closed.
	Modal

	// Tool indicates that this is a floating tool window that has minimized
	// window decoration.
	Tool

	// Fullscreen indicates a window that occupies the entire screen.
	Fullscreen

	// Minimized indicates a window reduced to an icon, or otherwise no longer
	// visible or active.  Otherwise, the window should be assumed to be
	// visible.
	Minimized

	// Focus indicates that the window has the focus.
	Focus

	WindowFlagsN
)

func (*WindowFlags) FromString 

func (i *WindowFlags) FromString(s string) error

func (WindowFlags) String 

func (i WindowFlags) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package clip defines the system clipboard for the GoGi GUI system.
 Package clip defines the system clipboard for the GoGi GUI system.
Package cursor defines the oswin cursor interface and standard system cursors that are supported across platforms
 Package cursor defines the oswin cursor interface and standard system cursors that are supported across platforms
Package dnd defines the system drag-and-drop events for the GoGi GUI system.
 Package dnd defines the system drag-and-drop events for the GoGi GUI system.
Package driver provides the default driver for accessing a screen.
 Package driver provides the default driver for accessing a screen.
glos
internal/_errapp
Package errapp provides a stub App implementation.
 Package errapp provides a stub App implementation.
internal/_macdriver
Package macdriver provides an OpenGL-based driver for MacOS platform.
 Package macdriver provides an OpenGL-based driver for MacOS platform.
internal/_swizzle
Package swizzle provides functions for converting between RGBA pixel formats.
 Package swizzle provides functions for converting between RGBA pixel formats.
internal/_vulkan
internal/_windriver
internal/_x11driver
Package x11driver provides the X11 driver for oswin
 Package x11driver provides the X11 driver for oswin
internal/drawer
Package drawer provides functions that help implement screen.Drawer methods.
 Package drawer provides functions that help implement screen.Drawer methods.
internal/event
Package event provides an infinitely buffered double-ended queue of events.
 Package event provides an infinitely buffered double-ended queue of events.
internal/glgpu
Package gpu provides an abstract interface to a graphical processing unit (GPU).
 Package gpu provides an abstract interface to a graphical processing unit (GPU).
Package key defines an event for physical keyboard keys, for the GoGi GUI system.
 Package key defines an event for physical keyboard keys, for the GoGi GUI system.
Package mimedata defines MIME data support used in clipboard and drag-and-drop functions in the GoGi GUI.
 Package mimedata defines MIME data support used in clipboard and drag-and-drop functions in the GoGi GUI.
Package mouse defines mouse events, for the GoGi GUI system.
 Package mouse defines mouse events, for the GoGi GUI system.
Package osevent defines operating system level events, not associated with a particular window.
 Package osevent defines operating system level events, not associated with a particular window.
Package touch defines an event for touch input, for the GoGi GUI system.
 Package touch defines an event for touch input, for the GoGi GUI system.
Package window defines events associated with windows -- including changes in the dimensions, physical resolution and orientation of the app's window, and iconify, open and close events.
 Package window defines events associated with windows -- including changes in the dimensions, physical resolution and orientation of the app's window, and iconify, open and close events.

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.