interface.go

package pixel

import "image/color"

// Target is something that can be drawn onto, such as a window, a canvas, and so on.
//
// You can notice, that there are no "drawing" methods in a Target. That's because all drawing
// happens indirectly through Triangles instance generated via MakeTriangles method.
//
// If no transforms are applied, the drawing area of a Target is the rectangle (-1, -1, +1, +1).
type Target interface {
	// MakeTriangles generates a specialized copy of the provided Triangles.
	//
	// When calling Draw method on the returned TargetTriangles, the TargetTriangles will be
	// drawn onto the Target that generated them.
	//
	// Note, that not every Target has to recognize all possible types of Triangles. Some may
	// only recognize TrianglesPosition and TrianglesColor and ignore all other properties (if
	// present) when making new TargetTriangles. This varies from Target to Target.
	MakeTriangles(Triangles) TargetTriangles

	// These are the most basic Target "adjustment" methods.
	SetPicture(*Picture)
	SetTransform(...Transform)
	SetMaskColor(color.Color)
}

// Triangles represents a list of vertices, where each three vertices form a triangle. (First,
// second and third is the first triangle, fourth, fifth and sixth is the second triangle, etc.)
type Triangles interface {
	// Len returns the number of vertices. The number of triangles is the number of vertices
	// divided by 3.
	Len() int

	// SetLen resizes Triangles to len vertices. If Triangles B were obtained by calling Slice
	// method on Triangles A, the relationship between A and B is undefined after calling SetLen
	// on either one of them.
	SetLen(len int)

	// Slice returns a sub-Triangles of this Triangles, covering vertices in range [i, j).
	//
	// If Triangles B were obtained by calling Slice(4, 9) on Triangles A, then A and B must
	// share the same underlying data. Modifying B must change the contents of A in range
	// [4, 9). The vertex with index 0 at B is the vertex with index 4 in A, and so on.
	//
	// Returned Triangles must have the same underlying type.
	Slice(i, j int) Triangles

	// Update copies vertex properties from the supplied Triangles into this Triangles.
	//
	// Properies not supported by these Triangles should be ignored. Properties not supported by
	// the supplied Triangles should be left untouched.
	//
	// The two Triangles need to have the same Len.
	Update(Triangles)

	// Copy creates an exact independent copy of this Triangles (with the same underlying type).
	Copy() Triangles
}

// TargetTriangles are Triangles generated by a Target with MakeTriangles method. They can be drawn
// onto that Target.
type TargetTriangles interface {
	Triangles

	// Draw draws Triangles onto an associated Target.
	Draw()
}

// TrianglesPosition specifies Triangles with Position property.
//
// Default value for a position is (0, 0).
type TrianglesPosition interface {
	Triangles
	Position(i int) Vec
}

// TrianglesColor specifies Triangles with Color property.
//
// Default value for a color is the white color.
type TrianglesColor interface {
	Triangles
	Color(i int) NRGBA
}

// TrianglesTexture specifies Triangles with Texture propery.
//
// Note that this represents texture coordinates, not an actual texture.
//
// Default value for a texture is (-1, -1), which means 'no texture'.
type TrianglesTexture interface {
	Triangles
	Texture(i int) Vec
}

// Drawer is something that can be drawn onto any Target.
type Drawer interface {
	Draw(Target)
}