Struct WriterBase

pub struct WriterBase<S> {
    rng: u16,
    cnt: i16,
    fake_bits_frac: u32,
    s: S,
}

Fields

rng: u16

The number of values in the current range.

cnt: i16

The number of bits of data in the current value.

fake_bits_frac: u32

Extra offset added to tell() and tell_frac() to approximate costs of actually coding a symbol

s: S

Use-specific storage

Implementations

impl<S> WriterBase<S>

A few local helper functions needed by the Writer that are not part of the public interface.

const fn new(storage: S) -> Self

Internal constructor called by the subtypes that implement the actual encoder and Recorder.

const fn lr_compute(&self, fl: u16, fh: u16, nms: u16) -> (u32, u16)

Compute low and range values from token cdf values and local state

fn frac_compute(nbits_total: u32, rng: u32) -> u32

Given the current total integer number of bits used and the current value of rng, computes the fraction number of bits used to OD_BITRES precision. This is used by od_ec_enc_tell_frac() and od_ec_dec_tell_frac(). nbits_total: The number of whole bits currently used, i.e., the value returned by od_ec_enc_tell() or od_ec_dec_tell(). rng: The current value of rng from either the encoder or decoder state. Return: The number of bits scaled by 2**OD_BITRES. This will always be slightly larger than the exact value (e.g., all rounding error is in the positive direction).

const fn recenter(r: u32, v: u32) -> u32

impl WriterBase<WriterRecorder>

Replay implementation specific to the Recorder

pub fn replay(&mut self, dest: &mut dyn StorageBackend)

Replays the partially-computed range tokens out of the Recorder’s storage and into the passed in Writer, which may be an Encoder or another Recorder. Clears the Recorder after replay.

impl WriterBase<WriterEncoder>

Done implementation specific to the Encoder

pub fn done(&mut self) -> Vec<u8>

Indicates that there are no more symbols to encode. Flushes remaining state into coding and returns a vector containing the final bitstream.

Trait Implementations

impl<S: Clone> Clone for WriterBase<S>

fn clone(&self) -> WriterBase<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug> Debug for WriterBase<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl StorageBackend for WriterBase<WriterCounter>

The Counter stores nothing we write to it, it merely counts the bit usage like in an Encoder for cost analysis.

fn store(&mut self, fl: u16, fh: u16, nms: u16)

Store partially-computed range code into given storage backend

fn stream_bits(&mut self) -> usize

Return bit-length of encoded stream to date

fn checkpoint(&mut self) -> WriterCheckpoint

Backend implementation of checkpoint to pass through Writer interface

fn rollback(&mut self, checkpoint: &WriterCheckpoint)

Backend implementation of rollback to pass through Writer interface

impl StorageBackend for WriterBase<WriterEncoder>

An Encoder produces an actual range-coded bitstream from passed in tokens. It does not retain any information about the coded tokens, only the resulting bitstream, and so it cannot be replayed (only checkpointed and rolled back).

fn store(&mut self, fl: u16, fh: u16, nms: u16)

Store partially-computed range code into given storage backend

fn stream_bits(&mut self) -> usize

Return bit-length of encoded stream to date

fn checkpoint(&mut self) -> WriterCheckpoint

Backend implementation of checkpoint to pass through Writer interface

fn rollback(&mut self, checkpoint: &WriterCheckpoint)

Backend implementation of rollback to pass through Writer interface

impl StorageBackend for WriterBase<WriterRecorder>

The Recorder does not produce a range-coded bitstream, but it still tracks the range coding progress like in an Encoder, as it neds to be able to report bit costs for RDO decisions. It stores a pair of mostly-computed range coding values per token recorded.

fn store(&mut self, fl: u16, fh: u16, nms: u16)

Store partially-computed range code into given storage backend

fn stream_bits(&mut self) -> usize

Return bit-length of encoded stream to date

fn checkpoint(&mut self) -> WriterCheckpoint

Backend implementation of checkpoint to pass through Writer interface

fn rollback(&mut self, checkpoint: &WriterCheckpoint)

Backend implementation of rollback to pass through Writer interface

impl<S> Writer for WriterBase<S>

where WriterBase<S>: StorageBackend,

Generic/shared implementation for Writers with StorageBackends (ie, Encoders and Recorders)

fn bool(&mut self, val: bool, f: u16)

Encode a single binary value. val: The value to encode (0 or 1). f: The probability that the val is one, scaled by 32768.

fn bit(&mut self, bit: u16)

Encode a single boolean value.

• val: The value to encode (false or true).
• f: The probability that the val is true, scaled by 32768.

fn literal(&mut self, bits: u8, s: u32)

Encode a literal bitstring, bit by bit in MSB order, with flat probability.

• ‘bits’: Length of bitstring
• ‘s’: Bit string to encode

fn symbol<const CDF_LEN: usize>(&mut self, s: u32, cdf: &[u16; CDF_LEN])

Encodes a symbol given a cumulative distribution function (CDF) table in Q15.

• s: The index of the symbol to encode.
• cdf: The CDF, such that symbol s falls in the range [s > 0 ? cdf[s - 1] : 0, cdf[s]). The values must be monotonically non-decreasing, and the last value must be greater than 32704. There should be at most 16 values. The lower 6 bits of the last value hold the count.

fn symbol_with_update<const CDF_LEN: usize>( &mut self, s: u32, cdf: CDFOffset<CDF_LEN>, log: &mut CDFContextLog, fc: &mut CDFContext, )

Encodes a symbol given a cumulative distribution function (CDF) table in Q15, then updates the CDF probabilities to reflect we’ve written one more symbol ‘s’.

• s: The index of the symbol to encode.
• cdf: The CDF, such that symbol s falls in the range [s > 0 ? cdf[s - 1] : 0, cdf[s]). The values must be monotonically non-decreasing, and the last value must be greater 32704. There should be at most 16 values. The lower 6 bits of the last value hold the count.

fn symbol_bits(&self, s: u32, cdf: &[u16]) -> u32

Returns approximate cost for a symbol given a cumulative distribution function (CDF) table and current write state.

• s: The index of the symbol to encode.
• cdf: The CDF, such that symbol s falls in the range [s > 0 ? cdf[s - 1] : 0, cdf[s]). The values must be monotonically non-decreasing, and the last value must be greater than 32704. There should be at most 16 values. The lower 6 bits of the last value hold the count.

fn write_golomb(&mut self, level: u32)

Encode a golomb to the bitstream.

• ‘level’: passed in value to encode

fn write_quniform(&mut self, n: u32, v: u32)

Write a value v in [0, n-1] quasi-uniformly

• n: size of interval
• v: value to encode

fn count_quniform(&self, n: u32, v: u32) -> u32

Returns QOD_BITRES bits for a value v in [0, n-1] quasi-uniformly

• n: size of interval
• v: value to encode

fn write_subexp(&mut self, n: u32, k: u8, v: u32)

Write symbol v in [0, n-1] with parameter k as finite subexponential

• n: size of interval
• k: “parameter”
• v: value to encode

fn count_subexp(&self, n: u32, k: u8, v: u32) -> u32

Returns QOD_BITRES bits for symbol v in [0, n-1] with parameter k as finite subexponential

• n: size of interval
• k: “parameter”
• v: value to encode

fn write_unsigned_subexp_with_ref(&mut self, v: u32, n: u32, k: u8, r: u32)

Write symbol v in [0, n-1] with parameter k as finite subexponential based on a reference r also in [0, n-1].

• v: value to encode
• n: size of interval
• k: “parameter”
• r: reference

fn count_unsigned_subexp_with_ref(&self, v: u32, n: u32, k: u8, r: u32) -> u32

Returns QOD_BITRES bits for symbol v in [0, n-1] with parameter k as finite subexponential based on a reference r also in [0, n-1].

• v: value to encode
• n: size of interval
• k: “parameter”
• r: reference

fn write_signed_subexp_with_ref( &mut self, v: i32, low: i32, high: i32, k: u8, r: i32, )

Write symbol v in [-(n-1), n-1] with parameter k as finite subexponential based on a reference r also in [-(n-1), n-1].

• v: value to encode
• n: size of interval
• k: “parameter”
• r: reference

fn count_signed_subexp_with_ref( &self, v: i32, low: i32, high: i32, k: u8, r: i32, ) -> u32

Returns QOD_BITRES bits for symbol v in [-(n-1), n-1] with parameter k as finite subexponential based on a reference r also in [-(n-1), n-1].

• v: value to encode
• n: size of interval
• k: “parameter”
• r: reference

fn tell(&mut self) -> u32

Returns the number of bits “used” by the encoded symbols so far. This same number can be computed in either the encoder or the decoder, and is suitable for making coding decisions. The value will be the same whether using an Encoder or Recorder.

Return: The integer number of bits. This will always be slightly larger than the exact value (e.g., all rounding error is in the positive direction).

fn tell_frac(&mut self) -> u32

Returns the number of bits “used” by the encoded symbols so far. This same number can be computed in either the encoder or the decoder, and is suitable for making coding decisions. The value will be the same whether using an Encoder or Recorder.

Return: The number of bits scaled by 2**OD_BITRES. This will always be slightly larger than the exact value (e.g., all rounding error is in the positive direction).

fn checkpoint(&mut self) -> WriterCheckpoint

Save current point in coding/recording to a checkpoint that can be restored later. A WriterCheckpoint can be generated for an Encoder or Recorder, but can only be used to rollback the Writer instance from which it was generated.

fn rollback(&mut self, wc: &WriterCheckpoint)

Roll back a given Writer to the state saved in the WriterCheckpoint

• ‘wc’: Saved Writer state/posiiton to restore

fn add_bits_frac(&mut self, bits_frac: u32)

Add additional bits from rate estimators without coding a real symbol