decoder

type Decoder interface {
	// Decode decodes the image and returns raw pixel data.
	// The pixel data format is consistent across all decoders:
	//   - 8-bit images: 1 byte per channel per pixel
	//   - 16-bit images: 2 bytes per channel per pixel (little-endian)
	//   - Channels are interleaved: RGBRGB... or RGBARGBA...
	Decode() ([]byte, error)

	// GetInfo returns metadata about the image.
	// This can be called before Decode() to get dimensions without
	// fully decoding the image.
	GetInfo() *ImageInfo
}

type Format int

type HDRDecoder interface {
	Decoder

	// DecodeHDR decodes the image and returns HDR pixel data as float32.
	// Each channel value is a floating-point number representing luminance.
	// The range depends on the HDR content (typically 0.0 to 10000.0+ nits).
	//
	// Returns ErrNoHDRData if the image doesn't contain HDR extension data.
	DecodeHDR() ([]float32, error)

	// DecodeHDR16 decodes the image and returns HDR pixel data as uint16.
	// This is useful for formats like JPEG XT Profile D (16-bit integer).
	//
	// Returns ErrNoHDRData if the image doesn't contain HDR extension data.
	DecodeHDR16() ([]uint16, error)

	// GetHDRInfo returns HDR-specific metadata.
	// Returns nil if the image doesn't contain HDR data.
	GetHDRInfo() *HDRInfo
}

type HDRInfo struct {
	// Profile indicates the JPEG XT profile (A, B, C, or D)
	Profile string

	// MinLuminance is the minimum luminance in nits (cd/m^2)
	MinLuminance float32

	// MaxLuminance is the maximum luminance in nits (cd/m^2)
	MaxLuminance float32

	// HasToneMap indicates if tone mapping data is present
	HasToneMap bool

	// HasAlpha indicates if alpha channel extension is present
	HasAlpha bool
}

type ImageInfo struct {
	// Width is the image width in pixels.
	Width int

	// Height is the image height in pixels.
	Height int

	// NumChannels is the number of color channels.
	// Common values: 1 (grayscale), 3 (RGB), 4 (RGBA)
	NumChannels int

	// BitDepth is the number of bits per sample.
	// Common values: 8 or 16
	BitDepth int

	// Format indicates which JPEG family format this image uses.
	Format Format

	// NumTilesX is the number of tiles horizontally (for tiled formats).
	// Zero or one for non-tiled images.
	NumTilesX int

	// NumTilesY is the number of tiles vertically (for tiled formats).
	// Zero or one for non-tiled images.
	NumTilesY int

	// TileWidth is the nominal tile width (for tiled formats).
	// Zero for non-tiled images.
	TileWidth int

	// TileHeight is the nominal tile height (for tiled formats).
	// Zero for non-tiled images.
	TileHeight int

	// HasHDR indicates if the image contains HDR extension data.
	HasHDR bool

	// IsLowLatency indicates if the format is designed for low-latency decoding.
	// JPEG XS is the primary low-latency format.
	IsLowLatency bool
}

type LowLatencyDecoder interface {
	Decoder

	// DecodeProgressive decodes the image progressively, calling the callback
	// for each decoded line. This enables low-latency streaming applications.
	DecodeProgressive(callback func(lineNumber int, data []byte) error) error

	// GetLatencyLines returns the latency in lines for progressive decoding.
	// JPEG XS is designed for sub-line latency.
	GetLatencyLines() int

	// GetMemoryBound returns the maximum memory usage in bytes.
	// JPEG XS has bounded memory requirements for real-time applications.
	GetMemoryBound() int64

	// IsLowLatency returns true if the decoder is configured for low-latency mode.
	IsLowLatency() bool
}

type StreamDecoder interface {
	// Decoder embeds the base decoder interface for GetInfo() access.
	Decoder

	// NumTiles returns the number of tiles in the image.
	// For non-tiled images or row-based streaming, this may represent
	// the number of rows or strips.
	NumTiles() int

	// TileInfo returns information about a specific tile.
	// Returns nil if the tile index is out of range.
	TileInfo(tileIdx int) *TileInfo

	// DecodeTile decodes a single tile and returns its raw pixel data.
	// This allows processing large images one tile at a time to limit
	// memory usage.
	//
	// The returned data is in the same format as Decode():
	//   - 8-bit images: 1 byte per channel per pixel
	//   - 16-bit images: 2 bytes per channel per pixel (little-endian)
	//   - Channels are interleaved within the tile
	DecodeTile(tileIdx int) ([]byte, error)

	// DecodeRow decodes a single row of pixels.
	// For formats that don't support row-by-row decoding, this may
	// decode the entire tile containing the row.
	//
	// Returns ErrStreamingNotSupported if row-based decoding is not available.
	DecodeRow(rowIdx int) ([]byte, error)

	// DecodeStream decodes the image using a callback for each tile.
	// This is useful for processing tiles as they are decoded without
	// storing them all in memory.
	//
	// The callback receives the tile index and its decoded pixel data.
	// If the callback returns an error, decoding stops and the error
	// is returned.
	DecodeStream(callback func(tileIdx int, data []byte) error) error

	// Reset resets the decoder state to allow re-decoding tiles.
	// This is useful when you want to decode tiles multiple times
	// or in a different order.
	Reset()
}

type TileInfo struct {
	// Index is the tile index (0-based).
	Index int

	// X is the horizontal tile position (0-based).
	X int

	// Y is the vertical tile position (0-based).
	Y int

	// Width is the tile width in pixels.
	Width int

	// Height is the tile height in pixels.
	Height int

	// OffsetX is the x-offset of this tile within the full image.
	OffsetX int

	// OffsetY is the y-offset of this tile within the full image.
	OffsetY int
}