Documentation
¶
Overview ¶
Package image provides hardware-accelerated Image primitive which can be manipulated in real-time using Pixel-Perfect API.
Instance of the Image should be created either by directly using a New function or using an external factory function such as glfw.OpenGL.NewImage:
image := images.New(2, 2, acceleratedImage)
Image can be manipulated using Selection:
wholeSelection := image.WholeImageSelection() wholeSelection.SetColor(0, 1, colornames.White)
Index ¶
- Variables
- type AcceleratedCommand
- type AcceleratedImage
- type AcceleratedImageLocation
- type AcceleratedImageSelection
- type Color
- type Image
- type Lines
- type Selection
- func (s Selection) Color(localX, localY int) Color
- func (s Selection) Height() int
- func (s Selection) Image() *Image
- func (s Selection) ImageX() int
- func (s Selection) ImageY() int
- func (s Selection) Lines() Lines
- func (s Selection) Modify(command AcceleratedCommand, selections ...Selection)
- func (s Selection) Selection(localX, localY int) Selection
- func (s Selection) SetColor(localX, localY int, color Color)
- func (s Selection) Width() int
- func (s Selection) WithSize(width, height int) Selection
Constants ¶
This section is empty.
Variables ¶
var Transparent = RGBA(0, 0, 0, 0)
Transparent is a special color where each component is zero (including alpha)
Functions ¶
This section is empty.
Types ¶
type AcceleratedCommand ¶
type AcceleratedCommand interface {
// Run should put the results into the output selection of AcceleratedImage,
// so that next time AcceleratedImage.Download is called modified pixels are
// downloaded.
//
// Run may return error when output or selections cannot be used. Usually
// the reason for that is they were not created in a given context (such
// as OpenGL context).
//
// Implementations must not retain selections.
Run(output AcceleratedImageSelection, selections []AcceleratedImageSelection)
}
AcceleratedCommand is a command executed externally (outside the CPU).
type AcceleratedImage ¶
type AcceleratedImage interface {
// Upload transfers pixels from RAM to external memory (such as VRAM).
//
// Pixels must have pixel colors sorted by coordinates.
// Pixels are send for last line first, from left to right.
// Pixels slice holds all image pixels and therefore must have size width*height
//
// Implementations must not retain pixels slice and make a copy instead.
Upload(pixels []Color)
// Download transfers pixels from external memory (such as VRAM) to RAM.
//
// Output will have pixel colors sorted by coordinates.
// Pixels are send for last line first, from left to right.
// Output must be of size width*height.
//
// If the image has not been uploaded before then Download should fill
// output with Transparent color.
//
// Implementations must not retain output.
Download(output []Color)
// Width returns the number of pixels in a row.
Width() int
// Height returns the number of pixels in a column.
Height() int
// Delete cleans resources, usually pixels stored in external memory (such as VRAM).
// After AcceleratedImage is deleted it cannot be used anymore.
Delete()
}
AcceleratedImage is an image processed by external device (outside the CPU). The mentioned device can be a video card.
type AcceleratedImageLocation ¶
type AcceleratedImageLocation struct {
X, Y, Width, Height int
}
AcceleratedImageLocation is a location of a AcceleratedImage
type AcceleratedImageSelection ¶
type AcceleratedImageSelection struct {
Location AcceleratedImageLocation
Image AcceleratedImage
}
AcceleratedImageSelection is same for AcceleratedImage as Selection for *Image
type Color ¶
type Color struct {
// contains filtered or unexported fields
}
Color represents pixel color using 4 components: Red, Green, Black and Alpha. Red, Green and Blue components are premultiplied by alpha.
Color is immutable struct. Changing the color means creating a new instance.
func NRGBA ¶
NRGBA creates Color using RGB components not premultiplied by alpha (aka straight alpha). Straight colors are being used by programs such as Aseprite.
func RGB ¶
RGB creates Color using three components: red, green and blue. The color will be fully opaque (alpha=255)
func RGBAi ¶
RGBAi creates Color using components given as integer values. All values are clamped to [0-255] range.
type Image ¶
type Image struct {
// contains filtered or unexported fields
}
Image is a 2D picture composed of pixels each having a specific color. Image is using 2 coordinates: X and Y to specify the position of a pixel. The origin (0,0) is at the top-left corner of the image.
The cost of creating an Image is huge therefore new images should be created sporadically, ideally when the application starts.
func New ¶
func New(acceleratedImage AcceleratedImage) *Image
New creates an Image with same size as provided AcceleratedImage. Will panic if AcceleratedImage is nil or width and height of AcceleratedImage are negative
func (*Image) Delete ¶
func (i *Image) Delete()
Delete cleans resources allocated outside the Go heap. This method must be called if you are going to create a number of short-lived images.
func (*Image) Selection ¶
Selection creates an area pointing to the image at a given starting position (x and y). The position must be a top left corner of the selection. Both x and y can be negative, meaning that selection starts outside the image.
func (*Image) Upload ¶
func (i *Image) Upload()
Upload uploads all image pixels to associated AcceleratedImage. This method should be called rarely. Image pixels are uploaded automatically when needed.
DEPRECATED - this method will be removed in next release
func (*Image) WholeImageSelection ¶
WholeImageSelection make selection of entire image.
type Lines ¶
type Lines struct {
// contains filtered or unexported fields
}
Lines represents lines of pixels created from Selection, which can be used for efficient pixel processing. It was created solely for performance reasons.
func (Lines) LineForRead ¶
LineForRead returns pixels in a given line which can be used for efficient pixel processing.
You may only read from returned slice. Trying to update the returned slice will not generate panic, but modified pixels will not be uploaded to AcceleratedImage when Modify is run. If you want to update the line contents please use LineForWrite instead.
Please note that returned slice behaves differently than Selection. Line contains only real pixels and trying to access out-of-bounds pixels generates panic. Therefore the len of returned slice may be lower than Selection width. The starting offset can be read by executing Lines.XOffset().
It is not safe to retain returned slice for future use. The image can be modified by AcceleratedCommand and changes will not be immediately reflected in a slice.
func (Lines) LineForWrite ¶
LineForWrite returns pixels in a given line which can be used for efficient pixel processing.
You may read and write to returned slice.
Please note that returned slice behaves differently than Selection. Line contains only real pixels and trying to access out-of-bounds pixels generates panic. Therefore the len of returned slice can be lower than Selection width. The starting offset can be read by executing Lines.XOffset().
It is not safe to retain returned slice for future use. The image can be modified by AcceleratedCommand and changes will not be immediately reflected in a slice.
type Selection ¶
type Selection struct {
// contains filtered or unexported fields
}
Selection points to a specific area of the image. It has a starting position (top-left corner) and optional size. Most Selection methods - such as Color, SetColor and Selection use local coordinates as parameters. Top-left corner of selection has (0,0) local coordinates.
func (Selection) Color ¶
Color returns the color of the pixel at a specific position. Passed coordinates are local, which means that the top-left corner of selection is equivalent to localX=0, localY=0. Negative coordinates are supported. If pixel is outside the image boundaries then transparent color is returned. It is also possible to get the color outside the selection.
func (Selection) Modify ¶
func (s Selection) Modify(command AcceleratedCommand, selections ...Selection)
Modify runs the AcceleratedCommand and put results into the Selection. This method ensures that all passed selections are uploaded before the command is called. Selections get converted into AcceleratedImageSelection and passed to the command.Run.
func (Selection) Selection ¶
Selection makes a new selection using the coordinates of existing selection. Passed coordinates are local, which means that the top-left corner of existing selection is equivalent to localX=0, localY=0. Both coordinates can be negative, meaning that selection starts outside the original selection.
func (Selection) SetColor ¶
SetColor sets the color of the pixel at specific position. Passed coordinates are local, which means that the top-left corner of selection is equivalent to localX=0, localY=0. Negative coordinates are supported. If pixel is outside the image boundaries then nothing happens. It is possible to set the color outside the selection.
Source Files
Directories