Documentation
¶
Overview ¶
Package xgif quantizes, normalizes, and encodes rendered animation frames as GIF. Frames are centered on a common canvas within GIF's 256-color limit, with one palette entry normalized to the white canvas background.
Index ¶
- Constants
- Variables
- func AnimateCenteredOpaquePalettedImagesWithLimit(ctx context.Context, images []*image.Paletted, width, height, intervalMs int, ...) ([]byte, error)
- func AnimatePalettedImagesWithLimit(ctx context.Context, images []*image.Paletted, animIntervalMs int, ...) ([]byte, error)
- func AnimationFrameCount(durationMs int) (int, error)
- func AnimationFrameTime(frameIndex int) (time.Duration, error)
- func NormalizePalettedImage(ctx context.Context, img *image.Paletted, width, height int) (*image.Paletted, error)
- func QuantizeImage(ctx context.Context, img image.Image) (*image.Paletted, error)
- func Validate(gifBytes []byte, nFrames int, intervalMS int) errordeprecated
- type OpaquePalettedAnimationEncoder
- type OpaqueQuantizationWorkspace
Constants ¶
const INFINITE_LOOP = 0
Variables ¶
var BG_COLOR = color.White
Functions ¶
func AnimateCenteredOpaquePalettedImagesWithLimit ¶ added in v0.9.0
func AnimateCenteredOpaquePalettedImagesWithLimit(ctx context.Context, images []*image.Paletted, width, height, intervalMs int, maxBytes int64) ([]byte, error)
AnimateCenteredOpaquePalettedImagesWithLimit encodes fully opaque paletted frames on a shared white canvas without allocating a full canvas-sized pixel buffer for frames that need centering. Input frames may have non-zero origins and different dimensions, but none may exceed the requested canvas.
The opaque contract permits the encoder to share one global color table when frame palettes match. Callers that need transparent GIF semantics must use AnimatePalettedImagesWithLimit, whose per-frame local color tables preserve transparent-frame metadata and deterministic byte compatibility.
func AnimatePalettedImagesWithLimit ¶ added in v0.9.0
func AnimatePalettedImagesWithLimit(ctx context.Context, images []*image.Paletted, animIntervalMs int, maxBytes int64) ([]byte, error)
AnimatePalettedImagesWithLimit encodes already-normalized paletted frames without quantizing or copying them. Every frame must have identical zero-based bounds and a valid GIF palette. The animation loops forever, and frame delays use the same schedule as animateImagesWithConcurrency. maxBytes must be positive. Encoding rejects a write before the accumulated output length can exceed the limit.
func AnimationFrameCount ¶ added in v0.9.0
AnimationFrameCount returns the number of 30 fps samples used for one positive board interval. The renderer and encoder share this schedule so fractional intervals use identical rounding rules.
func AnimationFrameTime ¶ added in v0.9.0
AnimationFrameTime returns the timestamp for a zero-based sample in the shared 30 fps capture schedule.
func NormalizePalettedImage ¶ added in v0.9.0
func NormalizePalettedImage(ctx context.Context, img *image.Paletted, width, height int) (*image.Paletted, error)
NormalizePalettedImage centers img on a width-by-height white canvas while preserving its indexed pixels. No color quantization is performed. When img already has zero-based width-by-height bounds, its palette is updated and img itself is returned so the common path does not allocate a second full pixel buffer. Otherwise the returned frame owns its pixel buffer and palette. Callers must impose appropriate canvas and aggregate pixel limits.
func QuantizeImage ¶ added in v0.9.0
QuantizeImage converts one rendered image to the indexed-color form required by GIF. It deliberately does not normalize the frame to an animation canvas; callers that render frames serially can release the larger source image as soon as this function returns, retain the smaller paletted result, and call NormalizePalettedImage after the animation dimensions are known.
Median-cut quantization and Floyd-Steinberg dithering cannot be interrupted while they are running. The context is checked between those bounded operations. Callers must impose an appropriate pixel limit before calling.
func Validate
deprecated
Validate checks the frame count, loop behavior, dimensions, and interval of gifBytes.
Deprecated: Validate is a test-only helper specific to D2's output and will be removed after one compatibility release. Downstream tests should decode the GIF and validate the properties they rely on directly.
Types ¶
type OpaquePalettedAnimationEncoder ¶ added in v0.9.0
type OpaquePalettedAnimationEncoder struct {
// contains filtered or unexported fields
}
OpaquePalettedAnimationEncoder incrementally encodes normalized, fully opaque paletted frames. It is useful when a renderer can release each frame before producing the next one. The opaque contract permits matching frames to share a global color table. An encoder is single-use and is not safe for concurrent calls.
func NewOpaquePalettedAnimationEncoder ¶ added in v0.9.0
func NewOpaquePalettedAnimationEncoder(ctx context.Context, width, height, totalFrames, intervalMs int, maxBytes int64) (*OpaquePalettedAnimationEncoder, error)
NewOpaquePalettedAnimationEncoder creates an incremental GIF encoder for an exact frame count and canvas. maxBytes bounds the encoded output before growth. WriteFrame rejects any palette entry that is not fully opaque.
func (*OpaquePalettedAnimationEncoder) Finish ¶ added in v0.9.0
func (e *OpaquePalettedAnimationEncoder) Finish() ([]byte, error)
Finish closes the animation and returns its encoded bytes. It fails unless the configured number of frames has been written.
func (*OpaquePalettedAnimationEncoder) WriteFrame ¶ added in v0.9.0
func (e *OpaquePalettedAnimationEncoder) WriteFrame(frame *image.Paletted) error
WriteFrame validates and encodes the next frame. The frame is no longer retained when this method returns, except for the palette values copied into the GIF stream.
type OpaqueQuantizationWorkspace ¶ added in v0.9.0
type OpaqueQuantizationWorkspace struct {
// contains filtered or unexported fields
}
OpaqueQuantizationWorkspace owns reusable indexed pixels and dithering storage for a serial sequence of fully opaque raster frames. Its zero value is ready for use. Calls must not overlap, including from a Quantize callback. The workspace retains storage sized for the largest frame it has processed; assigning a zero value releases that storage for garbage collection.
func (*OpaqueQuantizationWorkspace) Quantize ¶ added in v0.9.0
func (w *OpaqueQuantizationWorkspace) Quantize(ctx context.Context, img image.Image, consume func(*image.Paletted) error) error
Quantize converts one opaque RGBA or NRGBA image and calls consume with the resulting indexed frame. The frame and its pixel and palette storage are borrowed: callers must finish using all three before consume returns.
Source Files