libpng 1.6.58.4-aarch64-linux-ohos

data/lib/libpng/simplified_decoder.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Decodes a PNG byte buffer into raw pixels via libpng's "simplified"
+  # read API (png_image_begin_read_from_memory + png_image_finish_read).
+  #
+  # Also parses the byte buffer via ChunkWalker to populate
+  # DecodedImage#bit_depth, #color_type, #interlace (from IHDR),
+  # #text (from tEXt/zTXt/iTXt), and #color (from gAMA/cHRM/sRGB/iCCP).
+  # The simplified API itself drops these ancillary chunks on read --
+  # walking them separately is the only way to surface their content.
+  #
+  # One instance per decode call. Ractor-safe.
+  class SimplifiedDecoder
+    def initialize(png, pixel_format: 'RGBA')
+      raise Error, 'input PNG buffer is nil' if png.nil?
+      raise Error, 'input PNG buffer must be a String' unless png.is_a?(String)
+
+      @png = png
+      @pixel_format = pixel_format
+      raise Error, "unknown pixel_format #{@pixel_format.inspect}" unless format_value
+    end
+
+    # Returns a Libpng::DecodedImage.
+    def call
+      fmt = format_value
+      img = FFI::MemoryPointer.new(:uint8, PNG_IMAGE_SIZE)
+      img.clear
+      img.put_uint32(PNG_IMAGE_OFF_VERSION, PNG_IMAGE_VERSION)
+
+      FFI::MemoryPointer.new(:uint8, @png.bytesize) do |in_buf|
+        in_buf.write_bytes(@png)
+        ok = Libpng::Binding.png_image_begin_read_from_memory(img, in_buf, @png.bytesize)
+        raise Error, "png_image_begin_read_from_memory failed: #{read_message(img)}" if ok.zero?
+
+        img.put_uint32(PNG_IMAGE_OFF_FORMAT, fmt)
+        width = img.get_uint32(PNG_IMAGE_OFF_WIDTH)
+        height = img.get_uint32(PNG_IMAGE_OFF_HEIGHT)
+        stride = width * BytesPerPixel.for_format(fmt)
+        out_size = stride * height
+
+        FFI::MemoryPointer.new(:uint8, out_size) do |out_buf|
+          ok = Libpng::Binding.png_image_finish_read(img, nil, out_buf, stride, nil)
+          raise Error, "png_image_finish_read failed: #{read_message(img)}" if ok.zero?
+
+          return DecodedImage.new(
+            width: width,
+            height: height,
+            format: @pixel_format.to_s.upcase,
+            pixels: out_buf.read_bytes(out_size),
+            **walker_metadata
+          )
+        end
+      end
+    ensure
+      Libpng::Binding.png_image_free(img) unless img.nil? || img.null?
+    end
+
+    private
+
+    def format_value
+      FORMAT_BY_NAME[@pixel_format.to_s.upcase]
+    end
+
+    # Walks the PNG once via ChunkWalker to gather all metadata fields
+    # the simplified API does not surface. Each accessor is best-effort:
+    # a malformed IHDR or text chunk should not poison the rest of the
+    # decode -- empty Hashes / nil values are acceptable fall-throughs.
+    def walker_metadata
+      walker = ChunkWalker.new(@png)
+      ihdr = safe_ihdr(walker)
+      {
+        bit_depth: ihdr[:bit_depth],
+        color_type: ihdr[:color_type],
+        interlace: ihdr[:interlace],
+        text: safe_text(walker),
+        color: safe_color(walker)
+      }
+    end
+
+    def safe_ihdr(walker)
+      walker.ihdr_fields
+    rescue ChunkWalker::FormatError
+      {}
+    end
+
+    def safe_text(walker)
+      walker.text_chunks
+    rescue ChunkWalker::FormatError
+      {}
+    end
+
+    def safe_color(walker)
+      walker.color_chunks
+    rescue ChunkWalker::FormatError
+      {}
+    end
+
+    def read_message(img)
+      s = img.get_bytes(PNG_IMAGE_OFF_MESSAGE, PNG_IMAGE_MESSAGE_BYTES)
+      s = s.split("\x00").first || ''
+      s.empty? ? '(no message)' : s.force_encoding('UTF-8')
+    rescue StandardError
+      '(no message)'
+    end
+  end
+end

data/lib/libpng/simplified_encoder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Encodes raw pixel data as a PNG via libpng's "simplified" write API
+  # (png_image_write_to_memory). By default the output is then walked
+  # chunk-by-chunk to strip the sRGB/gAMA/cHRM/iCCP chunks the
+  # simplified API emits -- this matches the byte layout of the
+  # classic libpng write path (libemf2svg's rgb2png).
+  #
+  # One instance per encode call. Ractor-safe: no shared mutable state.
+  class SimplifiedEncoder
+    def initialize(width, height, pixels,
+                   pixel_format: 'RGBA',
+                   convert_to_8bit: false,
+                   strip_colorspace: true)
+      @width = width
+      @height = height
+      @pixels = pixels
+      @pixel_format = pixel_format
+      @convert_to_8bit = convert_to_8bit
+      @strip_colorspace = strip_colorspace
+      validate!
+    end
+
+    # Returns a binary String of PNG file bytes.
+    def call
+      raw = write_via_simplified_api
+      @strip_colorspace ? ChunkWalker.new(raw).strip_ancillary : raw
+    end
+
+    private
+
+    def validate!
+      raise Error, 'width must be positive' unless @width.positive?
+      raise Error, 'height must be positive' unless @height.positive?
+      raise Error, "unknown pixel_format #{@pixel_format.inspect}" unless format_value
+      return unless @pixels.bytesize < expected_size
+
+      raise Error,
+            "pixels too short: expected #{expected_size}, got #{@pixels.bytesize}"
+    end
+
+    def format_value
+      FORMAT_BY_NAME[@pixel_format.to_s.upcase]
+    end
+
+    def bytes_per_pixel
+      BytesPerPixel.for_format(format_value)
+    end
+
+    def expected_size
+      @width * bytes_per_pixel * @height
+    end
+
+    def write_via_simplified_api
+      img = FFI::MemoryPointer.new(:uint8, PNG_IMAGE_SIZE)
+      img.clear
+      img.put_uint32(PNG_IMAGE_OFF_VERSION, PNG_IMAGE_VERSION)
+      img.put_uint32(PNG_IMAGE_OFF_WIDTH, @width)
+      img.put_uint32(PNG_IMAGE_OFF_HEIGHT, @height)
+      img.put_uint32(PNG_IMAGE_OFF_FORMAT, format_value)
+
+      stride = @width * bytes_per_pixel
+      out_len_ptr = FFI::MemoryPointer.new(:size_t, 1)
+      ok = Libpng::Binding.png_image_write_to_memory(img, nil, out_len_ptr,
+                                                     @convert_to_8bit ? 1 : 0,
+                                                     @pixels, stride, nil)
+      if ok.zero?
+        msg = read_message(img)
+        Libpng::Binding.png_image_free(img)
+        raise Error, "png_image_write_to_memory (size query) failed: #{msg}"
+      end
+
+      out_len = out_len_ptr.read_uint64
+      raise Error, 'libpng reported zero-length PNG output' if out_len.zero?
+
+      buffer = FFI::MemoryPointer.new(:uint8, out_len)
+      ok = Libpng::Binding.png_image_write_to_memory(img, buffer, out_len_ptr,
+                                                     @convert_to_8bit ? 1 : 0,
+                                                     @pixels, stride, nil)
+      if ok.zero?
+        msg = read_message(img)
+        Libpng::Binding.png_image_free(img)
+        raise Error, "png_image_write_to_memory (write) failed: #{msg}"
+      end
+
+      buffer.read_bytes(out_len).tap { Libpng::Binding.png_image_free(img) }
+    end
+
+    def read_message(img)
+      s = img.get_bytes(PNG_IMAGE_OFF_MESSAGE, PNG_IMAGE_MESSAGE_BYTES)
+      s = s.split("\x00").first || ''
+      s.empty? ? '(no message)' : s.force_encoding('UTF-8')
+    rescue StandardError
+      '(no message)'
+    end
+  end
+end

data/lib/libpng/standard_encoder.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Encodes raw pixel data via libpng's standard write API
+  # (png_create_write_struct -> png_set_IHDR -> png_set_rows ->
+  # png_write_png(PNG_TRANSFORM_IDENTITY)). This matches the byte
+  # output of the "classic" libpng write path used by libemf2svg's
+  # rgb2png, and avoids the sRGB/gAMA chunks the simplified API
+  # injects by default.
+  #
+  # Options:
+  #   pixel_format:     :gray, :ga, :rgb, :rgba, or :palette
+  #   filter:           :default (adaptive), :none, :sub, :up, :avg,
+  #                     :paeth, :all, :adaptive
+  #   compression_level: 0..9 (default 6 = Z_DEFAULT_COMPRESSION)
+  #   interlace:        :none or :adam7 (default :none)
+  #   bit_depth:        8 or 16 (default 8; ignored for :palette which
+  #                     is always 8)
+  #   palette:          Array of [r, g, b] or [r, g, b, a] for
+  #                     pixel_format: :palette. 1..256 entries.
+  #
+  # One instance per encode call. Ractor-safe.
+  class StandardEncoder
+    def initialize(width, height, pixels,
+                   pixel_format: 'RGBA',
+                   filter: :default,
+                   compression_level: 6,
+                   interlace: :none,
+                   bit_depth: 8,
+                   palette: nil)
+      @width = width
+      @height = height
+      @pixels = pixels
+      @pixel_format_sym = coerce_pixel_format(pixel_format)
+      @filter_sym = filter.to_sym
+      @compression_level = compression_level
+      @interlace_sym = interlace.to_sym
+      @bit_depth = bit_depth
+      @palette = palette
+      validate!
+    end
+
+    # Returns a binary String of PNG file bytes.
+    def call
+      output = String.new.force_encoding('ASCII-8BIT')
+      callbacks = CallbackSet.new(output)
+
+      png_ptr = FFI::Pointer.new(0)
+      info_ptr = FFI::Pointer.new(0)
+      begin
+        png_ptr = Libpng::Binding.png_create_write_struct(LIBPNG_VER_STRING_C, nil, callbacks.error_fn, nil)
+        raise Error, 'png_create_write_struct returned NULL' if png_ptr.null?
+
+        info_ptr = Libpng::Binding.png_create_info_struct(png_ptr)
+        raise Error, 'png_create_info_struct returned NULL' if info_ptr.null?
+
+        apply_compression(png_ptr)
+        Libpng::Binding.png_set_write_fn(png_ptr, nil, callbacks.write_fn, nil)
+        Libpng::Binding.png_set_IHDR(png_ptr, info_ptr, @width, @height, effective_bit_depth,
+                                     color_type, interlace_method,
+                                     COMPRESSION_TYPE_DEFAULT, FILTER_TYPE_DEFAULT)
+        apply_filter(png_ptr)
+        apply_palette(png_ptr, info_ptr) if palette_format?
+
+        FFI::MemoryPointer.new(:uint8, @pixels.bytesize) do |px|
+          px.write_bytes(@pixels)
+          FFI::MemoryPointer.new(:pointer, @height) do |rows|
+            @height.times do |y|
+              rows.put_pointer(y * FFI.type_size(:pointer), px + (y * stride))
+            end
+            Libpng::Binding.png_set_rows(png_ptr, info_ptr, rows)
+            Libpng::Binding.png_write_png(png_ptr, info_ptr, TRANSFORM_IDENTITY, nil)
+          end
+        end
+
+        output
+      ensure
+        destroy(png_ptr, info_ptr)
+      end
+    end
+
+    private
+
+    # Holds FFI::Function callbacks alive for the duration of the
+    # libpng calls. FFI::Function objects are GC'd when no Ruby
+    # reference remains; libpng stores the raw function pointer but
+    # has no idea the underlying Ruby object needs to stay alive.
+    class CallbackSet
+      attr_reader :write_fn, :error_fn
+
+      def initialize(output_accumulator)
+        @write_fn = FFI::Function.new(:void, %i[pointer pointer size_t]) do |_, data, len|
+          output_accumulator << data.read_bytes(len)
+        end
+        @error_fn = FFI::Function.new(:void, %i[pointer string]) do |_, msg|
+          raise Error, "libpng: #{msg}"
+        end
+      end
+    end
+
+    def coerce_pixel_format(value)
+      sym = value.to_s.downcase.to_sym
+      raise Error, "unknown pixel_format #{value.inspect}" unless FORMAT_TO_COLOR_TYPE.key?(sym)
+
+      sym
+    end
+
+    def validate!
+      raise Error, 'width must be positive' unless @width.positive?
+      raise Error, 'height must be positive' unless @height.positive?
+      raise Error, "unknown filter #{@filter_sym.inspect}" unless FILTER_MASK_BY_NAME.key?(@filter_sym)
+      raise Error, 'compression_level must be 0..9' unless (0..9).cover?(@compression_level)
+      unless INTERLACE_BY_NAME.key?(@interlace_sym)
+        raise Error,
+              "unknown interlace #{@interlace_sym.inspect} (expected :none or :adam7)"
+      end
+
+      validate_bit_depth!
+      validate_palette! if palette_format?
+      return unless @pixels.bytesize < expected_size
+
+      raise Error,
+            "pixels too short: expected #{expected_size}, got #{@pixels.bytesize}"
+    end
+
+    def validate_bit_depth!
+      if palette_format?
+        raise Error, 'bit_depth must be 8 for palette format' unless @bit_depth == 8
+      elsif !%i[gray rgb rgba].include?(@pixel_format_sym)
+        # GA: only 8 supported here for now.
+        raise Error, 'bit_depth must be 8' unless @bit_depth == 8
+      elsif ![8, 16].include?(@bit_depth)
+        raise Error, "bit_depth must be 8 or 16, got #{@bit_depth.inspect}"
+      end
+    end
+
+    def validate_palette!
+      raise Error, 'palette format requires palette: option' if @palette.nil?
+      raise Error, 'palette must be an Array' unless @palette.is_a?(Array)
+      raise Error, 'palette must have 1..256 entries' unless (1..256).cover?(@palette.length)
+
+      @palette.each_with_index do |entry, i|
+        next if entry.is_a?(Array) && [3, 4].include?(entry.length) && entry.all? do |v|
+          v.is_a?(Integer) && v.between?(0, 255)
+        end
+
+        raise Error, "palette[#{i}] must be [r,g,b] or [r,g,b,a] with 0..255 values"
+      end
+    end
+
+    def palette_format?
+      @pixel_format_sym == :palette
+    end
+
+    def color_type
+      FORMAT_TO_COLOR_TYPE[@pixel_format_sym]
+    end
+
+    def effective_bit_depth
+      palette_format? ? 8 : @bit_depth
+    end
+
+    def interlace_method
+      INTERLACE_BY_NAME[@interlace_sym]
+    end
+
+    def stride
+      @width * bytes_per_pixel
+    end
+
+    def bytes_per_pixel
+      return 1 if palette_format?
+
+      BytesPerPixel.for_color_type(color_type, bit_depth: effective_bit_depth)
+    end
+
+    def expected_size
+      stride * @height
+    end
+
+    def apply_compression(png_ptr)
+      Libpng::Binding.png_set_compression_level(png_ptr, @compression_level)
+    end
+
+    def apply_filter(png_ptr)
+      mask = FILTER_MASK_BY_NAME[@filter_sym]
+      Libpng::Binding.png_set_filter(png_ptr, FILTER_HEURISTIC_DEFAULT, mask) if mask
+    end
+
+    def apply_palette(png_ptr, info_ptr)
+      pal = @palette
+      has_alpha = pal.any? { |e| e.length == 4 }
+      pal_bytes = pal.map { |e| e.first(3) }.flatten.pack('C*')
+      FFI::MemoryPointer.new(:uint8, pal_bytes.bytesize) do |pp|
+        pp.write_bytes(pal_bytes)
+        Libpng::Binding.png_set_PLTE(png_ptr, info_ptr, pp, pal.length)
+      end
+      return unless has_alpha
+
+      alpha_bytes = pal.map { |e| e[3] || 255 }.pack('C*')
+      FFI::MemoryPointer.new(:uint8, alpha_bytes.bytesize) do |ap|
+        ap.write_bytes(alpha_bytes)
+        Libpng::Binding.png_set_tRNS(png_ptr, info_ptr, ap, alpha_bytes.bytesize, nil)
+      end
+    end
+
+    def destroy(png_ptr, info_ptr)
+      return if png_ptr.null?
+
+      FFI::MemoryPointer.new(:pointer) do |pp|
+        pp.write_pointer(png_ptr)
+        FFI::MemoryPointer.new(:pointer) do |ip|
+          ip.write_pointer(info_ptr)
+          Libpng::Binding.png_destroy_write_struct(pp, ip)
+        end
+      end
+    end
+  end
+end

data/lib/libpng/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Gem version follows the pattern:
+  #
+  #   {LIBPNG_VERSION}.{LIBPNG_RUBY_ITERATION}
+  #
+  # where LIBPNG_VERSION is the upstream libpng release this gem is
+  # built against, and LIBPNG_RUBY_ITERATION is a counter for Ruby-side
+  # changes (recipe bug fixes, CI changes, docs) that bump without a
+  # new libpng release. The iteration resets to 0 each time
+  # LIBPNG_VERSION bumps.
+  LIBPNG_VERSION = '1.6.58'
+  LIBPNG_RUBY_ITERATION = 4
+  VERSION = "#{LIBPNG_VERSION}.#{LIBPNG_RUBY_ITERATION}"
+end

data/lib/libpng.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+# Libpng is a Ruby binding for libpng (the official PNG reference library)
+# via FFI. The native library is pre-compiled for each target platform and
+# shipped inside the gem, so no C compiler is required at install time.
+#
+# Public API:
+#   Libpng.encode(width, height, rgba_bytes, pixel_format: "RGBA")
+#   Libpng.encode_standard(width, height, rgba_bytes, pixel_format: "RGBA", ...)
+#   Libpng.decode(png_bytes, pixel_format: "RGBA")
+#
+# All encode/decode state is per-call. Each call constructs a dedicated
+# encoder or decoder instance, runs it, and discards it. Calls from
+# different Ractors do not share state. The FFI function table
+# (Libpng::Binding) loads lazily on first use and is shareable across
+# Ractors.
+module Libpng
+  # Version constants live in lib/libpng/version.rb. Autoloaded so the
+  # version file isn't loaded until someone references a version constant.
+  autoload :LIBPNG_VERSION, 'libpng/version'
+  autoload :LIBPNG_RUBY_ITERATION, 'libpng/version'
+  autoload :VERSION, 'libpng/version'
+
+  # Public-facing classes.
+  autoload :Error, 'libpng/error'
+  autoload :DecodedImage, 'libpng/decoded_image'
+  autoload :ChunkWalker, 'libpng/chunk_walker'
+  autoload :BytesPerPixel, 'libpng/bytes_per_pixel'
+  autoload :SimplifiedEncoder, 'libpng/simplified_encoder'
+  autoload :SimplifiedDecoder, 'libpng/simplified_decoder'
+  autoload :StandardEncoder, 'libpng/standard_encoder'
+
+  # FFI bindings. Autoloaded so that requiring `libpng` is cheap and
+  # does not dlopen libpng16.{so,dylib,dll} -- ext/extconf.rb needs to
+  # require 'libpng' to access Libpng::Recipe during the source-gem
+  # build, at which point the shared library doesn't exist yet.
+  autoload :Binding, 'libpng/binding'
+
+  # Build-time recipe (MiniPortile). Only loaded when ext/extconf.rb
+  # is invoked during `gem install` of the source ('ruby' platform) gem.
+  autoload :Recipe, 'libpng/recipe'
+
+  # ------------------------------------------------------------------
+  # PNG_IMAGE_FORMAT_* bit flags (png.h). Used by the simplified API.
+  # ------------------------------------------------------------------
+  FORMAT_FLAG_ALPHA             = 0x01
+  FORMAT_FLAG_COLOR             = 0x02
+  FORMAT_FLAG_LINEAR            = 0x04
+  FORMAT_FLAG_COLORMAP          = 0x08
+  FORMAT_FLAG_BGR               = 0x10
+  FORMAT_FLAG_AFIRST            = 0x20
+  FORMAT_FLAG_ASSOCIATED_ALPHA  = 0x40
+
+  FORMAT_GRAY = 0
+  FORMAT_GA   = FORMAT_FLAG_ALPHA
+  FORMAT_AG   = FORMAT_FLAG_ALPHA | FORMAT_FLAG_AFIRST
+  FORMAT_RGB  = FORMAT_FLAG_COLOR
+  FORMAT_BGR  = FORMAT_FLAG_COLOR | FORMAT_FLAG_BGR
+  FORMAT_RGBA = FORMAT_FLAG_COLOR | FORMAT_FLAG_ALPHA
+  FORMAT_ARGB = FORMAT_FLAG_COLOR | FORMAT_FLAG_ALPHA | FORMAT_FLAG_AFIRST
+  FORMAT_BGRA = FORMAT_FLAG_COLOR | FORMAT_FLAG_ALPHA | FORMAT_FLAG_BGR
+  FORMAT_ABGR = FORMAT_FLAG_COLOR | FORMAT_FLAG_ALPHA | FORMAT_FLAG_AFIRST | FORMAT_FLAG_BGR
+
+  FORMAT_BY_NAME = {
+    'GRAY' => FORMAT_GRAY,
+    'GRAYSCALE' => FORMAT_GRAY,
+    'GA' => FORMAT_GA,
+    'AG' => FORMAT_AG,
+    'RGB' => FORMAT_RGB,
+    'BGR' => FORMAT_BGR,
+    'RGBA' => FORMAT_RGBA,
+    'ARGB' => FORMAT_ARGB,
+    'BGRA' => FORMAT_BGRA,
+    'ABGR' => FORMAT_ABGR
+  }.freeze
+
+  # ------------------------------------------------------------------
+  # Standard-API color types (png.h).
+  # ------------------------------------------------------------------
+  COLOR_MASK_PALETTE = 0x01
+  COLOR_MASK_COLOR   = 0x02
+  COLOR_MASK_ALPHA   = 0x04
+
+  COLOR_TYPE_GRAY         = 0
+  COLOR_TYPE_PALETTE      = COLOR_MASK_COLOR | COLOR_MASK_PALETTE
+  COLOR_TYPE_RGB          = COLOR_MASK_COLOR
+  COLOR_TYPE_RGB_ALPHA    = COLOR_MASK_COLOR | COLOR_MASK_ALPHA
+  COLOR_TYPE_GRAY_ALPHA   = COLOR_MASK_ALPHA
+
+  FORMAT_TO_COLOR_TYPE = {
+    gray: COLOR_TYPE_GRAY,
+    ga: COLOR_TYPE_GRAY_ALPHA,
+    ag: COLOR_TYPE_GRAY_ALPHA,
+    rgb: COLOR_TYPE_RGB,
+    rgba: COLOR_TYPE_RGB_ALPHA,
+    palette: COLOR_TYPE_PALETTE
+  }.freeze
+
+  # ------------------------------------------------------------------
+  # png_set_IHDR pass-through constants (png.h).
+  # ------------------------------------------------------------------
+  INTERLACE_NONE            = 0
+  INTERLACE_ADAM7           = 1
+  COMPRESSION_TYPE_DEFAULT  = 0
+  FILTER_TYPE_DEFAULT       = 0
+  TRANSFORM_IDENTITY        = 0x0000
+
+  INTERLACE_BY_NAME = {
+    none: INTERLACE_NONE,
+    adam7: INTERLACE_ADAM7
+  }.freeze
+
+  # ------------------------------------------------------------------
+  # png_set_filter bitmask (PNG_FILTER_*).
+  # ------------------------------------------------------------------
+  FILTER_HEURISTIC_DEFAULT  = 0
+  FILTER_NONE               = 0x08
+  FILTER_SUB                = 0x10
+  FILTER_UP                 = 0x20
+  FILTER_AVG                = 0x40
+  FILTER_PAETH              = 0x80
+  FILTER_ALL                = FILTER_NONE | FILTER_SUB | FILTER_UP | FILTER_AVG | FILTER_PAETH
+
+  FILTER_MASK_BY_NAME = {
+    default: nil,
+    adaptive: FILTER_ALL,
+    none: FILTER_NONE,
+    sub: FILTER_SUB,
+    up: FILTER_UP,
+    avg: FILTER_AVG,
+    paeth: FILTER_PAETH,
+    all: FILTER_ALL
+  }.freeze
+
+  # PNG_LIBPNG_VER_STRING. The C string passed as `user_png_ver` to
+  # png_create_write_struct. libpng checks this against its compiled-in
+  # version; mismatches return NULL. Must match the libpng16 binary we
+  # ship, which is 1.6.58.
+  LIBPNG_VER_STRING_C = LIBPNG_VERSION
+
+  # ------------------------------------------------------------------
+  # png_image struct field offsets (bytes). Used by SimplifiedEncoder /
+  # SimplifiedDecoder to allocate the png_image struct via a raw
+  # FFI::MemoryPointer (rather than FFI::Struct, which has class-level
+  # state that isn't shareable across non-main Ractors).
+  # ------------------------------------------------------------------
+  PNG_IMAGE_VERSION = 1
+  PNG_IMAGE_MESSAGE_BYTES = 64
+  PNG_IMAGE_SIZE = FFI.type_size(:pointer) + (7 * 4) + PNG_IMAGE_MESSAGE_BYTES
+  PNG_IMAGE_OFF_OPAQUE = 0
+  PNG_IMAGE_OFF_VERSION = FFI.type_size(:pointer)
+  PNG_IMAGE_OFF_WIDTH = PNG_IMAGE_OFF_VERSION + 4
+  PNG_IMAGE_OFF_HEIGHT = PNG_IMAGE_OFF_WIDTH + 4
+  PNG_IMAGE_OFF_FORMAT = PNG_IMAGE_OFF_HEIGHT + 4
+  PNG_IMAGE_OFF_FLAGS = PNG_IMAGE_OFF_FORMAT + 4
+  PNG_IMAGE_OFF_COLORMAP_ENTRIES = PNG_IMAGE_OFF_FLAGS + 4
+  PNG_IMAGE_OFF_WARNING_OR_ERROR = PNG_IMAGE_OFF_COLORMAP_ENTRIES + 4
+  PNG_IMAGE_OFF_MESSAGE = PNG_IMAGE_OFF_WARNING_OR_ERROR + 4
+
+  # ------------------------------------------------------------------
+  # Public API. Each method constructs a dedicated encoder/decoder
+  # instance, runs it, and returns its output. Keeping these as thin
+  # dispatchers preserves the existing module-level API while letting
+  # the heavy logic live in testable, single-purpose classes.
+  # ------------------------------------------------------------------
+  class << self
+    # Encode raw pixels via the simplified API. Output is post-
+    # processed to strip sRGB/gAMA/cHRM/iCCP chunks unless
+    # strip_colorspace: false.
+    def encode(width, height, pixels, **opts)
+      SimplifiedEncoder.new(width, height, pixels, **opts).call
+    end
+
+    # Encode raw pixels via the standard write API. Accepts filter,
+    # compression_level, interlace, bit_depth, and palette options.
+    # Emits only IHDR/IDAT/IEND directly (no chunk stripping needed).
+    def encode_standard(width, height, pixels, **opts)
+      StandardEncoder.new(width, height, pixels, **opts).call
+    end
+
+    # Decode a PNG buffer into raw pixels plus IHDR metadata.
+    def decode(png, **opts)
+      SimplifiedDecoder.new(png, **opts).call
+    end
+  end
+end

data/libpng.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative 'lib/libpng/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'libpng'
+  spec.version       = Libpng::VERSION
+  spec.authors       = ['Ribose Inc.']
+  spec.email         = ['open.source@ribose.com']
+
+  spec.summary       = 'libpng for Ruby (pre-compiled, FFI-based).'
+  spec.description   = 'Ruby binding for libpng via FFI. The native ' \
+                       'libpng16 shared library is pre-compiled for ' \
+                       'each target platform and shipped inside the ' \
+                       'gem, so no C compiler is required at install time.'
+  spec.homepage      = 'https://github.com/claricle/libpng-ruby'
+  spec.license       = 'BSD-2-Clause'
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/README.adoc#versioning"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features|tmp|ports)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'ffi', '~> 1.0'
+  spec.add_dependency 'mini_portile2', '~> 2.8'
+
+  spec.extensions = ['ext/extconf.rb']
+end