dymokomi/luce-png
Source of release 0.10.0
0.10.0 / src / png / animation.lucb
#==============================================================================================
#
# png/animation - An APNG's frames decoded and composited
#
# DESCRIPTION:
# An `Animation` holds a PNG's frames (png/apng) and a canvas the size of the image,
# transparent to begin with, as at the beginning of each play. Rendering frame N
# disposes of frame N - 1 as its fcTL says (keeps its rectangle, clears it to
# transparent, or restores what was there before the frame was drawn), then decodes
# frame N (its IDAT or fdAT data, with the image's color type, depth, palette, tRNS
# and interlacing, at its own size) and draws it into its rectangle: SOURCE replaces
# the rectangle, OVER composites the frame over it. The caller receives a copy of the
# whole canvas, as Ladybird's PNG loader pushes each frame. A hidden default image is
# decoded and discarded before the first frame, as libpng reads it.
#
# Frames are drawn as Ladybird's PNG loader draws them, with its Painter into a canvas
# of straight alpha: through Skia's float raster pipeline (`skia_draw`), SOURCE as
# Skia's Copy and OVER as its SourceOver, a "previous" disposal restoring the area by a
# Copy of what was under the frame. The pipeline premultiplies and unpremultiplies, so a
# transparent pixel drawn keeps no color, as in Ladybird.
#
# A still PNG is an animation of one frame, its image as it decodes (Ladybird draws
# nothing for it).
#
#==============================================================================================
## What becomes of a frame's rectangle before the next frame is drawn.
pub enum Disposal:
## It stays (APNG_DISPOSE_OP_NONE).
keep
## It is cleared to transparent (APNG_DISPOSE_OP_BACKGROUND).
background
## It is restored to what was there before the frame was drawn
## (APNG_DISPOSE_OP_PREVIOUS).
previous
## One frame: where it is drawn, for how long, and how.
pub struct Frame:
## The fcTL's rectangle, within the image.
pub var left: usize
pub var top: usize
pub var width: usize
pub var height: usize
## The delay as written: numerator / denominator seconds, a denominator of 0 meaning
## 100.
pub var delay_numerator: u16
pub var delay_denominator: u16
## The delay in milliseconds, rounded down.
pub var duration: u32
pub var disposal: Disposal = Disposal.keep
## Whether the frame is composited over the canvas (APNG_BLEND_OP_OVER), or replaces
## its rectangle (SOURCE).
pub var blend: bool
## Its image data: pieces of the walk.
var first_piece: usize
var piece_count: usize
## A PNG's frames, rendered as whole composited canvases. `data` must stay valid while the
## animation is in use; `release` frees what it holds.
pub struct Animation:
## The image's size and format, and the acTL's frame and loop counts.
pub var info: Info
## Whether every frame acTL declares was found; false when the file is damaged or ends
## after the frames found (Ladybird then shows the first frame as a still image).
pub var complete: bool
var data: const u8[]
var parsed: Parsed
var walked: Walked
var options: DecodeOptions
## The canvas, `info.width * info.height` RGBA pixels, as the last frame rendered left
## it; what was under that frame, for its "previous" disposal; a frame's own pixels.
var canvas: u8[]
var saved: u8[]
var frame_pixels: u8[]
## The frame the next `render` draws first.
var next: usize
## An animation of the PNG in `data`: its chunks walked to its frames (no pixels decoded)
## and its canvases allocated. Fails where libpng fails to read the PNG's header.
pub static func open(data: const u8[], options: DecodeOptions = DecodeOptions()) -> Animation!:
var parsed = Parsed()
errdefer parsed.close()
var walked = try walk_frames(data, &parsed)
errdefer walked.release()
let size = parsed.info.width * parsed.info.height * 4
if size > options.max_bytes:
error(limit, "PNG canvas exceeds byte limit")
let canvas = try new u8[size] in memory.heap
errdefer free(canvas) in memory.heap
let frame_pixels = try new u8[size] --- in memory.heap
return Animation(info = parsed.info, complete = walked.complete, data = data, parsed = parsed, walked = walked, options = options, canvas = canvas, frame_pixels = frame_pixels)
## The frames found, in order.
pub func frames() -> const Frame[]:
return self.walked.frames[..<self.walked.count]
## Render frame `index` into `out`, `info.width * info.height * 4` bytes of straight
## RGBA: the canvas with every frame up to it composited. Frames render fastest in
## order; an earlier index starts again from the first. Fails for an index past the
## last frame, an `out` too small, or a frame (or the hidden default image before the
## first) that does not decode.
pub func render(index: usize, out: u8[]) -> !:
if index >= self.walked.count:
error(invalid, "PNG frame index is past the last frame")
let size = self.canvas.length
if out.length < size:
error(invalid, "PNG output buffer is smaller than the picture")
if index + 1 < self.next or self.next == 0:
memory.set(self.canvas, 0)
self.next = 0
if self.walked.hidden:
# libpng reads the default image before the first frame.
try self.decode_frame(self.walked.hidden_first, self.walked.hidden_count, self.info.width, self.info.height, true)
while self.next <= index:
if self.next > 0:
self.dispose(self.walked.frames[self.next - 1])
let frame = self.walked.frames[self.next]
if frame.disposal == Disposal.previous:
try self.save(frame)
try self.decode_frame(frame.first_piece, frame.piece_count, frame.width, frame.height, frame.first_piece == 0)
self.draw(frame)
self.next += 1
memory.copy(out, self.canvas, size)
## Free the frames, the canvases and the header.
pub func release():
self.walked.release()
self.parsed.close()
free(self.canvas) in memory.heap
free(self.frame_pixels) in memory.heap
if self.saved.length > 0:
free(self.saved) in memory.heap
var no_bytes: u8[]
self.saved = no_bytes
var no_walk = Walked()
self.walked = no_walk
# mark: Frames ============================================================================
## Decode the image data of pieces `first` to `first + count` (IDAT chunks, whose CRCs
## are checked, when `idat`) as a `width` by `height` image into `frame_pixels`. As
## libpng (through zlib) reads a frame, the stream must give every row, and its Adler-32
## is checked when it is there; a stream cut short after the rows is accepted. (libpng
## also takes a stream that goes on past the rows, with a warning; this refuses it.)
func decode_frame(first: usize, count: usize, width: usize, height: usize, idat: bool) -> !:
var frame = self.parsed
frame.info.width = width
frame.info.height = height
frame.pieces = self.walked.pieces[first..<first + count]
frame.count = count
frame.bands = 0
if count == 0:
error(corrupt, "PNG frame has no image data")
if idat:
try frame.check_idat(self.data, 1)
let l = Layout.of(&frame)
var total: usize = 0
for index in 0..<count:
total += frame.pieces[index].length
if total > self.options.max_bytes:
error(limit, "PNG data exceeds byte limit")
let stream = frame.piece(self.data, 0) if count == 1 else try join_pieces(self.data, &frame, total)
defer:
if count > 1:
free((u8[])stream) in memory.heap
if stream.length < 2:
error(corrupt, "invalid zlib header")
try check_zlib_header(stream)
let raw = try new u8[scanline_bytes(&l, frame.info.interlaced)] --- in memory.heap
defer free(raw) in memory.heap
let used = try flate.inflate_raw(stream[2..], raw)
if stream.length >= 2 + used + 4:
try check_adler(stream, 2 + used, flate.adler32(raw))
var target = Target(bytes = self.frame_pixels[..<width * height * 4])
try rows_in_order(&frame, &l, raw, &target)
## Draw the decoded frame into its rectangle, as Skia's Copy (SOURCE) or SourceOver (OVER);
## a still PNG's image is the canvas as it decodes.
func draw(frame: Frame):
let width = self.info.width
if not self.info.animated:
memory.copy(self.canvas, self.frame_pixels, self.canvas.length)
return
for y in 0..<frame.height:
let row = self.canvas.data + ((frame.top + y) * width + frame.left) * 4
let source = self.frame_pixels.data + y * frame.width * 4
for x in 0..<frame.width:
skia_draw(row + x * 4, source + x * 4, frame.blend)
## Dispose of `frame`, the last one drawn, before the next is drawn over it: its area
## cleared to transparent, or drawn back (a Copy) from what was under it.
func dispose(frame: Frame):
let width = self.info.width
match frame.disposal:
.keep:
return
.background:
for y in 0..<frame.height:
let row = ((frame.top + y) * width + frame.left) * 4
memory.set(self.canvas[row..<row + frame.width * 4], 0)
.previous:
let span = frame.width * 4
for y in 0..<frame.height:
let row = self.canvas.data + ((frame.top + y) * width + frame.left) * 4
let saved = self.saved.data + y * span
for x in 0..<frame.width:
skia_draw(row + x * 4, saved + x * 4, false)
## Keep what is under `frame` before it is drawn, for its "previous" disposal.
func save(frame: Frame) -> !:
if self.saved.length == 0:
self.saved = try new u8[self.canvas.length] --- in memory.heap
let span = frame.width * 4
for y in 0..<frame.height:
let row = ((frame.top + y) * self.info.width + frame.left) * 4
memory.copy(self.saved[y * span..], self.canvas[row..], span)
# mark: Skia's pipeline =========================================================================
## 1/255 as an f32 (Skia's from_byte scale).
let byte_scale: f32 = f32.bits(0x3b808081)
## Skia's to_unorm(v, 255): clamped to 0..1, scaled and rounded to nearest, ties to even
## (vcvtnq_u32_f32, _mm_cvtps_epi32).
func to_unorm(v: f32) -> u8:
let clamped = 0.0 if not (v > 0.0) else 1.0 if v > 1.0 else v
let scaled = clamped * 255.0
let whole = (u32)scaled
let fraction = scaled - (f32)whole
if fraction > 0.5 or (fraction == 0.5 and (whole & 1) == 1):
return (u8)(whole + 1)
return (u8)whole
## A straight RGBA pixel `source` drawn onto the straight RGBA pixel `target` through Skia's
## highp raster pipeline, as Ladybird's Painter draws a straight-alpha bitmap into a
## straight-alpha surface: both read as floats (each byte times 1/255) and premultiplied, then
## blended (Copy: the source; SourceOver: the target times one less the source's alpha, a
## fused multiply-add as on arm64, plus the source), unpremultiplied (times 1/alpha, or 0 for a
## transparent result) and stored.
func skia_draw(target: u8*, source: const u8*, over: bool):
let sa = (f32)source[3] * byte_scale
var a = sa
var color: f32[3] = ---
for c in 0..<(usize)3:
color[c] = (f32)source[c] * byte_scale * sa
if over:
let da = (f32)target[3] * byte_scale
let inverse = 1.0 - sa
for c in 0..<(usize)3:
let dc = (f32)target[c] * byte_scale * da
color[c] = dc.mul_add(inverse, color[c])
a = da.mul_add(inverse, sa)
let reciprocal: f32 = 1.0 / a
let scale: f32 = reciprocal if reciprocal < f32.bits(0x7f800000) else 0.0
for c in 0..<(usize)3:
target[c] = to_unorm(color[c] * scale)
target[3] = to_unorm(a)