texel 0.1.0

data/lib/texel/codec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Texel
+  class Codec
+    class << self
+      def can_decode?(_format)
+        false
+      end
+
+      def can_encode?(_format)
+        false
+      end
+
+      def decode(_bytes, **)
+        raise NotImplementedError
+      end
+
+      def info(_bytes, **)
+        raise NotImplementedError
+      end
+
+      def encode(_image, _format, **)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/texel/codecs/qoi.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Texel
+  module Codecs
+    class Qoi < Codec
+      MAGIC = "qoif".b
+      END_MARKER = "\0\0\0\0\0\0\0\1".b
+      HEADER_SIZE = 14
+      INDEX_SIZE = 64
+      MAX_PIXELS = 1 << 28
+
+      class << self
+        def can_decode?(format)
+          format == :qoi
+        end
+
+        def can_encode?(format)
+          format == :qoi
+        end
+
+        def info(bytes, format: :qoi, **)
+          width, height, channels, = parse_header(bytes)
+          Info.new(width: width, height: height, channels: channels, format: format)
+        end
+
+        def decode(bytes, channels: nil, dtype: nil, **)
+          width, height, source_channels, color_space = parse_header(bytes)
+          rgba = decode_pixels(bytes, width * height)
+          image = Image.new(
+            width: width,
+            height: height,
+            channels: 4,
+            dtype: :u8,
+            color_space: color_space,
+            data: rgba
+          )
+          image.convert(channels: channels || source_channels, dtype: dtype || :u8)
+        rescue DecodeError
+          raise
+        rescue StandardError => e
+          raise DecodeError, "invalid QOI image: #{e.message}"
+        end
+
+        def encode(image, _format = :qoi, **)
+          prepared = prepare_image(image)
+          output = MAGIC + [prepared.width, prepared.height].pack("N2") +
+            [prepared.channels, prepared.color_space == :linear ? 1 : 0].pack("C2")
+          encode_pixels(prepared, output)
+          output << END_MARKER
+        rescue EncodeError
+          raise
+        rescue StandardError => e
+          raise EncodeError, "could not encode QOI image: #{e.message}"
+        end
+
+        private
+
+        def parse_header(bytes)
+          unless bytes.bytesize >= HEADER_SIZE + END_MARKER.bytesize && bytes.start_with?(MAGIC)
+            raise DecodeError, "invalid QOI header"
+          end
+
+          width, height = bytes.byteslice(4, 8).unpack("N2")
+          channels, color_space = bytes.byteslice(12, 2).unpack("C2")
+          raise DecodeError, "QOI dimensions must be positive" unless width.positive? && height.positive?
+          raise DecodeError, "QOI dimensions are too large" if width * height > MAX_PIXELS
+          raise DecodeError, "QOI channels must be 3 or 4" unless [3, 4].include?(channels)
+          raise DecodeError, "invalid QOI color space tag" unless [0, 1].include?(color_space)
+
+          [width, height, channels, color_space.zero? ? :srgb : :linear]
+        end
+
+        def decode_pixels(bytes, pixel_count)
+          index = Array.new(INDEX_SIZE) { [0, 0, 0, 0] }
+          pixel = [0, 0, 0, 255]
+          output = String.new(capacity: [pixel_count * 4, 1 << 20].min, encoding: Encoding::BINARY)
+          offset = HEADER_SIZE
+          run = 0
+
+          pixel_count.times do
+            if run.positive?
+              run -= 1
+            else
+              pixel, offset, run = decode_opcode(bytes, offset, pixel, index)
+            end
+            index[pixel_hash(pixel)] = pixel.dup
+            pixel.each { |component| output << component }
+          end
+          raise DecodeError, "QOI run exceeds the declared pixel count" if run.positive?
+
+          validate_trailer!(bytes, offset)
+          output.freeze
+        end
+
+        def decode_opcode(bytes, offset, previous, index)
+          byte = byte_at!(bytes, offset)
+          offset += 1
+          return decode_rgb(bytes, offset, previous) if byte == 0xfe
+          return decode_rgba(bytes, offset) if byte == 0xff
+
+          case byte & 0xc0
+          when 0x00 then [index.fetch(byte & 0x3f).dup, offset, 0]
+          when 0x40 then [decode_diff(byte, previous), offset, 0]
+          when 0x80 then decode_luma(bytes, offset, byte, previous)
+          when 0xc0 then [previous, offset, byte & 0x3f]
+          end
+        end
+
+        def decode_rgb(bytes, offset, previous)
+          rgb = bytes.byteslice(offset, 3)&.bytes
+          raise DecodeError, "truncated QOI RGB opcode" unless rgb&.length == 3
+
+          [[*rgb, previous[3]], offset + 3, 0]
+        end
+
+        def decode_rgba(bytes, offset)
+          rgba = bytes.byteslice(offset, 4)&.bytes
+          raise DecodeError, "truncated QOI RGBA opcode" unless rgba&.length == 4
+
+          [rgba, offset + 4, 0]
+        end
+
+        def decode_diff(byte, previous)
+          [
+            (previous[0] + (((byte >> 4) & 0x03) - 2)) & 0xff,
+            (previous[1] + (((byte >> 2) & 0x03) - 2)) & 0xff,
+            (previous[2] + ((byte & 0x03) - 2)) & 0xff,
+            previous[3]
+          ]
+        end
+
+        def decode_luma(bytes, offset, byte, previous)
+          second = byte_at!(bytes, offset)
+          green_difference = (byte & 0x3f) - 32
+          red_difference = green_difference + ((second >> 4) - 8)
+          blue_difference = green_difference + ((second & 0x0f) - 8)
+          pixel = [
+            (previous[0] + red_difference) & 0xff,
+            (previous[1] + green_difference) & 0xff,
+            (previous[2] + blue_difference) & 0xff,
+            previous[3]
+          ]
+          [pixel, offset + 1, 0]
+        end
+
+        def validate_trailer!(bytes, offset)
+          trailer = bytes.byteslice(offset, END_MARKER.bytesize)
+          raise DecodeError, "invalid or missing QOI end marker" unless trailer == END_MARKER
+          return if offset + END_MARKER.bytesize == bytes.bytesize
+
+          raise DecodeError, "unexpected data after QOI end marker"
+        end
+
+        def byte_at!(bytes, offset)
+          bytes.getbyte(offset) || raise(DecodeError, "truncated QOI pixel data")
+        end
+
+        def prepare_image(image)
+          channels = [3, 4].include?(image.channels) ? image.channels : 4
+          image.convert(channels: channels, dtype: :u8)
+        end
+
+        def encode_pixels(image, output)
+          index = Array.new(INDEX_SIZE) { [0, 0, 0, 0] }
+          previous = [0, 0, 0, 255]
+          run = 0
+          pixel_count = image.width * image.height
+
+          pixel_count.times do |pixel_index|
+            offset = pixel_index * image.channels
+            pixel = image.channels.times.map { |channel| image.data.getbyte(offset + channel) }
+            pixel << 255 if image.channels == 3
+            if pixel == previous
+              run += 1
+              if run == 62 || pixel_index == pixel_count - 1
+                output << (0xc0 | (run - 1))
+                run = 0
+              end
+              next
+            end
+
+            if run.positive?
+              output << (0xc0 | (run - 1))
+              run = 0
+            end
+            encode_pixel(output, pixel, previous, index)
+            index[pixel_hash(pixel)] = pixel
+            previous = pixel
+          end
+        end
+
+        def encode_pixel(output, pixel, previous, index)
+          index_position = pixel_hash(pixel)
+          if index[index_position] == pixel
+            output << index_position
+          elsif pixel[3] != previous[3]
+            output << 0xff << pixel.pack("C4")
+          else
+            encode_rgb_difference(output, pixel, previous)
+          end
+        end
+
+        def encode_rgb_difference(output, pixel, previous)
+          red = pixel[0] - previous[0]
+          green = pixel[1] - previous[1]
+          blue = pixel[2] - previous[2]
+          if [red, green, blue].all? { |difference| difference.between?(-2, 1) }
+            output << (0x40 | ((red + 2) << 4) | ((green + 2) << 2) | (blue + 2))
+            return
+          end
+
+          red_green = red - green
+          blue_green = blue - green
+          if green.between?(-32, 31) && red_green.between?(-8, 7) && blue_green.between?(-8, 7)
+            output << (0x80 | (green + 32)) << (((red_green + 8) << 4) | (blue_green + 8))
+            return
+          end
+
+          output << 0xfe << pixel.first(3).pack("C3")
+        end
+
+        def pixel_hash(pixel)
+          ((pixel[0] * 3) + (pixel[1] * 5) + (pixel[2] * 7) + (pixel[3] * 11)) % INDEX_SIZE
+        end
+      end
+    end
+  end
+end

data/lib/texel/codecs/stb.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Texel
+  module Codecs
+    class Stb < Codec
+      DECODE_FORMATS = %i[png jpg jpeg bmp tga gif psd hdr].freeze
+      ENCODE_FORMATS = %i[png jpg jpeg bmp tga hdr].freeze
+
+      class << self
+        def can_decode?(format)
+          DECODE_FORMATS.include?(format) && Native.available?
+        end
+
+        def can_encode?(format)
+          ENCODE_FORMATS.include?(format) && Native.available?
+        end
+
+        def info(bytes, format:, **)
+          width, height, channels, = metadata(bytes)
+          Info.new(width: width, height: height, channels: channels, format: format)
+        end
+
+        def decode(bytes, channels: nil, dtype: nil, format:, **)
+          width, height, source_channels, sixteen_bit, hdr = metadata(bytes)
+          target_channels = channels || source_channels
+          target_dtype = dtype || default_dtype(sixteen_bit, hdr)
+          storage_dtype = if hdr
+                            :f32
+                          elsif target_dtype == :f32
+                            sixteen_bit ? :u16 : :u8
+                          else
+                            target_dtype
+                          end
+          data = Native.decode(bytes, target_channels, storage_dtype)
+          image = Image.new(
+            width: width,
+            height: height,
+            channels: target_channels,
+            dtype: storage_dtype,
+            color_space: hdr || format == :hdr ? :linear : :srgb,
+            data: data
+          )
+          image.convert(dtype: target_dtype)
+        rescue Native::OperationError => e
+          raise DecodeError, "could not decode #{format.to_s.upcase}: #{e.message}"
+        end
+
+        def encode(image, format, quality: 90, **)
+          format = :jpg if format == :jpeg
+          validate_quality!(quality) if format == :jpg
+          prepared = prepare_for_encoding(image, format)
+          Native.encode(
+            prepared.data, format, prepared.width, prepared.height, prepared.channels,
+            prepared.dtype, format == :png ? prepared.row_bytes : quality
+          )
+        rescue Native::OperationError => e
+          raise EncodeError, "could not encode #{format.to_s.upcase}: #{e.message}"
+        end
+
+        private
+
+        def metadata(bytes)
+          width, height, channels, sixteen_bit, hdr = Native.metadata(bytes)
+          raise Native::OperationError, "unsupported or corrupt image" unless width.positive? && height.positive?
+
+          [width, height, channels, sixteen_bit, hdr]
+        end
+
+        def default_dtype(sixteen_bit, hdr)
+          return :f32 if hdr
+          return :u16 if sixteen_bit
+
+          :u8
+        end
+
+        def prepare_for_encoding(image, format)
+          if format == :hdr
+            prepared = image.convert(dtype: :f32)
+            return prepared unless [2, 4].include?(prepared.channels)
+
+            return prepared.convert(channels: prepared.channels - 1)
+          end
+          if image.dtype == :u16
+            raise FormatError, "stb_image_write cannot encode 16-bit #{format.to_s.upcase}; convert to :u8 first"
+          end
+
+          prepared = image.convert(dtype: :u8)
+          if format == :bmp && prepared.channels == 2
+            return prepared.convert(channels: 4)
+          end
+          return prepared unless format == :jpg && [2, 4].include?(prepared.channels)
+
+          prepared.convert(channels: prepared.channels == 2 ? 1 : 3)
+        end
+
+        def validate_quality!(quality)
+          return if quality.is_a?(Integer) && quality.between?(1, 100)
+
+          raise FormatError, "JPEG quality must be an integer between 1 and 100"
+        end
+      end
+    end
+  end
+end

data/lib/texel/color_transform.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Texel
+  module ColorTransform
+    SRGB_TO_LINEAR_LUT = Array.new(256) do |index|
+      channel = index / 255.0
+      channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055)**2.4
+    end.freeze
+    LINEAR_TO_SRGB_LUT = Array.new(4096) do |index|
+      channel = index / 4095.0
+      channel <= 0.0031308 ? 12.92 * channel : (1.055 * (channel**(1.0 / 2.4))) - 0.055
+    end.freeze
+
+    module_function
+
+    def linearize(image)
+      validate_color_space!(image, :srgb, :linear)
+      return image.convert(dtype: :f32).dup_with(color_space: :linear) if image.color_space == :linear
+
+      source = PixelData.unpack(image.data, image.dtype)
+      result = source.each_with_index.map do |value, index|
+        normalized = PixelData.normalize(value, image.dtype)
+        alpha_channel?(index, image.channels) ? normalized : srgb_to_linear(normalized, image.dtype, value)
+      end
+      image.dup_with(data: PixelData.pack(result, :f32), dtype: :f32, color_space: :linear)
+    end
+
+    def delinearize(image, dtype: :u8)
+      validate_color_space!(image, :linear, :srgb)
+      return image.convert(dtype: dtype).dup_with(color_space: :srgb) if image.color_space == :srgb
+
+      source = PixelData.unpack(image.data, image.dtype)
+      result = source.each_with_index.map do |value, index|
+        normalized = PixelData.normalize(value, image.dtype)
+        converted = alpha_channel?(index, image.channels) ? normalized : linear_to_srgb(normalized)
+        PixelData.denormalize(converted, dtype)
+      end
+      image.dup_with(data: PixelData.pack(result, dtype), dtype: dtype, color_space: :srgb)
+    end
+
+    def srgb_to_linear(channel, dtype = :f32, raw_value = nil)
+      return SRGB_TO_LINEAR_LUT.fetch(raw_value) if dtype == :u8 && raw_value
+
+      channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055)**2.4
+    end
+
+    def linear_to_srgb(channel)
+      LINEAR_TO_SRGB_LUT.fetch((channel.clamp(0.0, 1.0) * 4095).round)
+    end
+
+    def alpha_channel?(flat_index, channels)
+      (channels == 2 || channels == 4) && (flat_index % channels == channels - 1)
+    end
+    private_class_method :alpha_channel?
+
+    def validate_color_space!(image, source, destination)
+      return if [source, destination].include?(image.color_space)
+
+      raise FormatError, "cannot convert #{image.color_space.inspect} pixels from #{source} to #{destination}"
+    end
+    private_class_method :validate_color_space!
+  end
+end

data/lib/texel/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Texel
+  class Error < StandardError; end
+  class DecodeError < Error; end
+  class EncodeError < Error; end
+  class FormatError < Error; end
+  class MissingCodecError < Error; end
+end

data/lib/texel/gl.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../texel"
+
+module Texel
+  module GL
+    Format = Data.define(:internal_format, :format, :type)
+    CHANNEL_FORMATS = {
+      1 => :red,
+      2 => :rg,
+      3 => :rgb,
+      4 => :rgba
+    }.freeze
+    INTERNAL_FORMATS = {
+      u8: { 1 => :r8, 2 => :rg8, 3 => :rgb8, 4 => :rgba8 },
+      u16: { 1 => :r16, 2 => :rg16, 3 => :rgb16, 4 => :rgba16 },
+      f32: { 1 => :r32f, 2 => :rg32f, 3 => :rgb32f, 4 => :rgba32f }
+    }.freeze
+    TYPES = { u8: :unsigned_byte, u16: :unsigned_short, f32: :float }.freeze
+
+    module_function
+
+    def format(image)
+      raise FormatError, "expected a Texel::Image" unless image.is_a?(Image)
+
+      internal = INTERNAL_FORMATS.fetch(image.dtype).fetch(image.channels)
+      internal = :srgb8 if image.dtype == :u8 && image.color_space == :srgb && image.channels == 3
+      internal = :srgb8_alpha8 if image.dtype == :u8 && image.color_space == :srgb && image.channels == 4
+      Format.new(
+        internal_format: internal,
+        format: CHANNEL_FORMATS.fetch(image.channels),
+        type: TYPES.fetch(image.dtype)
+      ).freeze
+    end
+  end
+end

data/lib/texel/half_float.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Texel
+  module HalfFloat
+    module_function
+
+    def pack(f32_data)
+      return Native.pack_f16(f32_data) if Native.available?
+
+      f32_data.unpack("e*").map { |value| bits(value) }.pack("S<*").b
+    rescue Native::OperationError => e
+      raise FormatError, "f16 conversion failed: #{e.message}"
+    end
+
+    def bits(value)
+      input = [value].pack("e").unpack1("L<")
+      sign = (input >> 16) & 0x8000
+      exponent = (input >> 23) & 0xff
+      mantissa = input & 0x7fffff
+      return sign | (mantissa.zero? ? 0x7c00 : 0x7e00) if exponent == 0xff
+
+      half_exponent = exponent - 127 + 15
+      return sign | 0x7c00 if half_exponent >= 31
+      return subnormal_bits(sign, mantissa, half_exponent) if half_exponent <= 0
+
+      normal_bits(sign, mantissa, half_exponent)
+    end
+
+    def subnormal_bits(sign, mantissa, exponent)
+      return sign if exponent < -10
+
+      mantissa |= 0x800000
+      shift = 14 - exponent
+      half_mantissa = mantissa >> shift
+      remainder = mantissa & ((1 << shift) - 1)
+      halfway = 1 << (shift - 1)
+      half_mantissa += 1 if remainder > halfway || (remainder == halfway && half_mantissa.odd?)
+      sign | half_mantissa
+    end
+    private_class_method :subnormal_bits
+
+    def normal_bits(sign, mantissa, exponent)
+      half_mantissa = mantissa >> 13
+      remainder = mantissa & 0x1fff
+      if remainder > 0x1000 || (remainder == 0x1000 && half_mantissa.odd?)
+        half_mantissa += 1
+        if half_mantissa == 0x400
+          half_mantissa = 0
+          exponent += 1
+          return sign | 0x7c00 if exponent >= 31
+        end
+      end
+      sign | (exponent << 10) | half_mantissa
+    end
+    private_class_method :normal_bits
+  end
+end

data/lib/texel/image.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Texel
+  class Image
+    DTYPE_SIZES = { u8: 1, u16: 2, f32: 4 }.freeze
+    COLOR_SPACES = %i[srgb linear unknown].freeze
+    DUPLICABLE_TAGS = %i[width height channels dtype color_space premultiplied].freeze
+
+    attr_reader :width, :height, :channels, :dtype, :color_space, :data, :premultiplied
+
+    def initialize(width:, height:, channels:, dtype:, color_space:, data:, premultiplied: false)
+      validate_dimensions!(width, height)
+      validate_channels!(channels)
+      validate_dtype!(dtype)
+      validate_color_space!(color_space)
+
+      @width = width
+      @height = height
+      @channels = channels
+      @dtype = dtype
+      @color_space = color_space
+      source = String(data)
+      @data = if source.encoding == Encoding::BINARY && source.frozen?
+                source
+              else
+                source.dup.force_encoding(Encoding::BINARY).freeze
+              end
+      @premultiplied = !!premultiplied
+      validate_data_size!
+    end
+
+    def bytesize_per_pixel
+      channels * DTYPE_SIZES.fetch(dtype)
+    end
+
+    def row_bytes
+      width * bytesize_per_pixel
+    end
+
+    def pixel(x, y)
+      unless x.is_a?(Integer) && y.is_a?(Integer) && x.between?(0, width - 1) && y.between?(0, height - 1)
+        raise IndexError, "pixel coordinates (#{x}, #{y}) are outside #{width}x#{height} image"
+      end
+
+      byte_offset = ((y * width) + x) * bytesize_per_pixel
+      bytes = data.byteslice(byte_offset, bytesize_per_pixel)
+      PixelData.unpack(bytes, dtype)
+    end
+
+    def dup_with(data: nil, **tags)
+      unknown_tags = tags.keys - DUPLICABLE_TAGS
+      raise ArgumentError, "unknown image tags: #{unknown_tags.join(", ")}" unless unknown_tags.empty?
+
+      self.class.new(
+        width: tags.fetch(:width, width),
+        height: tags.fetch(:height, height),
+        channels: tags.fetch(:channels, channels),
+        dtype: tags.fetch(:dtype, dtype),
+        color_space: tags.fetch(:color_space, color_space),
+        data: data || self.data,
+        premultiplied: tags.fetch(:premultiplied, premultiplied)
+      )
+    end
+
+    def premultiplied?
+      premultiplied
+    end
+
+    def premultiplied=(value)
+      @premultiplied = !!value
+    end
+
+    private
+
+    def validate_dimensions!(image_width, image_height)
+      return if image_width.is_a?(Integer) && image_width.positive? && image_height.is_a?(Integer) && image_height.positive?
+
+      raise FormatError, "image dimensions must be positive integers"
+    end
+
+    def validate_channels!(image_channels)
+      return if image_channels.is_a?(Integer) && image_channels.between?(1, 4)
+
+      raise FormatError, "channels must be between 1 and 4"
+    end
+
+    def validate_dtype!(image_dtype)
+      return if DTYPE_SIZES.key?(image_dtype)
+
+      raise FormatError, "unsupported dtype #{image_dtype.inspect}; expected :u8, :u16, or :f32"
+    end
+
+    def validate_color_space!(space)
+      return if COLOR_SPACES.include?(space)
+
+      raise FormatError, "unsupported color space #{space.inspect}"
+    end
+
+    def validate_data_size!
+      expected = width * height * bytesize_per_pixel
+      return if data.bytesize == expected
+
+      raise FormatError, "pixel data is #{data.bytesize} bytes; expected #{expected} bytes"
+    end
+  end
+end