Documentation
¶
Overview ¶
Package ebitenginewidget provides a Guigui widget that hosts a separate Ebitengine application.
The Ebitengine widget runs a prebuilt Ebitengine binary as a virtualization guest of Ebitengine's exp/vmhost package: the guest runs in its own process, and the widget forwards the window's input to it, composites its rendered frames into the widget's area, and plays its audio.
The guest binary must be built with the "ebitenginevmguest" build tag and against the same Ebitengine version as the host, since the two speak a version-locked protocol. This package depends on the experimental exp/vmhost, whose API may change.
Index ¶
- type AudioSampleRateMismatchError
- type Ebitengine
- func (e *Ebitengine) AdvanceTicks(n int)
- func (e *Ebitengine) Close() error
- func (e *Ebitengine) CursorShape(context *guigui.Context, widgetBounds *guigui.WidgetBounds) (ebiten.CursorShapeType, bool)
- func (e *Ebitengine) Draw(context *guigui.Context, widgetBounds *guigui.WidgetBounds, dst *ebiten.Image)
- func (e *Ebitengine) HandlePointingInput(context *guigui.Context, widgetBounds *guigui.WidgetBounds) guigui.HandleInputResult
- func (e *Ebitengine) IsRunning() bool
- func (e *Ebitengine) OnError(f func(context *guigui.Context, err error))
- func (e *Ebitengine) OnExited(f func(context *guigui.Context))
- func (e *Ebitengine) OnLaunched(f func(context *guigui.Context))
- func (e *Ebitengine) OnTPSRequested(f func(context *guigui.Context, tps int))
- func (e *Ebitengine) Session() *vmhost.GuestSession
- func (e *Ebitengine) SetAudioEnabled(enabled bool)
- func (e *Ebitengine) SetBinaryPath(path string)
- func (e *Ebitengine) SetCommandArgs(args []string)
- func (e *Ebitengine) SetCommandEnv(env []string)
- func (e *Ebitengine) SetInputForwardingEnabled(enabled bool)
- func (e *Ebitengine) SetTPS(tps int)
- func (e *Ebitengine) Tick(context *guigui.Context, widgetBounds *guigui.WidgetBounds) error
- type GuestNotConnectedError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AudioSampleRateMismatchError ¶
type AudioSampleRateMismatchError struct {
// CurrentSampleRate is the audio context's sample rate.
CurrentSampleRate int
// NewSampleRate is the guest's sample rate.
NewSampleRate int
}
AudioSampleRateMismatchError is reported to the OnError handler when the guest's audio cannot be played because the guest's sample rate does not match the process's audio context.
func (*AudioSampleRateMismatchError) Error ¶
func (e *AudioSampleRateMismatchError) Error() string
type Ebitengine ¶
type Ebitengine struct {
guigui.DefaultWidget
// contains filtered or unexported fields
}
Ebitengine is a Guigui widget that runs a prebuilt Ebitengine binary as a guest process and renders it in place. Its zero value is ready to use; a binary is selected with Ebitengine.SetBinaryPath.
The widget owns a child process and related OS resources. Call Ebitengine.Close to release them; otherwise they are reclaimed only when the process exits.
func (*Ebitengine) AdvanceTicks ¶
func (e *Ebitengine) AdvanceTicks(n int)
AdvanceTicks requests n additional updates on the guest, applied at the widget's next tick while a guest is running. Combined with SetTPS(0), the widget's owner fully controls the guest's pace. n must not be negative.
func (*Ebitengine) Close ¶
func (e *Ebitengine) Close() error
Close stops the guest and releases the widget's OS resources. Close is idempotent.
func (*Ebitengine) CursorShape ¶
func (e *Ebitengine) CursorShape(context *guigui.Context, widgetBounds *guigui.WidgetBounds) (ebiten.CursorShapeType, bool)
CursorShape returns the cursor shape the guest's game requests via ebiten.SetCursorShape.
func (*Ebitengine) Draw ¶
func (e *Ebitengine) Draw(context *guigui.Context, widgetBounds *guigui.WidgetBounds, dst *ebiten.Image)
func (*Ebitengine) HandlePointingInput ¶
func (e *Ebitengine) HandlePointingInput(context *guigui.Context, widgetBounds *guigui.WidgetBounds) guigui.HandleInputResult
HandlePointingInput focuses the widget when it is clicked, so subsequent keyboard input is forwarded to the guest.
func (*Ebitengine) IsRunning ¶
func (e *Ebitengine) IsRunning() bool
IsRunning reports whether a guest is currently running.
func (*Ebitengine) OnError ¶
func (e *Ebitengine) OnError(f func(context *guigui.Context, err error))
OnError sets a handler called when launching or driving the guest fails. Without a handler, failures are logged.
func (*Ebitengine) OnExited ¶
func (e *Ebitengine) OnExited(f func(context *guigui.Context))
OnExited sets a handler called when the guest has terminated normally.
func (*Ebitengine) OnLaunched ¶
func (e *Ebitengine) OnLaunched(f func(context *guigui.Context))
OnLaunched sets a handler called when a guest has connected and started running.
func (*Ebitengine) OnTPSRequested ¶
func (e *Ebitengine) OnTPSRequested(f func(context *guigui.Context, tps int))
OnTPSRequested sets a handler called once per guest, after its first tick, with the ticks-per-second the guest's own game requests via ebiten.SetTPS (ebiten.SyncWithFPS resolved to the host's rate).
func (*Ebitengine) Session ¶
func (e *Ebitengine) Session() *vmhost.GuestSession
Session returns the underlying guest session for advanced control, or nil when no guest is running. The session must not be used after the guest exits or after Ebitengine.Close.
func (*Ebitengine) SetAudioEnabled ¶
func (e *Ebitengine) SetAudioEnabled(enabled bool)
SetAudioEnabled sets whether the audio the guest plays is played on the host. It is enabled by default. While disabled, the guest's audio sources are not consumed, so the guest observes no audio playback progress.
func (*Ebitengine) SetBinaryPath ¶
func (e *Ebitengine) SetBinaryPath(path string)
SetBinaryPath sets the path to the guest binary to run. The binary must be an Ebitengine program built with the "ebitenginevmguest" build tag, against the host's Ebitengine version. Changing the path launches the guest, and an empty path stops the running guest; setting the current value again has no effect.
func (*Ebitengine) SetCommandArgs ¶
func (e *Ebitengine) SetCommandArgs(args []string)
SetCommandArgs sets the command-line arguments the guest binary is launched with. They take effect at the next launch.
func (*Ebitengine) SetCommandEnv ¶
func (e *Ebitengine) SetCommandEnv(env []string)
SetCommandEnv sets additional environment variables for the guest process, each in "key=value" form, appended to the host's environment. They take effect at the next launch.
func (*Ebitengine) SetInputForwardingEnabled ¶
func (e *Ebitengine) SetInputForwardingEnabled(enabled bool)
SetInputForwardingEnabled sets whether the window's input is forwarded to the guest. It is enabled by default.
func (*Ebitengine) SetTPS ¶
func (e *Ebitengine) SetTPS(tps int)
SetTPS overrides the rate, in ticks per second, at which the guest is updated; 0 pauses it. Without SetTPS, the guest is paced at the rate its own game requests (reported by Ebitengine.OnTPSRequested).
func (*Ebitengine) Tick ¶
func (e *Ebitengine) Tick(context *guigui.Context, widgetBounds *guigui.WidgetBounds) error
type GuestNotConnectedError ¶
type GuestNotConnectedError struct {
// BinaryPath is the path of the launched binary.
BinaryPath string
// Err is the underlying error.
Err error
}
GuestNotConnectedError is reported to the OnError handler when the launched binary did not connect to the widget as a virtualization guest, typically because it is not an Ebitengine program built with the "ebitenginevmguest" build tag.
func (*GuestNotConnectedError) Error ¶
func (e *GuestNotConnectedError) Error() string
func (*GuestNotConnectedError) Unwrap ¶
func (e *GuestNotConnectedError) Unwrap() error
Source Files