wiregl

package
v0.0.0-...-1a87af9 Latest Latest
Warning

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

 Go to latest Published: May 15, 2024 License: CC0-1.0 Imports: 18 Imported by: 11

README

Package wiregl

import "gitlab.com/fospathi/wire/wiregl"

Go package wiregl rasterises 3D scenes composed of quadratic Bezier curves.

It uses an OpenGL version 4.5 context created with Go's GLFW and OpenGL bindings.

Dependencies

Package wiregl depends on GLFW. GLFW has its own dependencies; on Ubuntu for example you need the libgl1-mesa-dev and xorg-dev packages:

sudo apt install libgl1-mesa-dev xorg-dev

Documentation

Index

Constants

View Source 
const (
	// DefaultDensity is a sensible default value for a scene's density
	// variable.
	DefaultDensity uint32 = 125
)

Variables

This section is empty.

Functions

func IsOrthographic 

func IsOrthographic(m maf.OpenGLMat4) bool

IsOrthographic distinguishes between orthographic and perspective projections created by the functions in this file.

Types

type BinaryPixelData 

type BinaryPixelData []byte

BinaryPixelData is RGBA data and a width/height suffix.

func (BinaryPixelData) ToPixelData 

func (pix BinaryPixelData) ToPixelData() PixelData

ToPixelData with a newly allocated backing slice.

func (BinaryPixelData) WidthHeight 

func (pix BinaryPixelData) WidthHeight() (w int, h int)

WidthHeight of the image in pixels as given by the binary pixels' appendage.

type BinaryPixels 

type BinaryPixels []byte

BinaryPixels is one or two pixel data binary encodings. When two encodings are present, the encoding of the smaller size image is first.

Each pixel data binary encoding is made of: 

data-1, data-2, ..., data-(4*w*h), w-1, w-2, w-3, w-4, h-1, h-2, h-3, h-4
|--------------------------------|<-------------appendage-------------->|

* Raw RGBA data, either one or two bytes per channel: data-n are one or two byte data elements for 8 or 16 bit colour channels respectively.

* Followed by two four-byte-numbers which are the width and height of the image in pixels: w-n and h-n are the bytes, msb first, of four-byte integers giving the image width and height.

func (BinaryPixels) ToPixels 

func (pix BinaryPixels) ToPixels() Pixels

ToPixels with new backing slice(s).

type CPUStitcher 

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

CPUStitcher stitches a small size image into a full size image using multiple CPU cores.

func NewCPUStitcher 

func NewCPUStitcher(cores int) *CPUStitcher

NewCPUStitcher constructs a new CPUStitcher.

func (*CPUStitcher) Stitch 

func (s *CPUStitcher) Stitch(
	full, small PixelData, smallAlpha float64, bottom int, left int,
)

Stitch the small size image into the full size image.

type Context 

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

Context is an OpenGL rendering context.

func (*Context) Close 

func (cx *Context) Close()

Close terminates GLFW and then closes the main-thread-only channel.

To successfully close, the main-thread-only channel shall be executing received functions concurrently.

If the context was previously closed nothing happens.

func (*Context) Rasterise 

func (cx *Context) Rasterise(s Scene) Pixels

Rasterise the argument scene and return the pixels.

If the given scene has no vertex attribute data a standard empty scene is drawn in its place.

If the context was previously closed nothing happens.

func (*Context) Stitch 

func (cx *Context) Stitch(s GPUStitch) PixelData

Stitch the small image into the full image using the GPU.

type ContextSpec 

type ContextSpec struct {
	Debug   bool // Set as true to enable OpenGL debugging.
	Samples int  // Enable MSAA by specifying a non-zero number: usually 2, 4, or 8.
	ImageSizes
}

ContextSpec specifies the properties of a new context.

type DepictionBuilder 

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

A DepictionBuilder helps build the depiction part of a complete scene from smaller depictions which are local to a frame.

func NewDepictionBuilder 

func NewDepictionBuilder() *DepictionBuilder

NewDepictionBuilder constructs a new DepictionBuilder.

func (*DepictionBuilder) Add 

func (db *DepictionBuilder) Add(pic mech.Depiction, toEye maf.OpenGLMat4x3)

Add the given depiction to the depiction but with the given toEye transformation added to the vertices' attributes.

The vertices in the given depiction shall not already include a toEye transformation attribute.

Once the depiction builder is completed Add() is a no-op.

func (*DepictionBuilder) Complete 

func (db *DepictionBuilder) Complete() mech.Depiction

Complete the depiction and return the depiction with the toEye transformations now part of each vertices' attributes.

type GPUStitch 

type GPUStitch struct {
	// Bottom and left are used to position the bottom left corner of the source
	// image. They are axis aligned distances in units of pixels relative to the
	// bottom left corner of the full size destination image.
	Bottom, Left int
	// Full size destination image onto which the source image is blended.
	Full8  []uint8
	Full16 []uint16
	// Small size source image which is blended into the full size image.
	Small8  []uint8
	Small16 []uint16

	// SmallAlpha is effectively pre-multiplied with the alpha values of the
	// small image's pixels before the blend operation.
	SmallAlpha float64
	// contains filtered or unexported fields
}

GPUStitch the small image into the full size image using the GPU.

type ImageSizes 

type ImageSizes struct {
	DeepColour     bool // Set as true to enable 16 bit RGB framebuffer/image/screen components as opposed to the usual 8 bits.
	W, H           int  // The dimensions of the framebuffer in pixels.
	SmallW, SmallH int  // The dimensions of the smaller framebuffer in pixels.
	// contains filtered or unexported fields
}

type InitResult 

type InitResult struct {
	Context *Context
	Err     error
}

InitResult is either a rasterising context or an initialisation error.

type MainThread 

type MainThread <-chan func()

A MainThread type channel shall execute the functions it receives in the main thread only.

func NewContext 

func NewContext(spec ContextSpec) (MainThread, <-chan InitResult)

NewContext creates and initialises a new context according to the argument spec.

For initialisation to succeed the context's main-thread-only-channel needs to execute any received functions in the main thread concurrently.

The returned channel returns an error if initialisation fails in which case the context is nil. If initialisation fails glfw has already been terminated.

type PixelData 

type PixelData struct {
	// The dimensions of the framebuffer in units of pixels.
	Height, Width int
	// Data16, if not empty, contains the 16 bit RGBA values from each pixel
	// starting at the bottom left of the screen in row order from the lowest to
	// the highest row, left to right in each row.
	Data16 []uint16
	// Data8, if not empty, contains the 8 bit RGBA values from each pixel
	// starting at the bottom left of the screen in row order from the lowest to
	// the highest row, left to right in each row.
	Data8 []uint8
}

func (PixelData) AsBinary 

func (px PixelData) AsBinary() BinaryPixelData

AsBinary returns the data in binary pixels format which will possibly be using the same backing slice that the original data uses.

func (PixelData) BlankCopy 

func (px PixelData) BlankCopy() PixelData

BlankCopy of the receiver with a new backing slice and black transparent pixels.

func (PixelData) Copy 

func (px PixelData) Copy() PixelData

Copy the receiver using a new backing slice.

func (PixelData) Stitch 

func (px PixelData) Stitch(src PixelData, alpha float64, bottom, left int)

Stitch the given source image onto the receiver image using the CPU.

Before applying the Porter-Duff compositing algorithm the given alpha (in the range 0..1) is multiplied with the alpha of the src image. https://apoorvaj.io/alpha-compositing-opengl-blending-and-premultiplied-alpha/

The bottom left corner of the source image is offset from the bottom left corner of the receiver image by the given offsets.

func (PixelData) Stride 

func (px PixelData) Stride() int

Stride is the number uint8s per row when the data is interpreted as a uint8 slice.

func (PixelData) ToGamma 

func (px PixelData) ToGamma() PixelData

ToGamma encoded form, assuming the receiver pixel data is linear encoded.

func (PixelData) ToImage 

func (px PixelData) ToImage() image.Image

ToImage returns a new image from the data.

func (PixelData) ToUint8 

func (px PixelData) ToUint8() []uint8

ToUint8 returns a new copy of the data but interpreted as a slice of uint8.

func (PixelData) ToUint8WithFlip 

func (px PixelData) ToUint8WithFlip() []uint8

ToUint8WithFlip returns a new copy of the data but interpreted as a slice of uint8 and with the rows reflected from top to bottom around the central row.

type Pixels 

type Pixels struct {
	Full  PixelData
	Small PixelData
}

Pixels is the data from the GPU's framebuffer after a scene is rasterised.

The data is in either 16 or 8 bits per component format depending on the bits of the framebuffer. The small size data is optional but, if present, has the same bits per component as the full size data.

func (Pixels) ContainsSmall 

func (px Pixels) ContainsSmall() bool

func (Pixels) ToBinaryPixels 

func (px Pixels) ToBinaryPixels() BinaryPixels

type Projection 

type Projection struct {
	// Go from camera/eye space to clip space.
	Matrix maf.Mat4
	// Go from clip space to camera/eye space.
	Inverse maf.Mat4
}

Projection matrices to transform between camera/eye space and clip space.

func NewOrthographicProjection 

func NewOrthographicProjection(vb ViewingBox) Projection

NewOrthographicProjection constructs a new orthographic projection matrix that projects points in the given viewing box to 4D clip space coordinates.

In terms of eye space coordinates the viewing volume is centered around and occupies a portion of the negative Z-axis so that the camera appears to be looking down the negative Z-axis from the origin.

Assuming W=1 for a given eye space vector then the corresponding 4D clip space coordinates are already the normalised device coordinates (NDC) and no perspective divide is necessary, this follows since an orthographic projection is just a linear scaling from a box to a box. The usual Z mapping is reversed so that the near clipping plane is mapped to Z = 1 and the far clipping plane is mapped to Z = 0. Note that the camera space is right-handed whereas the projected-to NDC space is left-handed.

func NewPerspectiveProjection 

func NewPerspectiveProjection(vf ViewingFrustum) Projection

NewPerspectiveProjection constructs a new perspective projection matrix that projects points in the given pyramidal viewing frustum to 4D clip space coordinates.

In terms of eye space coordinates the viewing volume is centered around and occupies a portion of the negative Z-axis so that the camera appears to be looking down the negative Z-axis from the origin.

Applying a perspective division to the 4D clip space coordinates produces normalised device coordinates (NDC). The usual Z mapping is reversed so that the near clipping plane is mapped to Z = 1 and the far clipping plane is mapped to Z = 0. Note that the camera space is right-handed whereas the projected-to NDC space is left-handed.

type Scene 

type Scene struct {
	mech.Depiction
	Veneer mech.Depiction // The veneer appears above the main view onto the world.

	// The projection matrix which projects a position given in eye coordinates
	// to clip coordinates.
	EyeToClip       maf.OpenGLMat4
	VeneerEyeToClip maf.OpenGLMat4

	// Controls the number of divisions each Bezier curve is divided into
	// depending on how much screen space it occupies.
	//
	// The density is approximately how many divisions a single Bezier curve
	// would be divided into if it was a straight line that occupied the
	// screen's full height. Thus the 'units' of this density value might be
	// thought of as 'divisions per full-vertical-screen'.
	//
	// A higher value will result in possibly higher quality at the cost of
	// worse performance.
	Density uint32

	// ClearAlpha is the buffer clear colour opacity.
	ClearAlpha float64
	// ClearColour is the buffer clear colour.
	ClearColour mech.Colour

	// Small is true if the small size version of the scene should be generated
	// in addition to the full size version.
	Small bool

	// A collection of optional values which effect the quality of the
	// rasterisation that most users can safely ignore.
	Minutiae SceneMinutiae
}

A Scene is a collection of styled quadratic Beziers and any other values necessary for the GLSL program to rasterise the scene.

type SceneMinutiae 

type SceneMinutiae struct {
	// Set as true/non-zero to enable alternate colours that enable the
	// individual triangles that make up a curve/line to be seen.
	Debug uint32

	// The minimum number of divisions each quadratic Bezier curve will be
	// divided into regardless of the density value.
	MinDivs uint32

	OrthoPointEdge float32
	PerspPointEdge float32

	VeneerOrthoPointEdge float32
	VeneerPerspPointEdge float32
	// contains filtered or unexported fields
}

A SceneMinutiae specifies the values of other configurable GLSL shader variables which effect the visual quality of the scene rasterisation.

These values are optional and most users will not need to change any minutiae.

type ViewingBox 

type ViewingBox struct {
	// Magnitude of the distance from the camera to the far clipping plane.
	F float64
	// Magnitude of the distance from the camera to the near clipping plane.
	N float64
	// Width of the box.
	W float64
	// Height of the box.
	H float64
}

ViewingBox specifies a viewing volume for an orthographic projection.

Basically this defines a box shape with the implied camera outside the box and level with the near face centre.

type ViewingFrustum 

type ViewingFrustum struct {
	// Aspect is the ratio of the FOV in the x direction to the FOV in the y
	// direction, that is, width divided by height.
	Aspect float64
	// FOV is the field of view in the y direction given in radians.
	FOV float64
	// Magnitude of the distance from the camera to the far clipping plane.
	F float64
	// Magnitude of the distance from the camera to the near clipping plane.
	N float64
}

ViewingFrustum specifies a viewing volume for a perspective projection.

Basically this defines a truncated pyramidal shape with the implied camera at the implied tip of the pyramid pointing towards the pyramid base.

Source Files

View all Source files

Directories

Path Synopsis

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.