gpudraw

README

GPUDraw: GPU version of Go image/draw compositing functionality

This package uses Alpha Compositing to render rectangular regions onto a render target, using the gpu package, consistent with the image/draw and experimental golang.org/x/image package in Go.

The Cogent Core GUI, along with other 2D-based GUI frameworks, uses a strategy of rendering to various rectangular sub-regions (in Cogent Core these are core.Scene objects) that are updated separately, and then the final result can be composited together into a single overall image that can be pasted onto the final window surface that the user sees.

This package supports these rectangular image region composition operations, via a simple render pipeline that just renders a rectangular shape with a texture. There is also a simple Fill pipeline that renders a single color into a rectangle.

The main API takes image.Image inputs directly, and follows the image/draw API as closely as possible (see draw.go):

Copy(dp image.Point, src image.Image, sr image.Rectangle, op draw.Op)

Scale(dr image.Rectangle, src image.Image, sr image.Rectangle, op draw.Op)

Transform(xform math32.Matrix3, src image.Image, sr image.Rectangle, op draw.Op)

// Copy also alls this with image.Uniform image input
Fill(clr color.Color, dr image.Rectangle, op draw.Op)

Calls to these functions must be surrounded by Start and End calls: internally it accumulates everything after the Start call, and actually does the render at the End.

Use / Used interface

There are also *Used versions of the above methods that operate on the current image that has been setup using the Use* methods. These allow the system to use GPU-internal texture sources for greater efficiency where relevant. These methods also support flipping the Y axis and other more advanced features (e.g., rotation in the ScaleUsed case).

Implementation: Var map

Group: -2 Vertex
    Role: Vertex
        Var: 0:	Pos	Float32Vector2	(size: 8)	Values: 1
    Role: Index
        Var: 0:	Index	Uint16	(size: 2)	Values: 1
Group: 0 Matrix
    Role: Uniform
        Var: 0:	Matrix	Struct	(size: 128)	Values: 1
Group: 1 Texture
    Role: SampledTexture
        Var: 0:	TexSampler	TextureRGBA32	(size: 4)	Values: 16

Documentation

Index

• Constants
• Variables
• type AsGPUDrawer
• type Drawer
  • func NewDrawer(gp *gpu.GPU, rd gpu.Renderer) *Drawer
  • func (dw *Drawer) AsGPUDrawer() *Drawer
  • func (dw *Drawer) ConfigPipeline(pl *gpu.GraphicsPipeline, blend bool)
  • func (dw *Drawer) Copy(dp image.Point, src image.Image, sr image.Rectangle, op draw.Op, ...)
  • func (dw *Drawer) CopyUsed(dp image.Point, sr image.Rectangle, op draw.Op, flipY bool)
  • func (dw *Drawer) DestBounds() image.Rectangle
  • func (dw *Drawer) DestSize() image.Point
  • func (dw *Drawer) End()
  • func (dw *Drawer) Fill(clr color.Color, dr image.Rectangle, op draw.Op)
  • func (dw *Drawer) Release()
  • func (dw *Drawer) Renderer() any
  • func (dw *Drawer) Scale(dr image.Rectangle, src image.Image, sr image.Rectangle, rotateDeg float32, ...)
  • func (dw *Drawer) ScaleUsed(dr image.Rectangle, sr image.Rectangle, rotateDeg float32, op draw.Op, ...)
  • func (dw *Drawer) Start()
  • func (dw *Drawer) Transform(xform math32.Matrix3, src image.Image, sr image.Rectangle, op draw.Op, ...)
  • func (dw *Drawer) TransformUsed(xform math32.Matrix3, sr image.Rectangle, op draw.Op, flipY bool)
  • func (dw *Drawer) UseGoImage(img image.Image, unchanged bool)
  • func (dw *Drawer) UseTexture(tx *gpu.Texture)

Constants

const (
	// Unchanged should be used for the unchanged argument in drawer calls,
	// when the caller knows that the image is unchanged.
	Unchanged = true

	// Changed should be used for the unchanged argument to drawer calls,
	// when the image has changed since last time or its status is unknown
	Changed
)

const (
	// Over = alpha blend with existing content.
	Over = draw.Over

	// Src = copy source to destination with no blending ("blit").
	Src = draw.Src
)

These draw.Op constants are provided so that users of this package don't have to explicitly import "image/draw". We also add the fill operations.

Variables

var AllocChunk = 16

AllocChunk is number of images / matrix elements to allocate at a time, to reduce number of reallocations. Should be set to the rough scale of number of items expected.

Types

type AsGPUDrawer

type AsGPUDrawer interface {

	// AsGPUDrawer returns the drawer as a [Drawer].
	// It may return nil if it cannot be used as a [Drawer].
	AsGPUDrawer() *Drawer
}

AsGPUDrawer represents a type that can be used as a Drawer.

type Drawer

type Drawer struct {
	// drawing system
	System *gpu.GraphicsSystem

	// use Lock, Unlock on Drawer for all impl routines
	sync.Mutex
	// contains filtered or unexported fields
}

Drawer is the overall GPUDraw implementation, which draws Textures or Fills solid colors to a render target. A sequence of drawing operations is programmed for each render pass, between Start and End calls, which is then uploaded and performed in one GPU render pass, according to the recorded order of operations.

func NewDrawer

func NewDrawer(gp *gpu.GPU, rd gpu.Renderer) *Drawer

NewDrawer returns a new Drawer configured for rendering to given Renderer.

func (*Drawer) AsGPUDrawer

func (dw *Drawer) AsGPUDrawer() *Drawer

AsGPUDrawer implements AsGPUDrawer.

func (*Drawer) ConfigPipeline

func (dw *Drawer) ConfigPipeline(pl *gpu.GraphicsPipeline, blend bool)

ConfigPipeline configures graphics settings on the pipeline

func (*Drawer) Copy

func (dw *Drawer) Copy(dp image.Point, src image.Image, sr image.Rectangle, op draw.Op, unchanged bool)

Copy copies the given Go source image to the render target, with the same semantics as golang.org/x/image/draw.Copy, with the destination implicit in the Drawer target.

• Must have called Start first!
• dp is the destination point.
• src is the source image. If an image.Uniform, fast Fill is done.
• sr is the source region, if zero full src is used; must have for Uniform.
• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing.
• unchanged should be true if caller knows that this image is unchanged from the last time it was used -- saves re-uploading to gpu.

func (*Drawer) CopyUsed

func (dw *Drawer) CopyUsed(dp image.Point, sr image.Rectangle, op draw.Op, flipY bool)

CopyUsed copies the current Use* texture to render target. Must have called Start and a Use* method first!

• dp is the destination point.
• src is the source image. If an image.Uniform, fast Fill is done.
• sr is the source region, if zero full src is used.
• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing.
• flipY = flipY axis when drawing this image.

func (*Drawer) DestBounds

func (dw *Drawer) DestBounds() image.Rectangle

DestBounds returns the bounds of the render destination

func (*Drawer) DestSize

func (dw *Drawer) DestSize() image.Point

DestSize returns the size of the render destination

func (*Drawer) End

func (dw *Drawer) End()

End ends image drawing rendering process on render target.

func (*Drawer) Fill

func (dw *Drawer) Fill(clr color.Color, dr image.Rectangle, op draw.Op)

Fill fills given color to render target, to given destination region dr.

• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing

func (*Drawer) Release

func (dw *Drawer) Release()

func (*Drawer) Renderer

func (dw *Drawer) Renderer() any

func (*Drawer) Scale

func (dw *Drawer) Scale(dr image.Rectangle, src image.Image, sr image.Rectangle, rotateDeg float32, op draw.Op, unchanged bool)

Scale copies the given Go source image to the render target, scaling the region defined by src and sr to the destination such that sr in src-space is mapped to dr in dst-space, and applying an optional rotation of the source image. Has the same general semantics as golang.org/x/image/draw.Scale, with the destination implicit in the Drawer target. If src image is an

• Must have called Start first!
• dr is the destination rectangle; if zero uses full dest image.
• src is the source image. Uniform does not work (or make sense) here.
• sr is the source region, if zero full src is used; must have for Uniform.
• rotateDeg = rotation degrees to apply in the mapping: 90 = left, -90 = right, 180 = invert.
• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing.
• unchanged should be true if caller knows that this image is unchanged from the last time it was used -- saves re-uploading to gpu.

func (*Drawer) ScaleUsed

func (dw *Drawer) ScaleUsed(dr image.Rectangle, sr image.Rectangle, rotateDeg float32, op draw.Op, flipY bool)

ScaleUsed copies the current Use* texture to render target, scaling the region defined by src and sr to the destination such that sr in src-space is mapped to dr in dst-space. Must have called Start and a Use* method first!

• dr is the destination rectangle; if zero uses full dest image.
• sr is the source region; if zero uses full src image.
• rotateDeg = rotation degrees to apply in the mapping: 90 = left, -90 = right, 180 = invert.
• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing.
• flipY = flipY axis when drawing this image.

func (*Drawer) Start

func (dw *Drawer) Start()

Start starts recording a sequence of draw / fill actions, which will be performed on the GPU at End(). This must be called prior to any Drawer operations.

func (*Drawer) Transform

func (dw *Drawer) Transform(xform math32.Matrix3, src image.Image, sr image.Rectangle, op draw.Op, unchanged bool)

Transform copies the given Go source image to the render target, with the same semantics as golang.org/x/image/draw.Transform, with the destination implicit in the Drawer target.

• xform is the transform mapping source to destination coordinates.
• src is the source image. Uniform does not work (or make sense) here.
• sr is the source region, if zero full src is used; must have for Uniform.
• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing.
• unchanged should be true if caller knows that this image is unchanged from the last time it was used -- saves re-uploading to gpu.

func (*Drawer) TransformUsed

func (dw *Drawer) TransformUsed(xform math32.Matrix3, sr image.Rectangle, op draw.Op, flipY bool)

TransformUsed draws the current Use* texture to render target Must have called Start and a Use* method first!

• xform is the transform mapping source to destination coordinates.
• sr is the source region; if zero uses full src image.
• op is the drawing operation: Src = copy source directly (blit), Over = alpha blend with existing.

func (*Drawer) UseGoImage

func (dw *Drawer) UseGoImage(img image.Image, unchanged bool)

UseGoImage uses the given Go image.Image as the source image for the next Draw operation. unchanged is a hint from the source about whether the image is unchanged from last use, in which case it does not need to be re-uploaded (if found).

func (*Drawer) UseTexture

func (dw *Drawer) UseTexture(tx *gpu.Texture)

UseTexture uses the given GPU resident Texture as the source image for the next Draw operation.