Documentation
¶
Overview ¶
Package terminalimage writes native images, image fonts, or color-block previews.
Index ¶
- Variables
- func CellSize(fd uintptr) (width, height int)
- func DecodePreview(ctx context.Context, source io.Reader) (image.Image, error)
- func FontPreviewColumns(bounds image.Rectangle, columns, rows int) int
- func FontSupported() bool
- func PrepareInteractiveImageOutput(ctx context.Context, out io.Writer) (context.Context, func() error)
- func PrepareNativeImageOutput(ctx context.Context, out io.Writer) (context.Context, func() error)
- func PrepareRows(ctx context.Context, out *os.File, img image.Image, protocol string, ...) ([]string, error)
- func ReadSaved(ctx context.Context, path string) (image.Image, error)
- func ReadSavedMatching(ctx context.Context, path string, expected [sha256.Size]byte) (image.Image, error)
- func RowColumns(row string) int
- func RunKittyOutputHelper(args []string) (bool, error)
- func Write(ctx context.Context, w io.Writer, img image.Image, protocol string, ...) error
- func WriteControl(ctx context.Context, out io.Writer, control string) error
- func WriteFrame(ctx context.Context, out io.Writer, frame string, protocol string) error
- func WriteProgress(ctx context.Context, w io.Writer, img image.Image, protocol string, ...) error
- type CanceledOutputError
- type FontError
Constants ¶
This section is empty.
Variables ¶
var ErrSavedImageChanged = errors.New("saved image contents changed before preview")
ErrSavedImageChanged means the preview bytes differ from the completed save.
Functions ¶
func CellSize ¶ added in v1.28.0
CellSize reads the text cell dimensions from existing window metadata without sending terminal queries or consuming input. Only their ratio is significant. When dimensions are missing or ambiguous, use the conventional 1-by-2 estimate.
func DecodePreview ¶ added in v1.28.0
DecodePreview decodes temporary image bytes using the same optional-preview limits as saved images. It never writes a file or limits the API response.
func FontPreviewColumns ¶ added in v1.28.0
FontPreviewColumns also fits the gallery's immutable row allocation. Gallery placements assume cells twice as tall as wide, regardless of the font; the bitmap itself still preserves proportions within those allocated cells.
func FontSupported ¶
func FontSupported() bool
FontSupported identifies a local Apple Terminal session. Font registration and tab control must never target a remote shell or a terminal multiplexer.
func PrepareInteractiveImageOutput ¶ added in v1.39.0
func PrepareInteractiveImageOutput(ctx context.Context, out io.Writer) (context.Context, func() error)
PrepareInteractiveImageOutput gives directly owned helpers private sessions. Group signals cancel the parent, while a prepared helper remains available to restore the interactive terminal modes. The existing lifeline still stops helpers if their parent dies unexpectedly.
func PrepareNativeImageOutput ¶ added in v1.38.0
PrepareNativeImageOutput binds the writer before a command reads input or waits for the API. Preparation errors are deferred until a preview actually uses it. Close reports helper failures only after use, preserving non-preview paths. The existing Kitty worker also carries VS Code and Konsole IIP bytes without interpreting them.
func PrepareRows ¶ added in v1.40.3
func PrepareRows(ctx context.Context, out *os.File, img image.Image, protocol string, columns int) ([]string, error)
PrepareRows retains independently positioned preview rows for a scrolling viewport. Font preparation preserves the existing explicit opt-in policy. Native rows retain source pixels and request exactly one terminal row.
func ReadSaved ¶
ReadSaved decodes an optional preview. These limits protect terminal rendering; they never limit the API response or change the original saved image.
func ReadSavedMatching ¶
func ReadSavedMatching(ctx context.Context, path string, expected [sha256.Size]byte) (image.Image, error)
ReadSavedMatching previews only the response bytes recorded by a prior save. Both identity checks and decoding apply to the same bounded snapshot, so a replaced path or a rewritten open file cannot substitute another image.
func RowColumns ¶ added in v1.40.3
RowColumns measures prepared text or the explicit cell width of a native row. Unknown native dimensions are unsafe to replay inside a bounded panel.
func RunKittyOutputHelper ¶ added in v1.36.0
RunKittyOutputHelper handles only the private resident writer invocation. The process itself owns output. Parent death exits it even during a blocked write, and the parent can always kill and reap its direct child on failure.
func Write ¶
Write displays img at the requested width in terminal cells, preserving its aspect ratio. iterm-auto delegates sizing to the terminal's live viewport. The caller selects the protocol and supplies a terminal writer.
func WriteControl ¶ added in v1.39.0
WriteControl sends caller-owned terminal controls through the same cancellable output binding as native images. Callers must not pass untrusted content.
func WriteFrame ¶ added in v1.40.3
WriteFrame preserves native graphics reset handling for a caller-owned view. Text and image rows must already contain escaped text or prepared image bytes.
func WriteProgress ¶ added in v1.28.0
func WriteProgress(ctx context.Context, w io.Writer, img image.Image, protocol string, columns int) error
WriteProgress uses the same renderer as a final image, while leaving capacity for one final font preview. Sharp progress keeps immutable private cache files because changing their glyphs would change earlier terminal scrollback.
Types ¶
type CanceledOutputError ¶ added in v1.39.0
type CanceledOutputError struct {
// contains filtered or unexported fields
}
CanceledOutputError retains the transport errors from a deliberately canceled interactive transfer. It does not include the subsequent terminal reset.
func (*CanceledOutputError) Error ¶ added in v1.39.0
func (e *CanceledOutputError) Error() string
func (*CanceledOutputError) Unwrap ¶ added in v1.39.0
func (e *CanceledOutputError) Unwrap() error
Source Files
¶
- cell_geometry.go
- control.go
- font.go
- font_cleanup.go
- font_geometry.go
- image.go
- iterm.go
- kitty_framed_output_linux.go
- kitty_framed_output_unix.go
- kitty_interrupt_linux.go
- kitty_output_helper_unix.go
- kitty_output_session_unix.go
- kitty_transport_unix.go
- kitty_view.go
- rows.go
- saved_file.go
- saved_file_unix.go
- viewport_unix.go