webp-ffi 0.3.1 → 1.0.0

data/ext/webp_ffi/webp_ffi.h

@@ -42,6 +42,16 @@ extern "C" {
     int width, height;
     int crop_x, crop_y, crop_w, crop_h;
     int resize_w, resize_h;
+    // -1 keeps the libwebp default for the options below
+    int preset;             // WebPPreset, applied before the other options
+    int image_hint;         // WebPImageHint
+    int exact;              // keep RGB values under transparent areas
+    int use_sharp_yuv;      // sharper (and slower) RGB to YUV conversion
+    int thread_level;       // multi-threaded encoding
+    int low_memory;         // less memory, more CPU
+    int emulate_jpeg_size;  // quality comparable to JPEG at the same size
+    int lossless_level;     // 0..9, WebPConfigLosslessPreset (turns on lossless)
+    int metadata;           // METADATA_* flags: what to copy from the input
   } FfiWebpEncodeConfig;
 
   typedef struct {
@@ -54,12 +64,44 @@ extern "C" {
   } FfiWebpDecodeConfig;
 
 
-  void decoder_version(char *version);
-  void encoder_version(char *version);
+  typedef struct {
+    int width, height;
+    int has_alpha, has_animation;
+    int format;  // 0 = mixed or unknown, 1 = lossy, 2 = lossless
+  } FfiWebpFeatures;
+
+  // Versions are packed as 0xMMmmpp (major, minor, patch).
+  int decoder_version(void);
+  int encoder_version(void);
   int webp_get_info(const uint8_t* data, size_t data_size, int* width, int* height);
-  int webp_encode(const char *in_file, const char *out_file, const FfiWebpEncodeConfig *encode_config);
-  int webp_decode(const char *in_file, const char *out_file, const FfiWebpDecodeConfig *decode_config);
-  int test_c(int n);
+  // Returns a VP8StatusCode, 0 when 'features' was filled.
+  int webp_get_features(const uint8_t* data, size_t data_size, FfiWebpFeatures* features);
+
+  // All functions below return 0 on success or an error code (see
+  // lib/webp/error.rb). On failure '*detail' holds libwebp's own reason when
+  // there is one: a WebPEncodingError when encoding, a VP8StatusCode when
+  // decoding, otherwise 0.
+  int webp_encode(const char *in_file, const char *out_file,
+                  const FfiWebpEncodeConfig *encode_config, int* detail);
+  int webp_decode(const char *in_file, const char *out_file,
+                  const FfiWebpDecodeConfig *decode_config, int* detail);
+
+  // In-memory versions: on success '*output' holds 'output_size' bytes that the
+  // caller frees with webp_free_data. On failure '*output' is NULL.
+  int webp_encode_data(const uint8_t* data, size_t data_size,
+                       uint8_t** output, size_t* output_size,
+                       const FfiWebpEncodeConfig* encode_config, int* detail);
+  int webp_decode_data(const uint8_t* data, size_t data_size,
+                       uint8_t** output, size_t* output_size,
+                       const FfiWebpDecodeConfig* decode_config, int* detail);
+  // Raw pixels: 'rgba' holds width * height * 4 bytes, row after row.
+  int webp_encode_rgba(const uint8_t* rgba, int width, int height,
+                       uint8_t** output, size_t* output_size,
+                       const FfiWebpEncodeConfig* encode_config, int* detail);
+  int webp_decode_rgba(const uint8_t* data, size_t data_size,
+                       uint8_t** output, size_t* output_size, int* width, int* height,
+                       const FfiWebpDecodeConfig* decode_config, int* detail);
+  void webp_free_data(uint8_t* data);
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }    // extern "C"

data/lib/webp/c.rb

@@ -39,7 +39,25 @@ module WebP
         :crop_w, :int,
         :crop_h, :int,
         :resize_w, :int,
-        :resize_h, :int
+        :resize_h, :int,
+        # -1 keeps the libwebp default
+        :preset, :int,
+        :image_hint, :int,
+        :exact, :int,
+        :use_sharp_yuv, :int,
+        :thread_level, :int,
+        :low_memory, :int,
+        :emulate_jpeg_size, :int,
+        :lossless_level, :int,
+        :metadata, :int
+    end
+
+    class FfiWebpFeatures < FFI::Struct
+      layout :width, :int,
+        :height, :int,
+        :has_alpha, :int,
+        :has_animation, :int,
+        :format, :int
     end
 
     class FfiWebpDecodeConfig < FFI::Struct
@@ -56,12 +74,28 @@ module WebP
     end
 
     # webp lib functions
-    attach_function :decoder_version, [:pointer], :void
-    attach_function :encoder_version, [:pointer], :void
-    attach_function :webp_get_info, [:pointer, :size_t, :pointer, :pointer], :int
-    attach_function :webp_encode, [:string, :string, :pointer], :int
-    attach_function :webp_decode, [:string, :string, :pointer], :int
+    # libwebp versions packed as 0xMMmmpp
+    attach_function :decoder_version, [], :int
+    attach_function :encoder_version, [], :int
+    attach_function :webp_get_info, [:buffer_in, :size_t, :pointer, :pointer], :int
+    attach_function :webp_get_features, [:buffer_in, :size_t, :pointer], :int
+    # blocking: true releases Ruby's Global VM Lock while C works, so other
+    # threads keep running. The C code never calls back into Ruby.
+    # The last argument receives libwebp's reason when a call fails.
+    attach_function :webp_encode, [:string, :string, :pointer, :pointer], :int, blocking: true
+    attach_function :webp_decode, [:string, :string, :pointer, :pointer], :int, blocking: true
+    # in-memory versions: (data, data size, output pointer, output size, options, reason)
+    attach_function :webp_encode_data, [:pointer, :size_t, :pointer, :pointer, :pointer, :pointer], :int, blocking: true
+    attach_function :webp_decode_data, [:pointer, :size_t, :pointer, :pointer, :pointer, :pointer], :int, blocking: true
+    # raw RGBA pixels: (pixels, width, height, output pointer, output size, options, reason)
+    attach_function :webp_encode_rgba, [:pointer, :int, :int, :pointer, :pointer, :pointer, :pointer], :int, blocking: true
+    # (data, data size, output pointer, output size, width, height, options, reason)
+    attach_function :webp_decode_rgba, [:pointer, :size_t, :pointer, :pointer, :pointer, :pointer, :pointer, :pointer], :int, blocking: true
+    attach_function :webp_free_data, [:pointer], :void
 
-    attach_function :test_c, [:int], :int
+    # internal: image size check shared by the PNG, JPEG and TIFF readers
+    attach_function :check_image_size, :UtilCheckImageSize, [:uint64, :uint64, :uint64, :pointer, :pointer], :int
+    # internal: version string of the libtiff in use
+    attach_function :tiff_version, :UtilTIFFVersion, [], :string
   end
 end

data/lib/webp/error.rb

@@ -1,21 +1,71 @@
 module WebP
-  
+
   ENCODER_ERRORS = [
-    "Version mismatch", 
-    "Invalid configuration", 
-    "Cannot read input picture file", 
-    "Cannot open output file", 
-    "Cannot crop picture", 
+    "Version mismatch",
+    "Invalid configuration",
+    "Cannot read input picture file",
+    "Cannot open output file",
+    "Cannot crop picture",
     "Cannot resize picture",
-    "Cannot encode picture as WebP"]
-    
+    "Cannot encode picture as WebP",
+    "Cannot allocate memory"]
+
   DECODER_ERRORS = [
-    "Version mismatch", 
-    "Invalid webp image", 
+    "Version mismatch",
+    "Invalid webp image",
     "Invalid output format",
-    "Decoding failed"]
-  
-  class InvalidImageFormatError < StandardError; end
-  class EncoderError < StandardError; end
-  class DecoderError < StandardError; end
+    "Decoding failed",
+    "Cannot read input file",
+    "Cannot write output file",
+    "Cannot allocate memory"]
+
+  # encode_data and encode_rgba have no input file, so the read error says "data"
+  ENCODER_DATA_ERRORS = ENCODER_ERRORS.dup.tap { |messages| messages[2] = "Cannot read input picture data" }.freeze
+
+  # error codes that point at the input or the output file
+  ENCODER_FILE_ERRORS = { 3 => :input, 4 => :output }.freeze
+  DECODER_FILE_ERRORS = { 2 => :input, 4 => :input, 5 => :input, 6 => :output }.freeze
+
+  # libwebp's own reasons: WebPEncodingError values when encoding
+  ENCODER_REASONS = {
+    1 => [:out_of_memory, "out of memory"],
+    2 => [:bitstream_out_of_memory, "out of memory while writing the bitstream"],
+    3 => [:null_parameter, "a required parameter is missing"],
+    4 => [:invalid_configuration, "the configuration is invalid"],
+    5 => [:bad_dimension, "the picture size is not supported, WebP allows up to 16383 x 16383 pixels"],
+    6 => [:partition0_overflow, "partition 0 is bigger than 512 KiB, try fewer segments or a lower partition_limit"],
+    7 => [:partition_overflow, "a partition is bigger than 16 MiB"],
+    8 => [:bad_write, "cannot write the output"],
+    9 => [:file_too_big, "the file is bigger than 4 GiB"],
+    10 => [:user_abort, "aborted"]
+  }.freeze
+
+  # ...and VP8StatusCode values when decoding
+  DECODER_REASONS = {
+    1 => [:out_of_memory, "out of memory"],
+    2 => [:invalid_param, "invalid parameter, for example a crop outside the picture"],
+    3 => [:bitstream_error, "the data is not a valid WebP bitstream"],
+    4 => [:unsupported_feature, "unsupported feature, for example an animated image"],
+    5 => [:suspended, "decoding was suspended"],
+    6 => [:user_abort, "aborted"],
+    7 => [:not_enough_data, "not enough data, the image may be truncated"]
+  }.freeze
+
+  # Base class for every error this gem raises.
+  class Error < StandardError
+    # the gem's error code from C, or nil
+    attr_reader :code
+    # libwebp's reason as a Symbol (for example :bad_dimension), or nil
+    attr_reader :reason
+
+    def initialize(message = nil, code: nil, reason: nil)
+      super(message)
+      @code = code
+      @reason = reason
+    end
+  end
+
+  class InvalidImageFormatError < Error; end
+  class EncoderError < Error; end
+  class DecoderError < Error; end
 end

data/lib/webp/info.rb

@@ -0,0 +1,13 @@
+module WebP
+  # Returned by WebP.info.
+  Info = Data.define(:width, :height, :format, :alpha, :animated, :metadata) do
+    # :lossy, :lossless or :mixed (animations can mix both)
+    def lossless? = format == :lossless
+    def alpha? = alpha
+    def animated? = animated
+  end
+
+  # Returned by WebP.decode_rgba: 'rgba' holds width * height * 4 bytes, row
+  # after row, as a binary String.
+  RGBAImage = Data.define(:rgba, :width, :height)
+end

data/lib/webp/options.rb

@@ -1,48 +1,155 @@
 module WebP
   class Options
 
+    # integer options; -1 tells C to keep the libwebp default
+    ENCODE_INT_OPTIONS = [:lossless, :near_lossless, :method, :target_size, :segments,
+      :sns_strength, :filter_strength, :filter_sharpness,
+      :filter_type, :autofilter, :alpha_compression, :alpha_filtering,
+      :alpha_quality, :pass, :show_compressed, :preprocessing, :partitions,
+      :partition_limit, :width, :height,
+      :exact, :use_sharp_yuv, :thread_level, :low_memory, :emulate_jpeg_size].freeze
+    ENCODE_FLOAT_OPTIONS = [:quality, :target_PSNR].freeze
+    CROP_RESIZE_OPTIONS = [:crop_x, :crop_y, :crop_w, :crop_h, :resize_w, :resize_h].freeze
+    # options that take a name or a list of names
+    ENCODE_NAMED_OPTIONS = [:preset, :image_hint, :level, :metadata].freeze
+    ENCODE_OPTIONS = (ENCODE_INT_OPTIONS + ENCODE_FLOAT_OPTIONS + CROP_RESIZE_OPTIONS + ENCODE_NAMED_OPTIONS).freeze
+    # raw pixels come with their own size and have no metadata
+    ENCODE_RGBA_OPTIONS = (ENCODE_OPTIONS - [:width, :height, :metadata]).freeze
+
+    DECODE_FLAGS = [:bypass_filtering, :no_fancy_upsampling, :use_threads].freeze
+    DECODE_OPTIONS = ([:output_format] + DECODE_FLAGS + CROP_RESIZE_OPTIONS).freeze
+    DECODE_RGBA_OPTIONS = (DECODE_OPTIONS - [:output_format]).freeze
+    OUTPUT_FORMATS = [:png, :pam, :ppm, :pgm, :bmp, :tiff, :yuv, :alpha_plane_only].freeze
+
+    # libwebp's WebPPreset, WebPImageHint and the METADATA_* flags in metadata.h
+    PRESETS = { default: 0, picture: 1, photo: 2, drawing: 3, icon: 4, text: 5 }.freeze
+    IMAGE_HINTS = { default: 0, picture: 1, photo: 2, graph: 3 }.freeze
+    METADATA = { exif: 1, icc: 2, xmp: 4 }.freeze
+
     def initialize(options)
       @user_options = options
     end
 
-    def encode_pointer
-      options_pointer = FFI::MemoryPointer.new :char, C::FfiWebpEncodeConfig.size, false
+    def encode_pointer(known = ENCODE_OPTIONS)
+      check_unknown_options(known, "encode")
+      options_pointer = FFI::MemoryPointer.new :char, C::FfiWebpEncodeConfig.size, true
       options_struct = C::FfiWebpEncodeConfig.new options_pointer
-      [:lossless, :near_lossless, :method, :target_size, :target_PSNR, :segments,
-        :sns_strength, :filter_strength, :filter_sharpness,
-        :filter_type, :autofilter, :alpha_compression, :alpha_filtering,
-        :alpha_quality, :pass, :show_compressed, :preprocessing, :partitions,
-        :partition_limit, :width, :height].each do |key|
-          options_struct[key] = @user_options[key] ? @user_options[key] : -1
+      (ENCODE_INT_OPTIONS + [:target_PSNR]).each do |key|
+        value = number_option(key)
+        options_struct[key] = value.nil? ? -1 : value
       end
       encode_default(options_struct)
-      [:quality, :crop_x, :crop_y, :crop_w,
-        :crop_h, :resize_w, :resize_h].each do |key|
-          options_struct[key] = @user_options[key] if @user_options[key]
+      CROP_RESIZE_OPTIONS.each do |key|
+        value = number_option(key)
+        options_struct[key] = value unless value.nil?
       end
+      level = level_option
+      quality = number_option(:quality)
+      # a lossless level picks its own quality, so only override it when asked
+      options_struct[:quality] = quality.nil? ? (level >= 0 ? -1 : 100) : quality
+      options_struct[:lossless_level] = level
+      options_struct[:preset] = named_option(:preset, PRESETS)
+      options_struct[:image_hint] = named_option(:image_hint, IMAGE_HINTS)
+      options_struct[:metadata] = metadata_option
       options_pointer
     end
 
-    def decode_pointer
-      options_pointer = FFI::MemoryPointer.new :char, C::FfiWebpDecodeConfig.size, false
+    def decode_pointer(known = DECODE_OPTIONS)
+      check_unknown_options(known, "decode")
+      options_pointer = FFI::MemoryPointer.new :char, C::FfiWebpDecodeConfig.size, true
       options_struct = C::FfiWebpDecodeConfig.new options_pointer
       decode_default(options_struct)
-      # options
-      if @user_options[:output_format] && [:png, :pam, :ppm, :pgm, :bmp, :tiff, :yuv, :alpha_plane_only].include?(@user_options[:output_format])
-        options_struct[:output_format] = C::OutputFileFormat[@user_options[:output_format]]
+      options_struct[:output_format] = C::OutputFileFormat[output_format] if @user_options[:output_format]
+      # set every flag explicitly, so C never reads a field we did not write
+      DECODE_FLAGS.each do |key|
+        options_struct[key] = flag_option(key)
       end
-      [:bypass_filtering, :no_fancy_upsampling, :use_threads].each do |key|
-        options_struct[key] = 1 if @user_options[key] && true == @user_options[key]
-      end
-      [:crop_x, :crop_y, :crop_w,
-        :crop_h, :resize_w, :resize_h].each do |key|
-          options_struct[key] = @user_options[key] if @user_options[key]
+      CROP_RESIZE_OPTIONS.each do |key|
+        value = number_option(key)
+        options_struct[key] = value unless value.nil?
       end
       options_pointer
     end
 
     private
 
+    # A typo like :cropt_y used to be ignored silently, so unknown options raise.
+    def check_unknown_options(known, operation)
+      unknown = @user_options.keys - known
+      return if unknown.empty?
+      details = unknown.map { |key| "#{key.inspect}#{suggestion(key, known)}" }
+      raise ArgumentError, "webp-ffi: unknown #{operation} option#{'s' if unknown.size > 1} #{details.join(', ')}"
+    end
+
+    def suggestion(key, known)
+      return "" unless defined?(DidYouMean::SpellChecker)
+      match = DidYouMean::SpellChecker.new(dictionary: known).correct(key).first
+      match ? " (did you mean #{match.inspect}?)" : ""
+    end
+
+    # numbers pass through, true and false become 1 and 0, nil keeps the default
+    def number_option(key)
+      value = @user_options[key]
+      case value
+      when nil then nil
+      when true then 1
+      when false then 0
+      when Numeric then value
+      else
+        raise ArgumentError, "webp-ffi: option #{key.inspect} must be a number or true/false, got #{value.inspect}"
+      end
+    end
+
+    def flag_option(key)
+      value = @user_options[key]
+      case value
+      when nil, false, 0 then 0
+      when true, 1 then 1
+      else
+        raise ArgumentError, "webp-ffi: option #{key.inspect} must be true or false, got #{value.inspect}"
+      end
+    end
+
+    def output_format
+      value = @user_options[:output_format]
+      format = value.respond_to?(:to_sym) ? value.to_sym : value
+      return format if OUTPUT_FORMATS.include?(format)
+      raise ArgumentError, "webp-ffi: unknown output_format #{value.inspect}, use one of #{OUTPUT_FORMATS.map(&:inspect).join(', ')}"
+    end
+
+    # a Symbol or String from 'names', or -1 for the default
+    def named_option(key, names)
+      value = @user_options[key]
+      return -1 if value.nil?
+      name = value.respond_to?(:to_sym) ? value.to_sym : value
+      names.fetch(name) do
+        raise ArgumentError, "webp-ffi: unknown #{key} #{value.inspect}, use one of #{names.keys.map(&:inspect).join(', ')}"
+      end
+    end
+
+    # lossless compression effort from 0 (fast) to 9 (small), or -1
+    def level_option
+      value = @user_options[:level]
+      return -1 if value.nil?
+      return value if value.is_a?(Integer) && value.between?(0, 9)
+      raise ArgumentError, "webp-ffi: option :level must be an integer from 0 to 9, got #{value.inspect}"
+    end
+
+    # :all, :none, or one or more of :exif, :icc and :xmp
+    def metadata_option
+      value = @user_options[:metadata]
+      case value
+      when nil, false, :none, "none" then 0
+      when true, :all, "all" then METADATA.values.sum
+      else
+        Array(value).sum do |name|
+          METADATA.fetch(name.respond_to?(:to_sym) ? name.to_sym : name) do
+            raise ArgumentError, "webp-ffi: unknown metadata #{name.inspect}, use :all, :none or some of :exif, :icc, :xmp"
+          end
+        end
+      end
+    end
+
     def encode_default(options_struct)
       options_struct[:quality] = 100
       similar_default(options_struct)

data/lib/webp/version.rb

@@ -1,3 +1,3 @@
 module WebP
-  VERSION = "0.3.1"
+  VERSION = "1.0.0"
 end

data/lib/webp/webp.rb

@@ -2,60 +2,178 @@ require "webp/options"
 require "webp/c"
 
 module WebP
+  # WebPBitstreamFeatures format values
+  FORMATS = { 0 => :mixed, 1 => :lossy, 2 => :lossless }.freeze
+  # flags in the VP8X header of extended WebP files
+  METADATA_FLAGS = { icc: 0x20, exif: 0x08, xmp: 0x04 }.freeze
+
   class << self
-    
+
     def decoder_version
-      pointer = FFI::MemoryPointer.new(:char, 10)
-      C.decoder_version(pointer)
-      pointer.null? ? nil : pointer.read_string()
+      format_version(C.decoder_version)
     end
-    
+
     def encoder_version
-      pointer = FFI::MemoryPointer.new(:char, 10)
-      C.encoder_version(pointer)
-      pointer.null? ? nil : pointer.read_string()
+      format_version(C.encoder_version)
     end
-    
-    # get webp image size
+
+    # Width and height of WebP image data (a String or an IO), or nil for nil.
     def webp_size(data)
       return nil if data.nil?
-      pointers = get_pointers_for_webp_size(data)
-      if 0 == C.webp_get_info(pointers[:data], pointers[:data_size], pointers[:width], pointers[:height])
-        [(pointers[:width].null? ? nil : pointers[:width].read_int), (pointers[:height].null? ? nil : pointers[:height].read_int)]
-      else
+      data = data_string(data)
+      width, height = FFI::MemoryPointer.new(:int), FFI::MemoryPointer.new(:int)
+      unless 0 == C.webp_get_info(data, data.bytesize, width, height)
         raise InvalidImageFormatError, "invalid WebP image data"
       end
+      [width.read_int, height.read_int]
     end
-    
+
+    # Details about WebP image data (a String or an IO) as a WebP::Info, or nil
+    # for nil: size, format (:lossy, :lossless or :mixed), alpha, animation and
+    # the metadata it carries (:icc, :exif, :xmp).
+    def info(data)
+      return nil if data.nil?
+      data = data_string(data)
+      features = C::FfiWebpFeatures.new
+      status = C.webp_get_features(data, data.bytesize, features)
+      unless status.zero?
+        reason, text = DECODER_REASONS[status]
+        raise InvalidImageFormatError.new(["invalid WebP image data", text].compact.join(": "), reason: reason)
+      end
+      Info.new(width: features[:width], height: features[:height],
+               format: FORMATS.fetch(features[:format], :mixed),
+               alpha: features[:has_alpha] == 1, animated: features[:has_animation] == 1,
+               metadata: metadata_in(data))
+    end
+
     # encode
     def encode(input_file, output_file, options = {})
-      unless 0 == (encode_res = C.webp_encode(input_file, output_file, init_options_object(options).encode_pointer))
-        raise EncoderError, ENCODER_ERRORS[encode_res - 1]
+      input_file, output_file = file_path(input_file), file_path(output_file)
+      options_pointer = init_options_object(options).encode_pointer
+      detail = FFI::MemoryPointer.new(:int)
+      code = C.webp_encode(input_file, output_file, options_pointer, detail)
+      unless code.zero?
+        raise build_error(EncoderError, ENCODER_ERRORS, code, detail.read_int, ENCODER_FILE_ERRORS, input_file, output_file)
       end
       true
     end
-    
+
     # decode
     def decode(input_file, output_file, options = {})
-      unless 0 == (decode_res = C.webp_decode(input_file, output_file, init_options_object(options).decode_pointer))
-        raise DecoderError, DECODER_ERRORS[decode_res - 1]
+      input_file, output_file = file_path(input_file), file_path(output_file)
+      options_pointer = init_options_object(options).decode_pointer
+      detail = FFI::MemoryPointer.new(:int)
+      code = C.webp_decode(input_file, output_file, options_pointer, detail)
+      unless code.zero?
+        raise build_error(DecoderError, DECODER_ERRORS, code, detail.read_int, DECODER_FILE_ERRORS, input_file, output_file)
       end
       true
     end
-    
+
+    # Encodes PNG, JPEG or TIFF image data (or raw YUV data, with the :width and
+    # :height options) to WebP. 'data' is a String or an IO. Returns the WebP
+    # image as a binary String.
+    def encode_data(data, options = {})
+      options_pointer = init_options_object(options).encode_pointer
+      with_output(EncoderError, ENCODER_DATA_ERRORS, data) do |input, size, output, output_size, detail|
+        C.webp_encode_data(input, size, output, output_size, options_pointer, detail)
+      end
+    end
+
+    # Decodes WebP image data (a String or an IO). Returns the image in the
+    # :output_format (PNG by default) as a binary String.
+    def decode_data(data, options = {})
+      options_pointer = init_options_object(options).decode_pointer
+      with_output(DecoderError, DECODER_ERRORS, data) do |input, size, output, output_size, detail|
+        C.webp_decode_data(input, size, output, output_size, options_pointer, detail)
+      end
+    end
+
+    # Encodes raw RGBA pixels: 'pixels' holds width * height * 4 bytes, row
+    # after row. Returns the WebP image as a binary String.
+    def encode_rgba(pixels, width, height, options = {})
+      width, height = Integer(width), Integer(height)
+      pixels = data_string(pixels)
+      unless width.positive? && height.positive? && pixels.bytesize == width * height * 4
+        raise ArgumentError, "webp-ffi: expected #{width} x #{height} x 4 bytes of RGBA pixels, got #{pixels.bytesize}"
+      end
+      options_pointer = init_options_object(options).encode_pointer(Options::ENCODE_RGBA_OPTIONS)
+      with_output(EncoderError, ENCODER_DATA_ERRORS, pixels) do |input, _size, output, output_size, detail|
+        C.webp_encode_rgba(input, width, height, output, output_size, options_pointer, detail)
+      end
+    end
+
+    # Decodes WebP image data (a String or an IO) to raw RGBA pixels. Returns a
+    # WebP::RGBAImage with the pixels, width and height.
+    def decode_rgba(data, options = {})
+      options_pointer = init_options_object(options).decode_pointer(Options::DECODE_RGBA_OPTIONS)
+      width, height = FFI::MemoryPointer.new(:int), FFI::MemoryPointer.new(:int)
+      rgba = with_output(DecoderError, DECODER_ERRORS, data) do |input, size, output, output_size, detail|
+        C.webp_decode_rgba(input, size, output, output_size, width, height, options_pointer, detail)
+      end
+      RGBAImage.new(rgba: rgba, width: width.read_int, height: height.read_int)
+    end
+
     private
-    
-    def get_pointers_for_webp_size(data)
-      pointers = Hash.new
-      pointers[:data_size] = data.respond_to?(:bytesize) ? data.bytesize : data.size
-      pointers[:width], pointers[:height] = FFI::MemoryPointer.new(:int, 2), FFI::MemoryPointer.new(:int, 2)
-      pointers[:data] = FFI::MemoryPointer.new(:char, pointers[:data_size]).put_bytes(0, data)
-      pointers
-    end
-    
+
+    def format_version(version)
+      [version >> 16, version >> 8, version].map { |part| part & 0xff }.join(".")
+    end
+
+    # Accepts a String, a Pathname or anything with #to_path. Returns a new
+    # string, because C reads it while other Ruby threads keep running.
+    def file_path(file)
+      String.new(File.path(file))
+    end
+
+    # Accepts a String (or anything with #to_str) or an IO to read from.
+    def data_string(data)
+      data = data.read if data.respond_to?(:read) && !data.is_a?(String)
+      String.try_convert(data) or raise TypeError, "webp-ffi: expected image data as a String or an IO, got #{data.class}"
+    end
+
+    def metadata_in(data)
+      return [] unless data.bytesize >= 21 && data.byteslice(12, 4) == "VP8X"
+      flags = data.getbyte(20)
+      METADATA_FLAGS.select { |_name, flag| flags & flag != 0 }.keys
+    end
+
+    # Copies the input to native memory (C reads it while other Ruby threads
+    # keep running), yields the arguments for the C call, and returns the output
+    # bytes. Raises error_class when C reports an error.
+    def with_output(error_class, messages, data)
+      data = data_string(data)
+      input = FFI::MemoryPointer.new(:uint8, [data.bytesize, 1].max)
+      input.put_bytes(0, data)
+      output = FFI::MemoryPointer.new(:pointer)
+      output_size = FFI::MemoryPointer.new(:size_t)
+      detail = FFI::MemoryPointer.new(:int)
+      code = yield(input, data.bytesize, output, output_size, detail)
+      raise build_error(error_class, messages, code, detail.read_int) unless code.zero?
+
+      buffer = output.read_pointer
+      begin
+        buffer.read_bytes(output_size.read(:size_t))
+      ensure
+        C.webp_free_data(buffer)
+      end
+    end
+
+    def build_error(error_class, messages, code, detail, file_errors = {}, input_file = nil, output_file = nil)
+      message = code.between?(1, messages.size) ? messages[code - 1] : "Unknown error (code #{code})"
+      case file_errors[code]
+      when :input then message = "#{message}: #{input_file}"
+      when :output then message = "#{message}: #{output_file}"
+      end
+      reasons = error_class == EncoderError ? ENCODER_REASONS : DECODER_REASONS
+      reason, text = reasons[detail]
+      message = "#{message} (#{text})" if text
+      error_class.new(message, code: code, reason: reason)
+    end
+
     def init_options_object(options)
       Options.new options
     end
-    
+
   end
-end
+end

data/lib/webp_ffi.rb

@@ -11,6 +11,6 @@ end
 require "webp/options"
 require "webp/c"
 require "webp/error"
-require "webp/libc" # not used right now
+require "webp/info"
 require "webp/webp"
 require "webp/version"