scrap

README

go-scrap

go-scrap is a Go wrapper around the Rust scrap library. It supports reasonably fast capturing of raw screen pixels. The library dependency is only at compile time and statically compiled into the binary. It works on Windows, Linux, and macOS.

Building

Obtain the library, e.g. use go get with -d to not install yet:

go get -d github.com/cretz/go-scrap

Now, the Rust subproject scrap-sys must be compiled which is glue between the Go library and the Rust library. With Rust installed, this can is done by running the following in the scrap-sys/ subdirectory:

cargo build --release

Note: On Windows this must use the same gcc that Cgo would. Go does not support MSVC-compiled libraries yet. The easiest way to ensure this is with rustup by running rustup default stable-x86_64-pc-windows-gnu before building.

Note: On Linux this needs the X11 XCB libraries with the Shm and RandR extensions. On Ubuntu (18.04+ since RandR must be >= 1.12) they are packages named libx11-xcb-dev, libxcb-shm0-dev, and libxcb-randr0-dev respectively.

Now that the dependency is built, the library can be built. For example, take a screenshot:

go run ./example/screenshot

See the Godoc for more documentation and examples.

Documentation

Overview

Package scrap is a Go wrapper around the Rust https://github.com/quadrupleslap/scrap library. It supports reasonably fast capturing of raw screen pixels. The library dependency is only at compile time and statically compiled into the binary.

Since go-scrap statically links the Scrap library, the scrap-sys subdirectory Rust project must be built in release mode before compiling this project. See the README at https://github.com/cretz/go-scrap for more info.

Example (Screenshot)

// Get the main display
d, err := scrap.PrimaryDisplay()
panicIfErr(err)
// Create capturer for it
c, err := scrap.NewCapturer(d)
panicIfErr(err)
// Get an image, trying until one available
var img *scrap.FrameImage
for img == nil {
	img, _, err = c.FrameImage()
	panicIfErr(err)
}
// Save it to PNG
file, err := os.Create("screenshot.png")
panicIfErr(err)
defer file.Close()
panicIfErr(png.Encode(file, img))

Index

• func MakeDPIAware() error
• type Capturer
  • func NewCapturer(display *Display) (*Capturer, error)
  • func (c *Capturer) Frame() (pix []uint8, wouldBlock bool, err error)
  • func (c *Capturer) FrameImage() (img *FrameImage, wouldBlock bool, err error)
  • func (c *Capturer) Height() int
  • func (c *Capturer) Width() int
• type Display
  • func Displays() ([]*Display, error)
  • func GetDisplay(index int) (*Display, error)
  • func PrimaryDisplay() (*Display, error)
  • func (d *Display) Height() int
  • func (d *Display) Width() int
• type FrameImage
  • func (f *FrameImage) At(x, y int) color.Color
  • func (f *FrameImage) Bounds() image.Rectangle
  • func (f *FrameImage) ColorModel() color.Model
  • func (f *FrameImage) Detach()
  • func (f *FrameImage) Opaque() bool
  • func (f *FrameImage) PixOffset(x, y int) int
  • func (f *FrameImage) RGBAAt(x, y int) color.RGBA
  • func (f *FrameImage) ToRGBAImage() *image.RGBA

Examples

• Package (Screenshot)

Functions

func MakeDPIAware

func MakeDPIAware() error

MakeDPIAware enables the DPI aware setting for this process. This is currently only applicable for Windows. When DPI aware, the Width and Height of the Display and Capturer will return the full resolution for the screen instead of the scaled size.

Types

type Capturer

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

Capturer represents the capturing of a display.

func NewCapturer

func NewCapturer(display *Display) (*Capturer, error)

NewCapturer creates a capturer for the given display. Methods on the display can no longer be called after passed to this function.

func (*Capturer) Frame

func (c *Capturer) Frame() (pix []uint8, wouldBlock bool, err error)

Frame gets an individual frame for this captured display. If an error occurs, it is returned. If capturing the frame would be a blocking call, wouldBlock is set to true and the pix is empty. Otherwise, if the frame is captured, wouldBlock is false and the error is nil.

The resulting frame data is in packed BGRA format. This means that every pixel is represented by 4 values: blue, green, red, and alpha in that order. The "stride" is how many values are present in each row and is easily calculated as value count / height. For each row, there are at least 4 * width values for the BGRA representation, but there may be unused padding values at the end of the row.

When a frame slice is returned, it is owned by the Capturer. It very likely will be overwritten by the next call to Frame. It also will be disposed of when the capturer is. The general rule is not to mutate the slice and don't store/use it beyond the lifetime of this Capturer.

func (*Capturer) FrameImage

func (c *Capturer) FrameImage() (img *FrameImage, wouldBlock bool, err error)

FrameImage wraps the result of Frame into a FrameImage. It inherits the same ownership rules and restrictions of the Frame slice result.

func (*Capturer) Height

func (c *Capturer) Height() int

Height returns the height of this captured display.

func (*Capturer) Width

func (c *Capturer) Width() int

Width returns the width of this captured display.

type Display

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

Display represents a system display that can be captured. Once a display is used in NewCapturer, no other methods can be called on it.

func Displays

func Displays() ([]*Display, error)

Displays returns the set of known displays.

func GetDisplay

func GetDisplay(index int) (*Display, error)

GetDisplay returns a display on the specified index

func PrimaryDisplay

func PrimaryDisplay() (*Display, error)

PrimaryDisplay returns the primary display of the system or an error.

func (*Display) Height

func (d *Display) Height() int

Height gets the height of this display. This will panic if it is called after the display has been passed to NewCapturer.

func (*Display) Width

func (d *Display) Width() int

Width gets the width of this display. This will panic if it is called after the display has been passed to NewCapturer.

type FrameImage

type FrameImage struct {
	// Pix is the raw slice of packed BGRA pixels. For more information on the
	// format and ownership rules and restrictions, see Capturer.Frame. If you
	// run the Detach method, the owners rules and restrictions will no longer
	// apply.
	Pix []uint8
	// Stride is the number of values that make up each vertical row. It is
	// simply len(Pix) / Height. See Capturer.Frame for more info.
	Stride int
	// Width is the width of the image.
	Width int
	// Height is the height of the image.
	Height int
}

FrameImage is an implementation of image.Image. It carries the same ownership rules and restrictions as the Capturer.Frame slice result. If you run the Detach method, the owners rules and restrictions will no longer apply.

func (*FrameImage) At

func (f *FrameImage) At(x, y int) color.Color

At implements image.At.

func (*FrameImage) Bounds

func (f *FrameImage) Bounds() image.Rectangle

ColorModel implements image.Bounds.

func (*FrameImage) ColorModel

func (f *FrameImage) ColorModel() color.Model

ColorModel implements image.ColorModel.

func (*FrameImage) Detach

func (f *FrameImage) Detach()

Detach simply replaces Pix with a copy so the ownership rules and regulations of the underlying array no longer apply and this can be freely used without ensuring the Capturer that created it is still available.

func (*FrameImage) Opaque

func (f *FrameImage) Opaque() bool

Opaque always returns false as is present a performance optimization for algorithms such as PNG saving.

func (*FrameImage) PixOffset

func (f *FrameImage) PixOffset(x, y int) int

PixOffset gives the index of the Pix where the 4-value BGRA pixel is.

func (*FrameImage) RGBAAt

func (f *FrameImage) RGBAAt(x, y int) color.RGBA

RGBAAt returns the RGBA color at the given point.

func (*FrameImage) ToRGBAImage

func (f *FrameImage) ToRGBAImage() *image.RGBA

ToRGBAImage converts this image to a image.RGBA image. This has value because in some packages such as image/draw and image/png, image.RGBA values are given special fast-path treatment. Note, this copies the entire Pix slice, so the same ownership rules and restrictions on this image do not apply to the result.