Class: Cabriolet::Decompressors::Quantum

Inherits:
Base
  • Object
show all
Includes:
QuantumShared
Defined in:
lib/cabriolet/decompressors/quantum.rb

Overview

Quantum handles Quantum-compressed data using arithmetic coding Based on libmspack qtmd.c implementation

The Quantum method was created by David Stafford, adapted by Microsoft Corporation.

Defined Under Namespace

Classes: MSBBitstream

Constant Summary

Constants included from QuantumShared

QuantumShared::EXTRA_BITS, QuantumShared::FRAME_SIZE, QuantumShared::LENGTH_BASE, QuantumShared::LENGTH_EXTRA, QuantumShared::MAX_MATCH, QuantumShared::MIN_MATCH, QuantumShared::POSITION_BASE

Instance Attribute Summary collapse

Attributes inherited from Base

#buffer_size, #input, #io_system, #output

Instance Method Summary collapse

Methods included from QuantumShared

find_length_slot, find_position_slot

Constructor Details

#initialize(io_system, input, output, buffer_size, window_bits: 10, **_kwargs) ⇒ Quantum

Initialize Quantum decompressor

Parameters:



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/cabriolet/decompressors/quantum.rb', line 36

def initialize(io_system, input, output, buffer_size, window_bits: 10,
**_kwargs)
  super(io_system, input, output, buffer_size)

  # Validate window_bits
  unless (10..21).cover?(window_bits)
    raise ArgumentError,
          "Quantum window_bits must be 10-21, got #{window_bits}"
  end

  @window_bits = window_bits
  @window_size = 1 << window_bits

  # Initialize window (must be binary to avoid UTF-8 character vs byte mismatch)
  @window = ("\0" * @window_size).b
  @window_posn = 0
  @frame_todo = FRAME_SIZE

  # Arithmetic coding state
  @h = 0xFFFF
  @l = 0
  @c = 0
  @header_read = false

  # Initialize bitstream for MSB-first reading
  @bitstream = MSBBitstream.new(io_system, input, buffer_size)

  # Initialize models
  initialize_models
end

Instance Attribute Details

#window_bits ⇒ Object (readonly)

Returns the value of attribute window_bits.



27
28
29
 
# File 'lib/cabriolet/decompressors/quantum.rb', line 27

def window_bits
  @window_bits
end

#window_size ⇒ Object (readonly)

Returns the value of attribute window_size.



27
28
29
 
# File 'lib/cabriolet/decompressors/quantum.rb', line 27

def window_size
  @window_size
end

Instance Method Details

#decompress(bytes) ⇒ Integer

Decompress Quantum data

Parameters:

  • bytes (Integer) —

    Number of bytes to decompress

Returns:

  • (Integer) —

    Number of bytes decompressed



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/cabriolet/decompressors/quantum.rb', line 86

def decompress(bytes)
  return 0 if bytes <= 0

  output_data = String.new(capacity: bytes)
  bytes_todo = bytes

  while bytes_todo.positive?
    # Read header if needed (initializes C register)
    read_frame_header unless @header_read

    # Calculate how much to decode this iteration
    frame_end = @window_posn + [bytes_todo, @frame_todo,
                                @window_size - @window_posn].min

    # Decode symbols
    while @window_posn < frame_end
      selector = decode_symbol(@model7)

      if selector < 4
        # Literal byte from one of 4 models
        model = case selector
                when 0 then @model0
                when 1 then @model1
                when 2 then @model2
                else @model3
                end

        sym = decode_symbol(model)
        @window.setbyte(@window_posn, sym)
        @window_posn += 1
        @frame_todo -= 1
      else
        # Match
        match_offset, match_length = decode_match(selector)

        # Validate match doesn't exceed frame or window
        if @window_posn + match_length > @window_size
          raise DecompressionError,
                "Match exceeds window boundary"
        end

        @frame_todo -= match_length

        # Copy match
        copy_match(match_offset, match_length)
      end
    end

    # Extract decoded bytes for output
    output_amount = [@window_posn, bytes_todo].min
    output_data << @window[0, output_amount]
    bytes_todo -= output_amount

    # Handle frame completion
    if @frame_todo.zero?
      # Re-align to byte boundary
      @bitstream.byte_align

      # Skip trailer bytes until 0xFF
      loop do
        byte = @bitstream.read_bits(8)
        break if byte == 0xFF
      end

      @header_read = false
      @frame_todo = FRAME_SIZE
    end

    # Handle window wrap
    @window_posn = 0 if @window_posn == @window_size
  end

  # Write output
  io_system.write(output, output_data)
  bytes
end

#free ⇒ void

This method returns an undefined value.

Free resources used by the decompressor

Releases memory buffers to prevent memory leaks when the decompressor is no longer needed.



73
74
75
76
77
78
79
80
 
# File 'lib/cabriolet/decompressors/quantum.rb', line 73

def free
  @window = nil
  @bitstream = nil
  @m0sym = @m1sym = @m2sym = @m3sym = nil
  @m4sym = @m5sym = @m6sym = @m6lsym = nil
  @model0 = @model1 = @model2 = @model3 = nil
  @model4 = @model5 = @model6 = @model6len = nil
end