Documentation
¶
Overview ¶
Package tsixel provides abstractions to work with SIXEL images in tcell.
Index ¶
- Constants
- Variables
- func CharPt(cols, rows int) image.Point
- type Animation
- func (img *Animation) Bounds() image.Rectangle
- func (img *Animation) BoundsPx() image.Rectangle
- func (img *Animation) RequestedBounds() image.Rectangle
- func (img *Animation) SetPosition(pos image.Point)
- func (img *Animation) SetSize(size image.Point)
- func (anim *Animation) Update(state DrawState) Frame
- type DrawState
- func (sz DrawState) CellSize() image.Point
- func (sz DrawState) PtInCells(pt image.Point) image.Point
- func (sz DrawState) PtInPixels(pt image.Point) image.Point
- func (sz DrawState) RectInCells(rect image.Rectangle) image.Rectangle
- func (sz DrawState) RectInPixels(rect image.Rectangle, round bool) image.Rectangle
- func (sz DrawState) RoundPt(pt image.Point) image.Point
- type Frame
- type Image
- func (img *Image) Bounds() image.Rectangle
- func (img *Image) BoundsPx() image.Rectangle
- func (img *Image) RequestedBounds() image.Rectangle
- func (img *Image) SetImage(newSrc image.Image)
- func (img *Image) SetPosition(pos image.Point)
- func (img *Image) SetSize(size image.Point)
- func (img *Image) Update(state DrawState) Frame
- type ImageOpts
- type Imager
- type ResizePipeline
- type ResizerJob
- type Screen
- type StaticImage
Constants ¶
const MaxResizeTime = 500 * time.Millisecond
MaxResizeTime is the duration to wait since the last resize to try resizing images again. It is only useful for images with resizing enabled.
const SIXELBufferSize = 40960 // 40KB
SIXELBufferSize is the size of the pre-allocated SIXEL buffer.
const SIXELHeight = 6 // px
SIXELHeight is the height of a single SIXEL strip.
According to Wikipedia, the free encyclopedia:
Sixel encodes images by breaking up the bitmap into a series of 6-pixel high horizontal strips.
This suggests that a SIXEL image's height can only be in multiples of 6. We must account this fact into consideration when resizing an image to not overflow a line when a cell's height is not in multiples of 6.
Variables ¶
var ( ErrNoDrawInterceptor = errors.New("screen does not support draw interceptors") ErrNoPixelDimensions = errors.New("screen does not support pixel dimensions") ErrNoDirectDrawer = errors.New("screen does not support direct drawer") // ErrNoExplicitSync is returned if a screen does not implement sync.Locker. // This is needed to explicitly sync our own internal state with the screen. ErrNoExplicitSync = errors.New("screen does not allow explicit syncing") )
Errors returned if the tcell screen does not have the capabilities for SIXEL.
Functions ¶
Types ¶
type Animation ¶
type Animation struct {
// contains filtered or unexported fields
}
func (*Animation) Bounds ¶
Bounds returns the bounds of the image relative to the top-left corner of the screen in units of cells. It is capped to the dimensions of the screen and may not be the actual bounds set. The function will return a zero-sized rectangle if the image is not yet initialized.
func (*Animation) RequestedBounds ¶
RequestedBounds calculates the bounds similarly to Bounds(), except the returned size is the one requested, not the one that's rescaled. This is useful for calculations relative to the corners of the screen.
func (*Animation) SetPosition ¶
SetPosition sets the top-left corner of the image in units of cells.
func (*Animation) SetSize ¶
SetSize sets the size of the image in units of cells. In other words, it sets the bottom-right corner of the image relatively to the top-left corner of the image. Note that this merely sets a hint; the actual image will never be larger than the screen OR the source image.
type DrawState ¶
type DrawState struct {
// Delegate is a callback to draw the screen at a later point. Calling this
// function without being in a goroutine will deadlock.
Delegate func()
// Time is the time the screen was drawn.
Time time.Time
Sync bool
Cells image.Point
Pixels image.Point
}
DrawState stores the screen size in two units: cells and pixels.
func (DrawState) PtInCells ¶
PtInCells converts a point which unit is in pixels to cells. The cells are rounded up (ceiling). If DrawState's cell size is a zero-value, then a zero point is returned.
func (DrawState) PtInPixels ¶
PtInPixels converts a point which unit is in cells to pixels.
func (DrawState) RectInCells ¶
RectInCells converts a rectangle which unit is in pixels into one in cells.
func (DrawState) RectInPixels ¶
RectInPixels converts a rectangle which unit is in cells into one in pixels. It accounts for the cell margins if round is true. The returned rectangle is guaranteed to have roughly the same aspect ratio.
type Frame ¶
type Frame struct {
// SIXEL is the byte slice to the raw SIXEL data of the image. The slice
// must only be changed when Update is called.
SIXEL []byte
// Bounds is the current image size and position on the screen in units of
// cells.
Bounds image.Rectangle
// MustUpdate, if true, will force the screen to redraw the SIXEL. The
// screen may still redraw the SIXEL if this is false.
MustUpdate bool
}
Frame is a representation of the image frame after an update.
type Image ¶
type Image struct {
// contains filtered or unexported fields
}
Image represents a SIXEL image. This image holds the source image and resizes it as needed. Each image has its own buffer and its associated encoder. To set its boundaries, use the SetBounds method. Note that the setter methods don't update the screen; the caller must manually synchronize it.
An image is not thread-safe, so it is not safe to share it across multiple screens, even with the same dimensions. This is because the synchronization of an image entirely depends on the screen it is on.
func (*Image) Bounds ¶
Bounds returns the bounds of the image relative to the top-left corner of the screen in units of cells. It is capped to the dimensions of the screen and may not be the actual bounds set. The function will return a zero-sized rectangle if the image is not yet initialized.
func (*Image) RequestedBounds ¶
RequestedBounds calculates the bounds similarly to Bounds(), except the returned size is the one requested, not the one that's rescaled. This is useful for calculations relative to the corners of the screen.
func (*Image) SetImage ¶
SetImage sets the new image source into the currnet image. The processing is done immediately, so the sizes returned by the methods are guaranteed to be updated.
func (*Image) SetPosition ¶
SetPosition sets the top-left corner of the image in units of cells.
type ImageOpts ¶
type ImageOpts struct {
// Scaler determines the scaler to use when scaling. Most of the time,
// ApproxBiLinear should be used.
//
// If Scaler is nil, then the image is never resized.
Scaler draw.Scaler
// KeepRatio, if true, will maintain the aspect ratio of the image when it's
// scaled down to fit the size. The image will be anchored on the top left.
KeepRatio bool
// Dither, if true, will apply dithering onto the image.
Dither bool
// NoRounding disables SIXEL rounding. This is useful if the image sizes
// are dynamically calculated manually and are expected to be consistent.
NoRounding bool
}
ImageOpts represents the options of a SIXEL image. It is meant to be constant to each image.
type Imager ¶
type Imager interface {
// UpdateSize updates the image's sizes. After this method is called, the
// image must be synchronized using the given state. If Update returns true,
// then the screen will redraw the SIXEL.
Update(state DrawState) Frame
}
Imager represents an image interface.
type ResizePipeline ¶
type ResizePipeline struct {
// contains filtered or unexported fields
}
func MainResizePipeline ¶
func MainResizePipeline() *ResizePipeline
func NewResizePipeline ¶
func NewResizePipeline() *ResizePipeline
func NewResizePipelineContext ¶
func NewResizePipelineContext(ctx context.Context) *ResizePipeline
NewResizePipelineContext creates a new resize pipeline with the given context. Once the context is canceled
func (*ResizePipeline) QueueJob ¶
func (pipeline *ResizePipeline) QueueJob(job ResizerJob)
QueueJob queues a resizing job. If a job with the same Imager is already queued, then its size is updated and the callback is preserved.
func (*ResizePipeline) Start ¶
func (pipeline *ResizePipeline) Start()
Start starts the pipeline. It does nothing if the pipeline is already stopped.
func (*ResizePipeline) Stop ¶
func (pipeline *ResizePipeline) Stop()
Stop stops the pipeline. It does nothing if the pipeline is already stopped.
type ResizerJob ¶
type ResizerJob struct {
Done func(ResizerJob, []byte)
SrcImg image.Image
Options ImageOpts
NewSize image.Point
}
ResizerJob describes a resizing job. The resize pipeline will batch up jobs, resize them asynchronously, and call the screen once it's done.
type Screen ¶
type Screen struct {
// contains filtered or unexported fields
}
Screen wraps around a tcell screen to manage and draw visible SIXEL images.
func WrapInitScreen ¶
WrapInitScreen wraps around an initialized tcell screen to create a new screen with an internal SIXEL state. It returns an error if the screen is not capable of outputting SIXEL. Note that this does not check if the terminal can draw SIXEL images. This behavior may change in the future.
func (*Screen) AddAnyImage ¶
AddAnyImage adds any image type onto the screen. It is a convenient wrapper around NewImage and AddImage.
func (*Screen) AddImage ¶
AddImage adds a SIXEL image onto the screen. This method will not redraw, so the caller should call Sync on the screen.
func (*Screen) RemoveImage ¶
RemoveImage removes an image from the screen. It does not redraw.
type StaticImage ¶
type StaticImage struct {
// contains filtered or unexported fields
}
StaticImage provides the most simple implementation to draw a SIXEL image. It provides no resizing.
func NewStaticImage ¶
func NewStaticImage(src image.Image) *StaticImage
NewStaticImage creates a new static image from the given image.
func NewStaticImageCustom ¶
func NewStaticImageCustom(src image.Image, dither bool, colors int) *StaticImage
NewStaticImageCustom creates a new static image with custom encoder parameters. Colors can be in-between 2 and 255.
func (*StaticImage) Bounds ¶
func (static *StaticImage) Bounds() image.Rectangle
Bounds returns the current bounds of the static image in cells. It works similarly to Image's Bounds.
func (*StaticImage) SetImage ¶
func (static *StaticImage) SetImage(src image.Image)
SetImage sets a new image. The image is automatically resized in the method, but a redraw will not be triggered.
func (*StaticImage) SetPosition ¶
func (static *StaticImage) SetPosition(pt image.Point)
SetPosition sets the image position.
func (*StaticImage) Update ¶
func (static *StaticImage) Update(state DrawState) Frame
Update returns the current SIXEL data. It
Source Files