shared

README

package shared: Cross Platform Window Interface

This package implements an extremely simple interface for opening a window on different OS platforms, and for receiving certain events from the user and window system. Not all messages have been implemented yet!

• User events: Key press, mouse movement, mouse enter/exit
• Window events: resize, minimize, lose/gain focus

To use this pacakge, do:

    app := shared.NewApp()
    ch := app.GetEventChannel()
    
    go myCustomEventLoop(ch) // You have to write this, see the samples for examples

    app.Run() // Run() must execute on the main thread and it blocks until the window is closed.

Events

Events are fed into a channel which can be read by user code. The recommended procedure for each frame is to read all events (i.e. empty the channel) before rendering the current frame. This package does not attempt to bubble or delgate events to components in any way.

Message Dispatch Loop

1. Receive a message from the OS.
2. Build the internal message based on the OS-provided details.
3. Send the message to the message channel.

A final ET_Sys_Close message will be added to the channel when a request to close the window is received, after which the channel will be close by the sender. It is up to the programmer to clean up any Vulkan resources and call OkToClose before exiting the event loop. The OkToClose function signals that your application has completed cleanup and will not attempt to draw another frame, allowing the window to be safely destroyed.

Documentation

Index

• type App
• type EventMessage
• type EventType
• type KeyEvent
• type KeyModBitFlags
• type MouseBtnBitFlags
• type MouseEvent
• type SystemEvent

Types

type App

type App interface {
	// Specify the width and height of the window before opening, and the location via top and left offset.
	// For example, (800, 600, 20, 20) will position an 800 x 600 pixel window 20 pixels from the top and from the left
	// edge of the screen. Note that the renderable surface may not be the full width and height depending on
	// the underlying window system. If not called, then the default window is 640x480 at an arbitrary screen location.
	// Setting these values to a negative number will trigger the default behavior.
	SetWindowParams(width, height, left, top int)

	GetEventChannel() <-chan EventMessage
	// GetHandleForSurface returns the OS-specific handle that can be used to create a vk.SurfaceKHR.
	// The handle returned by this function will be 0 before Run() has been called and after Run() completes.
	// The handle will also be embedded in the window creation message (ET_Sys_Created).
	// GetHandleForSurface() uintptr
	Run() error

	// OkToClose notifies the window system that it is ok to close the window at this point in time. This should be
	// called by the app once a ET_Sys_Closed message is received. The window system will cause this message to be sent
	// when the user has requested to close the window. The OkToClose callback is needed to avoid destroying the window
	// in the middle of a draw call, which will cause a crash instead of a clean shutdown.
	// The app should exit the message loop after calling this function.
	OkToClose(handle uintptr)

	GetRequiredInstanceExtensions() []string

	DelegateCreateSurface(instance vk.Instance) (vk.SurfaceKHR, error)
}

type EventMessage

type EventMessage struct {
	Type EventType

	*MouseEvent
	*KeyEvent
	*SystemEvent
}

type EventType

type EventType int

const (
	ET_None EventType = iota

	ET_Mouse_Scroll
	ET_Mouse_Move
	ET_Mouse_Drag
	ET_Mouse_ButtonDown
	ET_Mouse_ButtonUp
	ET_Mouse_Click

	ET_Key_Down
	ET_Key_Up
	ET_Key_Repeat

	// Sent when the window has been created, but not neccesarily visible. Guaranteed to be the first message sent.
	ET_Sys_Created
	// Sent when the window has closed. Guaranteed to be the last event sent.
	ET_Sys_Closed

	ET_Sys_Minimize
	ET_Sys_UnMinimize
	ET_Sys_Maximize
	ET_Sys_LostFocus
	ET_Sys_RecieveFocus
	ET_Sys_ResizeStart
	ET_Sys_ResizeProgress
	ET_Sys_ResizeComplete

	ET_Maximum
)

type KeyEvent

type KeyEvent struct {
	KeyCode uint16
	// Rune is the UTF-8 rune that the OS interprets this keypress as. It can be different from the key code
	// e.g. if shift is pressed, if the user has a key mapping configured, or if a combination of keys results
	// in a (non-ascii) unicode rune according to the operating system.
	Rune      rune
	Modifiers KeyModBitFlags
}

type KeyModBitFlags

type KeyModBitFlags uint32

const (
	KeyModNone KeyModBitFlags = 0

	KeyModLeftShift  KeyModBitFlags = 1 << 1
	KeyModRightShift KeyModBitFlags = 1 << 2
	KeyModLeftCtrl   KeyModBitFlags = 1 << 3
	KeyModRightCtrl  KeyModBitFlags = 1 << 4
	KeyModLeftAlt    KeyModBitFlags = 1 << 5 // LeftAlt is the same as left option on Mac keyboard
	KeyModRightAlt   KeyModBitFlags = 1 << 6 // RightAlt is the same as right option on Mac keyboard
	KeyModLeftMeta   KeyModBitFlags = 1 << 7 // LeftMeta is the left command key on Mac and the left Windows key on win32
	KeyModRightMeta  KeyModBitFlags = 1 << 8 // RightMeta is the right command key on Mac and the right Windows key on win32

	//export KeyModAnyShift
	KeyModAnyShift KeyModBitFlags = KeyModLeftShift | KeyModRightShift
	KeyModAnyCtrl  KeyModBitFlags = KeyModLeftCtrl | KeyModRightCtrl
	KeyModAnyAlt   KeyModBitFlags = KeyModLeftAlt | KeyModRightAlt
	KeyModAnyMeta  KeyModBitFlags = KeyModLeftMeta | KeyModRightMeta
)

type MouseBtnBitFlags

type MouseBtnBitFlags uint8

const (
	MouseBtnNone   MouseBtnBitFlags = 0
	MouseBtnLeft   MouseBtnBitFlags = 1 << 0
	MouseBtnRight  MouseBtnBitFlags = 1 << 1
	MouseBtnMiddle MouseBtnBitFlags = 1 << 2
)

type MouseEvent

type MouseEvent struct {
	TriggerButtonMask    MouseBtnBitFlags // Only one bit will be set, and only for ButtonDown, ButtonUp, and Click events
	ButtonsMask          MouseBtnBitFlags // Potentially multiple bits will be set, showing the state of all buttons at the time of this event
	LocationX, LocationY uint16           // Event location in the window active area. (0,0) is [system dependent? Always lower left?]
	Modifiers            KeyModBitFlags
}

type SystemEvent

type SystemEvent struct {
	HandleForSurface          uintptr
	WindowWidth, WindowHeight uint32
}

SystemEvent todo...window handle, process handle, others?