Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-jpeg

Source of release 0.10.0

0.10.0 / src / jpeg / encode.lucb

#==============================================================================================
#
#   jpeg/encode - The baseline encoder
#
#   DESCRIPTION:
#       Baseline JPEG from 8-bit gray, RGB or RGBA rows (alpha is ignored), 4:4:4, 4:2:2
#       or 4:2:0, with the Annex K quantization tables scaled by quality. Rows arrive
#       all at once (`encode_rgba8` and friends) or in any number of pushes through an
#       `Encoder`, which holds only a group of MCU rows (a few per thread) at a time.
#
#       Each group's MCU rows transform and Huffman-code on every processor into
#       separate bit streams, which the calling thread then joins into the file. With
#       `restart` a restart marker follows every MCU row, so decoders (this one too)
#       can split the entropy decoding. With `optimize` the Huffman tables are fitted
#       to the picture in a second pass, which keeps every block until `finish`.
#
#==============================================================================================

## Chroma resolution: full, half across, or half across and down.
pub enum Subsampling:
    s444
    s422
    s420

## Input pixels: bytes a pixel and their order.
pub enum Input:
    rgba
    rgb
    gray

## How an encode runs.
pub struct EncodeOptions:
    ## 1..100, as libjpeg's quality.
    pub var quality: i64 = 90
    ## Ignored for gray input.
    pub var subsampling: Subsampling = .s420
    ## A restart marker after every MCU row.
    pub var restart: bool = false
    ## Huffman tables fitted to the picture: a few percent smaller, and every block
    ## is kept in memory until `finish`.
    pub var optimize: bool = false
    ## Worker threads, counting the caller's; 0 uses every processor.
    pub var threads: usize = 0
    ## An ICC profile to embed (APP2 ICC_PROFILE segments, as the ICC spec chunks
    ## them), telling readers the pixels' color space; empty for none. Borrowed
    ## until the encode finishes.
    pub var icc_profile: const u8[]

## Encode `width` x `height` RGBA pixels (row after row) as a JPEG appended to `output`.
pub func encode_rgba8(pixels: const u8[], width: usize, height: usize, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> !:
    try encode_pixels(pixels, width, height, .rgba, output, options)

## Encode RGB pixels, three bytes each.
pub func encode_rgb8(pixels: const u8[], width: usize, height: usize, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> !:
    try encode_pixels(pixels, width, height, .rgb, output, options)

## Encode gray pixels, one byte each, as a one-component JPEG.
pub func encode_gray8(pixels: const u8[], width: usize, height: usize, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> !:
    try encode_pixels(pixels, width, height, .gray, output, options)

func encode_pixels(pixels: const u8[], width: usize, height: usize, input: Input, output: Buffer*, options: EncodeOptions) -> !:
    var encoder = try Encoder.begin(width, height, input, output, options)
    defer encoder.close()
    try encoder.write_rows(pixels, height)
    try encoder.finish()

## Encode a Raster's gray or RGB uint8 samples at `quality`, 4:4:4, as before.
pub func encode(image: const Raster*, output: Buffer*, quality: i64 = 90) -> !:
    let nc = image.channels.length
    if nc != 1 and nc != 3:
        error(unsupported, "JPEG requires grayscale or RGB; convert alpha explicitly")
    for c in image.channels:
        if c.kind != .uint8:
            error(unsupported, "JPEG requires uint8 samples")
    if image.pixels.length != image.width * image.height * nc:
        error(invalid, "JPEG raster pixels are not allocated")
    var encoder = try Encoder.begin(image.width, image.height, .gray if nc == 1 else .rgb, output, EncodeOptions(quality = quality, subsampling = .s444))
    defer encoder.close()
    # Samples to bytes a few rows at a time, rounded to the nearest.
    let chunk: usize = 64
    let row_bytes = image.width * nc
    let bytes = try new u8[chunk * row_bytes] --- in memory.heap
    defer free(bytes) in memory.heap
    var y: usize = 0
    while y < image.height:
        let rows = chunk if y + chunk <= image.height else image.height - y
        let samples = image.pixels[y * row_bytes..<(y + rows) * row_bytes]
        for i in 0..<samples.length:
            let value = samples[i]
            if not (value >= 0.0 and value <= 255.0):
                error(invalid, "JPEG sample out of range")
            bytes[i] = floor8(value + 0.5)
        try encoder.write_rows(bytes[..<rows * row_bytes], rows)
        y += rows
    try encoder.finish()

## One MCU row's work: its blocks, its coded stream (MCU 1 on, or all of it when
## `whole`), and each component's last DC.
struct Band:
    var blocks: i16[]
    var stream: BitBuffer
    var last: i32[3]
    var whole: bool
    var counts: Counts

## A JPEG being written row by row: `begin`, `write_rows` as often as needed, then
## `finish`, and `close` in any case.
pub struct Encoder:
    var frame: EncodeFrame
    var coding: Coding
    var output: Buffer*
    var threads: usize
    ## MCU rows a group, and the group's row buffer and the rows in it.
    var group: usize
    var rows: u8[]
    var buffered: usize
    ## Rows received, and MCU rows transformed.
    var received: usize
    var next_band: usize
    ## The group's bands, or with `optimize` every band.
    var bands: Band[]
    var first: BitBuffer
    var writer: Stuffer
    var predictors: i32[3]
    var finished: bool
    ## The ICC profile the header embeds (EncodeOptions.icc_profile).
    var profile: const u8[]

    ## Start a `width` x `height` JPEG of `input` pixels at the end of `output`.
    pub static func begin(width: usize, height: usize, input: Input, output: Buffer*, options: EncodeOptions = EncodeOptions()) -> Encoder!:
        if width == 0 or height == 0 or width > 65535 or height > 65535 or options.quality < 1 or options.quality > 100:
            error(invalid, "JPEG dimensions or quality out of range")
        let pixel: usize = 4 if input == .rgba else 3 if input == .rgb else 1
        var encoder = Encoder(frame = EncodeFrame.make(width, height, pixel, options.subsampling, options.quality, options.restart, options.optimize), output = output, threads = thread_count(options.threads, width * height), writer = Stuffer(out = output, acc = 0, bits = 0), profile = options.icc_profile)
        let f = &encoder.frame
        encoder.group = encoder.threads * 2 if encoder.threads * 2 < f.mcuy else f.mcuy
        encoder.coding.sizes = magnitude_bits()
        encoder.coding.dc[0] = CodeTable.make(std_dc_luma_counts, std_dc_luma_values)
        encoder.coding.ac[0] = CodeTable.make(std_ac_luma_counts, std_ac_luma_values)
        encoder.coding.dc[1] = CodeTable.make(std_dc_chroma_counts, std_dc_chroma_values)
        encoder.coding.ac[1] = CodeTable.make(std_ac_chroma_counts, std_ac_chroma_values)
        encoder.bands = try new Band[f.mcuy if f.optimize else encoder.group] in memory.heap
        errdefer encoder.close()
        if not f.optimize:
            try write_header(&encoder)
        return encoder

    ## Push `count` rows of pixels, tightly packed.
    pub func write_rows(pixels: const u8[], count: usize) -> !:
        let f = &self.frame
        let row_bytes = f.width * f.pixel
        if self.finished or self.received + count > f.height:
            error(invalid, "more JPEG rows than the picture has")
        if pixels.length < count * row_bytes:
            error(invalid, "JPEG rows are shorter than the width")
        let group_rows = self.group * f.band_rows
        var taken: usize = 0
        while taken < count:
            if self.buffered == 0:
                # Whole groups, or everything left of the picture, straight from the
                # caller's rows.
                let left = count - taken
                var bands: usize = 0
                if self.received + left == f.height:
                    bands = f.mcuy - self.next_band
                elif left >= group_rows:
                    bands = left // group_rows * self.group
                if bands > 0:
                    let source = Source(data = pixels.data + taken * row_bytes, stride = row_bytes, first_row = self.received)
                    try self.encode_bands(&source, bands)
                    let used = left if self.received + left == f.height else bands * f.band_rows
                    taken += used
                    self.received += used
                    continue
            if self.rows.length == 0:
                self.rows = try new u8[group_rows * row_bytes] --- in memory.heap
            let rows = group_rows - self.buffered if group_rows - self.buffered < count - taken else count - taken
            memory.copy(self.rows[self.buffered * row_bytes..], pixels[taken * row_bytes..], rows * row_bytes)
            self.buffered += rows
            self.received += rows
            taken += rows
            if self.buffered == group_rows or self.received == f.height:
                let source = Source(data = self.rows.data, stride = row_bytes, first_row = self.received - self.buffered)
                let bands = self.group if self.received < f.height else f.mcuy - self.next_band
                try self.encode_bands(&source, bands)
                self.buffered = 0

    ## Complete the file once every row is in.
    pub func finish() -> !:
        let f = &self.frame
        if self.finished:
            return
        if self.received != f.height:
            error(invalid, "JPEG rows missing at finish")
        if f.optimize:
            try self.fit_tables()
            try write_header(&self)
            var band: usize = 0
            while band < f.mcuy:
                let count = self.group if band + self.group <= f.mcuy else f.mcuy - band
                try self.code_group(band, count)
                band += count
        try self.output.reserve(8)
        self.writer.align()
        try self.output.put(b"\xff\xd9")
        self.finished = true

    pub func close():
        for i in 0..<self.bands.length:
            if self.bands[i].blocks.length > 0:
                free(self.bands[i].blocks) in memory.heap
            self.bands[i].stream.close()
        if self.bands.length > 0:
            free(self.bands) in memory.heap
        if self.rows.length > 0:
            free(self.rows) in memory.heap
        self.first.close()
        var empty: Band[]
        self.bands = empty
        var none_rows: u8[]
        self.rows = none_rows

    ## Transform `count` MCU rows from `source` and, unless optimizing, code them.
    func encode_bands(source: const Source*, count: usize) -> !:
        var done: usize = 0
        while done < count:
            let n = self.group if done + self.group <= count else count - done
            var job = BandJob(encoder = &self, source = source, first_band = self.next_band)
            try run_tasks(band_task, (void*)&job, n, self.threads, 0, 0, transform_bytes(&self.frame))
            if job.failed.load() != 0:
                error(memory.exhausted, "JPEG encoder buffers could not grow")
            if not self.frame.optimize:
                for i in 0..<n:
                    try self.join(&self.bands[i], self.next_band + i)
            self.next_band += n
            done += n

    ## Append band `index`'s stream to the file: its restart marker, its first MCU
    ## (unless the stream has it) and the rest.
    func join(band: Band*, index: usize) -> !:
        let f = &self.frame
        try self.output.reserve(band.stream.used * 8 + f.mcu_blocks * 64 * 8 + 64)
        if f.restart and index > 0:
            self.writer.align()
            self.output.data[self.output.used] = 255
            self.output.data[self.output.used + 1] = (u8)(208 + (index - 1) % 8)
            self.output.used += 2
            self.predictors = [0, 0, 0]
        if not band.whole:
            self.first.reset()
            if not self.first.ensure(f.mcu_blocks * 54 + 2):
                error(memory.exhausted, "JPEG encoder buffers could not grow")
            code_mcu(&self.frame, &self.coding, band.blocks.data, &self.predictors[0], &self.first)
            self.writer.append(&self.first)
        self.writer.append(&band.stream)
        self.predictors = band.last

    ## Count every band's symbols and fit the four tables to them.
    func fit_tables() -> !:
        let f = &self.frame
        var job = BandJob(encoder = &self, first_band = 0, counting = true)
        try run_tasks(band_task, (void*)&job, f.mcuy, self.threads)
        var total = Counts()
        for b in 0..<f.mcuy:
            for i in 0..<(usize)514:
                total.dc[i] += self.bands[b].counts.dc[i]
                total.ac[i] += self.bands[b].counts.ac[i]
        for t in 0..<(usize)(1 if f.count == 1 else 2):
            self.coding.dc[t] = optimal_table(total.dc[t * 257..<t * 257 + 257])
            self.coding.ac[t] = optimal_table(total.ac[t * 257..<t * 257 + 257])

    ## Code kept bands `first..<first + count` whole and join them.
    func code_group(first: usize, count: usize) -> !:
        var job = BandJob(encoder = &self, first_band = first, coding = true)
        try run_tasks(band_task, (void*)&job, count, self.threads)
        if job.failed.load() != 0:
            error(memory.exhausted, "JPEG encoder buffers could not grow")
        for i in 0..<count:
            try self.join(&self.bands[first + i], first + i)
            self.bands[first + i].stream.close()

## One parallel step over bands: transform (and code, unless optimizing), count
## symbols, or code kept bands whole.
struct BandJob:
    var encoder: Encoder*
    var source: const Source*?
    var first_band: usize
    var counting: bool
    var coding: bool
    var failed: @u32

func band_task(context: void*, index: usize, scratch: Scratch*):
    let job = (BandJob*)context
    let e = job.encoder
    let f = &e.frame
    let number = job.first_band + index
    let band = &e.bands[number if f.optimize else index]
    if job.counting or job.coding:
        # Kept bands: predictors come from the band before, unless it restarted.
        var predictors: i32[3] = [0, 0, 0]
        if number > 0 and not f.restart:
            predictors = e.bands[number - 1].last
        if job.counting:
            band.counts = Counts()
            count_mcus(f, &e.coding, band.blocks.data, 0, f.mcux, &predictors[0], &band.counts)
            return
        band.stream.reset()
        band.whole = true
        if not code_mcus(f, &e.coding, band.blocks.data, 0, f.mcux, &predictors[0], &band.stream):
            _ = job.failed.swap(1)
        return
    if band.blocks.length == 0:
        band.blocks = new i16[f.band_blocks * 64] --- in memory.heap catch:
            _ = job.failed.swap(1)
            return
    let source = job.source else return
    transform_band(f, source, number, band.blocks.data, &band.last[0], scratch.bytes.data)
    if f.optimize:
        return
    # MCU 1 on, predicted from MCU 0; the join codes MCU 0 once the band before is known.
    var predictors: i32[3] = [0, 0, 0]
    predictors[0] = (i32)band.blocks[(f.h * f.v - 1) * 64]
    if f.count == 3:
        predictors[1] = (i32)band.blocks[f.h * f.v * 64]
        predictors[2] = (i32)band.blocks[(f.h * f.v + 1) * 64]
    band.stream.reset()
    band.whole = false
    if not code_mcus(f, &e.coding, band.blocks.data, 1, f.mcux, &predictors[0], &band.stream):
        _ = job.failed.swap(1)

## Code MCUs `first..<last` of a band's blocks; false when the stream could not grow.
func code_mcus(f: const EncodeFrame*, coding: const Coding*, blocks: const i16*, first: usize, last: usize, predictors: i32*, out: BitBuffer*) -> bool:
    for mcu in first..<last:
        if not out.ensure(f.mcu_blocks * 54 + 2):
            return false
        code_mcu(f, coding, blocks + mcu * f.mcu_blocks * 64, predictors, out)
    return true

## Code the MCU at `blocks`, updating the predictors.
func code_mcu(f: const EncodeFrame*, coding: const Coding*, blocks: const i16*, predictors: i32*, out: BitBuffer*):
    let luma = f.h * f.v
    let sizes = &coding.sizes[0]
    for i in 0..<luma:
        code_block(out, blocks + i * 64, predictors[0], &coding.dc[0], &coding.ac[0], sizes)
        predictors[0] = (i32)blocks[i * 64]
    if f.count == 3:
        for c in 1..<(usize)3:
            let block = blocks + (luma + c - 1) * 64
            code_block(out, block, predictors[c], &coding.dc[1], &coding.ac[1], sizes)
            predictors[c] = (i32)block[0]

func count_mcus(f: const EncodeFrame*, coding: const Coding*, blocks: const i16*, first: usize, last: usize, predictors: i32*, counts: Counts*):
    let luma = f.h * f.v
    let sizes = &coding.sizes[0]
    for mcu in first..<last:
        let at = blocks + mcu * f.mcu_blocks * 64
        for i in 0..<luma:
            count_block(at + i * 64, predictors[0], &counts.dc[0], &counts.ac[0], sizes)
            predictors[0] = (i32)at[i * 64]
        if f.count == 3:
            for c in 1..<(usize)3:
                let block = at + (luma + c - 1) * 64
                count_block(block, predictors[c], &counts.dc[257], &counts.ac[257], sizes)
                predictors[c] = (i32)block[0]

## SOI through SOS: JFIF, quantization and Huffman tables, the frame, the restart
## interval and the scan header.
func write_header(e: Encoder*) -> !:
    let f = &e.frame
    let output = e.output
    let tables: usize = 1 if f.count == 1 else 2
    try output.put(b"\xff\xd8")
    try emit_segment(output, 224, b"JFIF\0\x01\x01\0\0\x01\0\x01\0\0")
    try write_profile(output, e.profile)
    var data = Buffer()
    defer data.close()
    for t in 0..<tables:
        try data.byte((u8)t)
        for i in 0..<64:
            try data.byte(f.quant[t * 64 + zigzag[i]])
    try emit_segment(output, 219, data.view())
    data.used = 0
    try data.byte(8)
    try data.uint((u64)f.height, 2, false)
    try data.uint((u64)f.width, 2, false)
    try data.byte((u8)f.count)
    for c in 0..<f.count:
        try data.byte((u8)c + 1)
        try data.byte((u8)(f.h * 16 + f.v) if c == 0 else 17)
        try data.byte(0 if c == 0 else 1)
    try emit_segment(output, 192, data.view())
    data.used = 0
    for t in 0..<tables:
        for class in 0..<(usize)2:
            let table = &e.coding.dc[t] if class == 0 else &e.coding.ac[t]
            try data.byte((u8)(class * 16 + t))
            try data.put(table.counts)
            try data.put(table.values[..<table.count])
    try emit_segment(output, 196, data.view())
    if f.restart:
        data.used = 0
        try data.uint((u64)f.mcux, 2, false)
        try emit_segment(output, 221, data.view())
    data.used = 0
    try data.byte((u8)f.count)
    for c in 0..<f.count:
        try data.byte((u8)c + 1)
        try data.byte(0 if c == 0 else 17)
    try data.put(b"\0\x3f\0")
    try emit_segment(output, 218, data.view())

## The most profile bytes one APP2 segment holds: 65535 less the length field, the
## "ICC_PROFILE\0" tag and the chunk's number and count.
let profile_chunk: usize = 65519

## `profile` as APP2 ICC_PROFILE segments, numbered from 1, each saying how many there are.
func write_profile(output: Buffer*, profile: const u8[]) -> !:
    if profile.length == 0:
        return
    let count = (profile.length + profile_chunk - 1) // profile_chunk
    if count > 255:
        error(invalid, "an ICC profile in a JPEG is at most 255 segments")
    var data = Buffer()
    defer data.close()
    for at in 0..<count:
        data.used = 0
        try data.put(b"ICC_PROFILE\0")
        try data.byte((u8)(at + 1))
        try data.byte((u8)count)
        let start = at * profile_chunk
        let end = start + profile_chunk if start + profile_chunk < profile.length else profile.length
        try data.put(profile[start..<end])
        try emit_segment(output, 226, data.view())

func emit_segment(output: Buffer*, code: u8, data: const u8[]) -> !:
    try output.byte(255)
    try output.byte(code)
    try output.uint((u64)data.length + 2, 2, false)
    try output.put(data)