imgui

README

Dear ImGui for Go

This library is a Go wrapper for Dear ImGui.

At the moment, this wrapper is a special-purpose wrapper for use within InkyBlackness. However, it is self-contained and can be used for other purposes as well.

This wrapper is

• hand-crafted, for Go
• documented
• versioned
• with a ported example using GLFW3 and OpenGL3.

Version philosophy

This library does not mirror the versions of the wrapped ImGui. The semantic versioning of this wrapper is defined as:

• Major changes: (Breaking) changes in API or behaviour. Typically done through changes in ImGui.
• Minor changes: Extensions in API. Typically done through small version increments of ImGui and/or exposing further features in a compatible way.
• Patch changes: Bug fixes - either in the wrapper or the wrapped ImGui, given that the API & behaviour remains the same.

At the moment, this library uses version 1.61 of ImGui.

Alternatives

Before this project was created, the following alternatives were considered - and ignored:

• kdrag0n/go-imgui. Reasons for dismissal:
  • Auto-generated bloat, which doesn't help
  • Old API (1.5x)
  • Does not compile (Issues 1 and 3)
  • Project appears to be abandoned
• Extrawurst/cimgui. Reasons for dismissal:
  • Old API (1.5x), 1.6x attempted, in-progress, could not be used
  • Appears to still semi-expose the C++ API, especially through the structures
  • Adding this adds another dependency

License

The project is available under the terms of the New BSD License (see LICENSE file). The licenses of included sources are stored in the _licenses folder.

Documentation

Index

• Variables
• func EndFrame()
• func IndexBufferLayout() (entrySize int)
• func NewFrame()
• func Render()
• func ShowDemoWindow(open *bool)
• func Version() string
• func VertexBufferLayout() (entrySize int, posOffset int, uvOffset int, colOffset int)
• type Alpha8Image
• type Context
  • func CreateContext(fontAtlas *FontAtlas) *Context
  • func CurrentContext() (*Context, error)
  • func (context *Context) Destroy()
  • func (context Context) SetCurrent() error
• type DrawCommand
  • func (cmd DrawCommand) CallUserCallback(list DrawList)
  • func (cmd DrawCommand) ClipRect() (rect Vec4)
  • func (cmd DrawCommand) ElementCount() int
  • func (cmd DrawCommand) HasUserCallback() bool
  • func (cmd DrawCommand) TextureID() TextureID
• type DrawData
  • func RenderedDrawData() DrawData
  • func (data DrawData) CommandLists() []DrawList
  • func (data DrawData) ScaleClipRects(scale Vec2)
  • func (data DrawData) Valid() bool
• type DrawList
  • func (list DrawList) Commands() []DrawCommand
  • func (list DrawList) IndexBuffer() (unsafe.Pointer, int)
  • func (list DrawList) VertexBuffer() (unsafe.Pointer, int)
• type FontAtlas
  • func (atlas FontAtlas) SetTextureID(id TextureID)
  • func (atlas FontAtlas) TextureDataAlpha8() *Alpha8Image
• type IO
  • func CurrentIO() IO
  • func (io IO) AddMouseWheelDelta(horizontal, vertical float32)
  • func (io IO) Fonts() FontAtlas
  • func (io IO) SetDeltaTime(value float32)
  • func (io IO) SetDisplaySize(value Vec2)
  • func (io IO) SetFontGlobalScale(value float32)
  • func (io IO) SetMouseButtonDown(index int, down bool)
  • func (io IO) SetMousePosition(value Vec2)
• type Style
  • func CurrentStyle() Style
  • func (style Style) ScaleAllSizes(scale float32)
• type TextureID
• type Vec2
• type Vec4

Variables

var ErrContextDestroyed = errors.New("context is destroyed")

ErrContextDestroyed is returned when trying to use an already destroyed context.

var ErrNoContext = errors.New("no current context")

ErrNoContext is used when no context is current.

Functions

func EndFrame

func EndFrame()

EndFrame ends the ImGui frame. Automatically called by Render(), so most likely don't need to ever call that yourself directly. If you don't need to render you may call EndFrame() but you'll have wasted CPU already. If you don't need to render, better to not create any imgui windows instead!

func IndexBufferLayout

func IndexBufferLayout() (entrySize int)

IndexBufferLayout returns the byte size necessary to select fields in an index buffer of DrawList.

func NewFrame

func NewFrame()

NewFrame starts a new ImGui frame, you can submit any command from this point until Render()/EndFrame().

func Render

func Render()

Render ends the ImGui frame, finalize the draw data. After this method, call RenderedDrawData to retrieve the draw commands and execute them.

func ShowDemoWindow

func ShowDemoWindow(open *bool)

ShowDemoWindow creates a demo/test window. Demonstrates most ImGui features. Call this to learn about the library! Try to make it always available in your application!

func Version

func Version() string

Version returns a version string e.g. "1.23".

func VertexBufferLayout

func VertexBufferLayout() (entrySize int, posOffset int, uvOffset int, colOffset int)

VertexBufferLayout returns the byte sizes necessary to select fields in a vertex buffer of a DrawList.

Types

type Alpha8Image

type Alpha8Image struct {
	Width, Height int
	Pixels        unsafe.Pointer
}

Alpha8Image represents a imgui backed 8-bit alpha value image.

type Context

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

Context specifies a scope of ImGui.

All contexts share a same FontAtlas by default. If you want different font atlas, you can create them and overwrite the CurrentIO.Fonts of an ImGui context.

func CreateContext

func CreateContext(fontAtlas *FontAtlas) *Context

CreateContext produces a new internal state scope. Passing nil for the fontAtlas creates a default font.

func CurrentContext

func CurrentContext() (*Context, error)

CurrentContext returns the currently active state scope. Returns ErrNoContext if no context is available.

func (*Context) Destroy

func (context *Context) Destroy()

Destroy removes the internal state scope. Trying to destroy an already destroyed context does nothing.

func (Context) SetCurrent

func (context Context) SetCurrent() error

SetCurrent activates this context as the currently active state scope.

type DrawCommand

type DrawCommand uintptr

DrawCommand describes one GPU call (or a callback).

func (DrawCommand) CallUserCallback

func (cmd DrawCommand) CallUserCallback(list DrawList)

CallUserCallback calls the user callback instead of rendering the vertices. ClipRect and TextureID will be set normally.

func (DrawCommand) ClipRect

func (cmd DrawCommand) ClipRect() (rect Vec4)

ClipRect defines the clipping rectangle (x1, y1, x2, y2).

func (DrawCommand) ElementCount

func (cmd DrawCommand) ElementCount() int

ElementCount is the number of indices (multiple of 3) to be rendered as triangles. Vertices are stored in the callee DrawList's VertexBuffer, indices in IndexBuffer.

func (DrawCommand) HasUserCallback

func (cmd DrawCommand) HasUserCallback() bool

HasUserCallback returns true if this handle command should be deferred.

func (DrawCommand) TextureID

func (cmd DrawCommand) TextureID() TextureID

TextureID is the user-provided texture ID. Set by user in FontAtlas.SetTextureID() for fonts or passed to Image*() functions. Ignore if never using images or multiple fonts atlas.

type DrawData

type DrawData uintptr

DrawData contains all draw data to render an ImGui frame.

func RenderedDrawData

func RenderedDrawData() DrawData

RenderedDrawData returns the created draw commands, which are valid after Render() and until the next call to NewFrame(). This is what you have to render.

func (DrawData) CommandLists

func (data DrawData) CommandLists() []DrawList

CommandLists is an array of DrawList to render. The DrawList are owned by the context and only pointed to from here.

func (DrawData) ScaleClipRects

func (data DrawData) ScaleClipRects(scale Vec2)

ScaleClipRects is a helper to scale the ClipRect field of each DrawCmd. Use if your final output buffer is at a different scale than ImGui expects, or if there is a difference between your window resolution and framebuffer resolution.

func (DrawData) Valid

func (data DrawData) Valid() bool

Valid indicates whether the structure is usable. It is valid only after Render() is called and before the next NewFrame() is called.

type DrawList

type DrawList uintptr

DrawList is a draw-command list. This is the low-level list of polygons that ImGui functions are filling. At the end of the frame, all command lists are passed to your render function for rendering.

Each ImGui window contains its own DrawList. You can use GetWindowDrawList() to access the current window draw list and draw custom primitives.

You can interleave normal ImGui calls and adding primitives to the current draw list.

All positions are generally in pixel coordinates (top-left at (0,0), bottom-right at io.DisplaySize), however you are totally free to apply whatever transformation matrix to want to the data (if you apply such transformation you'll want to apply it to ClipRect as well)

Important: Primitives are always added to the list and not culled (culling is done at higher-level by ImGui functions), if you use this API a lot consider coarse culling your drawn objects.

func (DrawList) Commands

func (list DrawList) Commands() []DrawCommand

Commands returns the list of draw commands. Typically 1 command = 1 GPU draw call, unless the command is a callback.

func (DrawList) IndexBuffer

func (list DrawList) IndexBuffer() (unsafe.Pointer, int)

IndexBuffer returns the handle information of the whole index buffer. Returned are the handle pointer and the total byte size. The buffer is a packed array of index entries, each consisting of an integer offset. To determine the byte size, call IndexBufferLayout.

func (DrawList) VertexBuffer

func (list DrawList) VertexBuffer() (unsafe.Pointer, int)

VertexBuffer returns the handle information of the whole vertex buffer. Returned are the handle pointer and the total byte size. The buffer is a packed array of vertex entries, each consisting of a 2D position vector, a 2D UV vector, and a 4-byte color value. To determine the byte size and offset values, call VertexBufferLayout.

type FontAtlas

type FontAtlas uintptr

FontAtlas contains runtime data for multiple fonts, bake multiple fonts into a single texture, TTF/OTF font loader

func (FontAtlas) SetTextureID

func (atlas FontAtlas) SetTextureID(id TextureID)

SetTextureID sets user data to refer to the texture once it has been uploaded to user's graphic systems. It is passed back to you during rendering via the DrawCommand.

func (FontAtlas) TextureDataAlpha8

func (atlas FontAtlas) TextureDataAlpha8() *Alpha8Image

TextureDataAlpha8 returns the image in 8-bit alpha values for the font atlas. The returned image is valid as long as the font atlas is.

type IO

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

IO is where your app communicate with ImGui. Access via CurrentIO(). Read 'Programmer guide' section in imgui.cpp file for general usage.

func CurrentIO

func CurrentIO() IO

CurrentIO returns access to the ImGui communication struct for the currently active context.

func (IO) AddMouseWheelDelta

func (io IO) AddMouseWheelDelta(horizontal, vertical float32)

AddMouseWheelDelta adds the given offsets to the current mouse wheel values. 1 vertical unit scrolls about 5 lines text. Most users don't have a mouse with an horizontal wheel, may not be provided by all back-ends.

func (IO) Fonts

func (io IO) Fonts() FontAtlas

Fonts returns the font atlas to load and assemble one or more fonts into a single tightly packed texture.

func (IO) SetDeltaTime

func (io IO) SetDeltaTime(value float32)

SetDeltaTime sets the time elapsed since last frame, in seconds.

func (IO) SetDisplaySize

func (io IO) SetDisplaySize(value Vec2)

SetDisplaySize sets the size in pixels.

func (IO) SetFontGlobalScale

func (io IO) SetFontGlobalScale(value float32)

SetFontGlobalScale sets the global scaling factor for all fonts.

func (IO) SetMouseButtonDown

func (io IO) SetMouseButtonDown(index int, down bool)

SetMouseButtonDown sets whether a specific mouse button is currently pressed. Mouse buttons: left, right, middle + extras. ImGui itself mostly only uses left button (BeginPopupContext** are using right button). Other buttons allows us to track if the mouse is being used by your application + available to user as a convenience via IsMouse** API.

func (IO) SetMousePosition

func (io IO) SetMousePosition(value Vec2)

SetMousePosition sets the mouse position, in pixels. Set to Vec2(-math.MaxFloat32,-mathMaxFloat32) if mouse is unavailable (on another screen, etc.)

type Style

type Style uintptr

Style describes the overall graphical representation of the user interface.

func CurrentStyle

func CurrentStyle() Style

CurrentStyle returns the UI Style for the currently active context.

func (Style) ScaleAllSizes

func (style Style) ScaleAllSizes(scale float32)

ScaleAllSizes applies a scaling factor to all sizes. To scale your entire UI (e.g. if you want your app to use High DPI or generally be DPI aware) you may use this helper function. Scaling the fonts is done separately and is up to you.

Important: This operation is lossy because all sizes are rounded to integer. If you need to change your scale multiples, call this over a freshly initialized style rather than scaling multiple times.

type TextureID

type TextureID uintptr

TextureID is a user data to identify a texture.

type Vec2

type Vec2 struct {
	X float32
	Y float32
}

Vec2 represents a two-dimensional vector.

type Vec4

type Vec4 struct {
	X float32
	Y float32
	Z float32
	W float32
}

Vec4 represents a four-dimensional vector.