oily_png 0.0.2 → 0.0.3

data/.gitignore

@@ -1,7 +1,8 @@
 Makefile
 /conftest.dSYM
-/*.bundle
-/*.o
+*.bundle
+*.o
 /.bundle/
 /pkg
 oily_png-*.gem
+.DS_Store

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    oily_png (0.0.2)
+    oily_png (0.0.3)
       chunky_png (~> 0.10.1)
 
 GEM

data/README.rdoc

@@ -1,9 +1,26 @@
-=== OilyPNG
+= OilyPNG
 
-Native module to speed up ChunkyPNG. 
+OilyPNG is a Ruby C extension to speed up the pure Ruby ChunkyPNG library. 
 
-* Install this gem 
-* Use require "oily_png" instead of require"chunky_png"
-* Use the ChunkyPNG API as you normally would.
-* Presto!
+Currently it has an alternative implementation of decoding PNGs, making that operation much 
+faster for PNG images that apply filtering. An alternative implementation for encoding is
+planned.
+
+*Warning*: this is my first C code in years. It may blow up your PC after leaking memory all
+over the place, killing a kitten in the process. You have been warned.
+
+== Usage
+
+1. First install the gem and make it available to your project.
+2. Use require "oily_png" instead of require "chunky_png"
+3. Presto! Now use ChunkyPNG as you normally would and get an instant speedup. 
+
+See http://github.com/wvanbergen/chunky_png/wiki for more information on how to use the
+ChunkyPNG API.
+
+== About
+
+License: MIT (see LICENSE)
+
+This C module is written by Willem van Bergen with help from Dirkjan Bussink.
 

data/ext/oily_png/extconf.rb

@@ -1,11 +1,2 @@
-# Loads mkmf which is used to make makefiles for Ruby extensions
 require 'mkmf'
-
-# paths = ['/opt/local', '/usr/local']
-# lib_paths = paths.map { |p| p + '/lib' }
-# inc_paths = paths.map { |p| p + '/include' }
-
-# exit(1) unless find_library('png', 'png_get_io_ptr', *lib_paths) && find_header('png.h', *inc_paths)
-
-# Create a makefile
-create_makefile('oily_png/decoding')
+create_makefile('oily_png/png_decoding')

data/ext/oily_png/{decoding.c → png_decoding.c}

@@ -1,65 +1,65 @@
 #include "ruby.h"
 
-// Variable for the OilyPNG module
-VALUE OilyPNG = Qnil;
+// PNG color mode constants
+#define OILY_PNG_COLOR_GRAYSCALE        0
+#define OILY_PNG_COLOR_TRUECOLOR        2
+#define OILY_PNG_COLOR_INDEXED          3
+#define OILY_PNG_COLOR_GRAYSCALE_ALPHA  4
+#define OILY_PNG_COLOR_TRUECOLOR_ALPHA  6
 
-void Init_decoding();
+// PNG filter constants
+#define OILY_PNG_FILTER_NONE    0
+#define OILY_PNG_FILTER_SUB     1
+#define OILY_PNG_FILTER_UP      2
+#define OILY_PNG_FILTER_AVERAGE 3
+#define OILY_PNG_FILTER_PAETH   4
 
+// Type definitions
+#define PIXEL unsigned int
+
+void Init_png_decoding();
 VALUE oily_png_decode_png_image_pass(VALUE self, VALUE stream, VALUE width, VALUE height, VALUE color_mode, VALUE start_pos);
 
-// COLOR_GRAYSCALE       = 0
-// COLOR_TRUECOLOR       = 2
-// COLOR_INDEXED         = 3
-// COLOR_GRAYSCALE_ALPHA = 4
-// COLOR_TRUECOLOR_ALPHA = 6
-// 
-// FILTERING_DEFAULT     = 0
-// 
-// COMPRESSION_DEFAULT   = 0
-// 
-// INTERLACING_NONE      = 0
-// INTERLACING_ADAM7     = 1
-// 
-// FILTER_NONE           = 0
-// FILTER_SUB            = 1
-// FILTER_UP             = 2
-// FILTER_AVERAGE        = 3
-// FILTER_PAETH          = 4
+////////////////////////////////////////////////////////////////////////////
 
-void Init_decoding() {
+// Initialize the extension by creating the OilyPNG::PNGDecoding module
+void Init_png_decoding() {
   VALUE OilyPNG = rb_define_module("OilyPNG");
-  VALUE OilyPNGDecoding = rb_define_module_under(OilyPNG, "PNGDecoding");
-  rb_define_method(OilyPNGDecoding, "decode_png_image_pass", oily_png_decode_png_image_pass, 5);
+  VALUE OilyPNGPNGDecoding = rb_define_module_under(OilyPNG, "PNGDecoding");
+  rb_define_method(OilyPNGPNGDecoding, "decode_png_image_pass", oily_png_decode_png_image_pass, 5);
 }
 
+// Returns the number of bytes per pixel for a given color mode.
 int oily_png_pixel_size(color_mode) {
   switch (color_mode) {
-    case 0:  return 1;
-    case 2:  return 3;
-    case 3:  return 1;
-    case 4:  return 2;
-    case 6:  return 4;
+    case OILY_PNG_COLOR_GRAYSCALE:       return 1;
+    case OILY_PNG_COLOR_TRUECOLOR:       return 3;
+    case OILY_PNG_COLOR_INDEXED:         return 1;
+    case OILY_PNG_COLOR_GRAYSCALE_ALPHA: return 2;
+    case OILY_PNG_COLOR_TRUECOLOR_ALPHA: return 4;
     default: return -1;
   }
 }
 
-unsigned int oily_png_decode_pixel(int color_mode, unsigned char* bytes, int byte_index, VALUE decoding_palette) {
+// Decodes a pixel at the given position in the bytearray
+PIXEL oily_png_decode_pixel(int color_mode, unsigned char* bytes, int byte_index, VALUE decoding_palette) {
   switch (color_mode) {
-    case 0:
+    case OILY_PNG_COLOR_GRAYSCALE:
       return (bytes[byte_index] << 24) + (bytes[byte_index] << 16) + (bytes[byte_index] << 8) + 0xff;
-    case 2:
+    case OILY_PNG_COLOR_TRUECOLOR:
       return (bytes[byte_index] << 24) + (bytes[byte_index + 1] << 16) + (bytes[byte_index + 2] << 8) + 0xff;
-    case 3:
+    case OILY_PNG_COLOR_INDEXED:
       return NUM2UINT(rb_funcall(decoding_palette, rb_intern("[]"), 1, INT2FIX(bytes[byte_index])));
-    case 4:
+    case OILY_PNG_COLOR_GRAYSCALE_ALPHA:
       return (bytes[byte_index] << 24) + (bytes[byte_index] << 16) + (bytes[byte_index] << 8) + bytes[byte_index + 1];
-    case 6:
+    case OILY_PNG_COLOR_TRUECOLOR_ALPHA:
       return (bytes[byte_index] << 24) + (bytes[byte_index + 1] << 16) + (bytes[byte_index + 2] << 8) + bytes[byte_index + 3];
     default: 
       exit(1);
   }
 }
 
+// Decodes a SUB filtered scanline at the given position in the byte array
 void oily_png_filter_sub(unsigned char* bytes, int pos, int line_length, int pixel_size) {
   int i;
   for (i = 1 + pixel_size; i < line_length; i++) {
@@ -67,8 +67,10 @@ void oily_png_filter_sub(unsigned char* bytes, int pos, int line_length, int pix
   }
 }
 
+// Decodes an UP filtered scanline at the given position in the byte array
 void oily_png_filter_up(unsigned char* bytes, int pos, int line_length, int pixel_size) {
   int i;
+  // The first line is not filtered because there is no privous line
   if (pos >= line_length) {
     for (i = 1; i < line_length; i++) {
       bytes[pos + i] += bytes[pos + i - line_length]; // mod 256 ???
@@ -76,33 +78,37 @@ void oily_png_filter_up(unsigned char* bytes, int pos, int line_length, int pixe
   }
 }
 
+// Decodes an AVERAGE filtered scanline at the given position in the byte array
 void oily_png_filter_average(unsigned char* bytes, int pos, int line_length, int pixel_size) {
   int i;
   unsigned char a, b;
   for (i = 1; i < line_length; i++) {
     a = (i > pixel_size)     ? bytes[pos + i - pixel_size]  : 0;
     b = (pos >= line_length) ? bytes[pos + i - line_length] : 0;
-    bytes[pos + i] += (a + b) >> 1;
+    bytes[pos + i] += (a + b) >> 1; // mod 256 ???
   }
 }
 
+// Decodes a PAETH filtered scanline at the given position in the byte array
 void oily_png_filter_paeth(unsigned char* bytes, int pos, int line_length, int pixel_size) {
   unsigned char a, b, c, pr;
   int i, p, pa, pb, pc;
   for (i = 1; i < line_length; i++) {
     a = (i > pixel_size) ? bytes[pos + i - pixel_size]  : 0;
     b = (pos >= line_length) ? bytes[pos + i - line_length] : 0;
-    c = (pos >= line_length && i > pixel_size) ? bytes[pos + i - line_length - pixel_size] : 0;    
+    c = (pos >= line_length && i > pixel_size) ? bytes[pos + i - line_length - pixel_size] : 0;
     p = a + b - c;
     pa = abs(p - a);
     pb = abs(p - b);
     pc = abs(p - c);
     pr = (pa <= pb) ? (pa <= pc ? a : c) : (pb <= pc ? b : c);
-    bytes[pos + i] += pr;
+    bytes[pos + i] += pr; // mod 256 ???
   }
 }
 
-
+// Decodes an image pass from the given byte stream at the given position.
+// A normal PNG will only have one pass that consumes the entire stream, while an
+// interlaced image requires 7 passes which are loaded from different starting positions.
 VALUE oily_png_decode_png_image_pass(VALUE self, VALUE stream, VALUE width, VALUE height, VALUE color_mode, VALUE start_pos) {
   
   int pixel_size = oily_png_pixel_size(FIX2INT(color_mode));
@@ -112,31 +118,37 @@ VALUE oily_png_decode_png_image_pass(VALUE self, VALUE stream, VALUE width, VALU
   VALUE pixels = rb_ary_new();
   
   VALUE decoding_palette = Qnil;
-  if (FIX2INT(color_mode) == 3) {
+  if (FIX2INT(color_mode) == OILY_PNG_COLOR_INDEXED) {
     decoding_palette = rb_funcall(self, rb_intern("decoding_palette"), 0);
   }
   
+  // Copy the bytes for this pass from the stream to a separate location
+  // so we can work on this byte array directly.
   unsigned char* pixelstream = RSTRING_PTR(stream);
   unsigned char* bytes = malloc(pass_size);
   memcpy(bytes, pixelstream + FIX2INT(start_pos), pass_size);
 
   int y, x, line_start, prev_line_start, byte_index, pixel_index;
   unsigned char filter;
-  unsigned int pixel;
+  PIXEL pixel;
   
   for (y = 0; y < FIX2INT(height); y++) {
     line_start = y * line_size;
-    filter = bytes[line_start];
     
-    switch (filter) {
-      case 0: break;
-      case 1: oily_png_filter_sub(     bytes, line_start, line_size, pixel_size); break;
-      case 2: oily_png_filter_up(      bytes, line_start, line_size, pixel_size); break;
-      case 3: oily_png_filter_average( bytes, line_start, line_size, pixel_size); break;
-      case 4: oily_png_filter_paeth(   bytes, line_start, line_size, pixel_size); break;
+    // Apply filering to the line
+    switch (bytes[line_start]) {
+      case OILY_PNG_FILTER_NONE:    break;
+      case OILY_PNG_FILTER_SUB:     oily_png_filter_sub(     bytes, line_start, line_size, pixel_size); break;
+      case OILY_PNG_FILTER_UP:      oily_png_filter_up(      bytes, line_start, line_size, pixel_size); break;
+      case OILY_PNG_FILTER_AVERAGE: oily_png_filter_average( bytes, line_start, line_size, pixel_size); break;
+      case OILY_PNG_FILTER_PAETH:   oily_png_filter_paeth(   bytes, line_start, line_size, pixel_size); break;
       default: exit(1);
     }
     
+    // Set the filter byte to 0 because the bytearray is now unfiltered.
+    bytes[line_start] = OILY_PNG_FILTER_NONE;
+    
+    // Now, iterate over all bytes in this line and combine them into pixels
     for (x = 0; x < FIX2INT(width); x++) {
       pixel_index = FIX2INT(width) * y + x;
       byte_index  = line_start + 1 + (x * pixel_size);
@@ -145,7 +157,10 @@ VALUE oily_png_decode_png_image_pass(VALUE self, VALUE stream, VALUE width, VALU
     }
   }
   
+  // Get rid of the byte array.
   free(bytes);
+  
+  // Now, return a new ChunkyPNG::Canvas instance with the decoded pixels.
   return rb_funcall(self, rb_intern("new"), 3, width, height, pixels);
 }
 

data/lib/oily_png.rb

@@ -1,9 +1,9 @@
 require 'chunky_png'
-require 'oily_png/decoding'
+require 'oily_png/png_decoding'
 
 module OilyPNG
   
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 
   def self.included(base)
     base::Canvas.extend OilyPNG::PNGDecoding

data/oily_png.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |s|
   
   # Do not change the version and date fields by hand. This will be done
   # automatically by the gem release script.
-  s.version = "0.0.2"
+  s.version = "0.0.3"
   s.date    = "2010-10-05"
 
   s.summary     = "Native mixin to speed up ChunkyPNG"
@@ -30,6 +30,6 @@ Gem::Specification.new do |s|
 
   # Do not change the files and test_files fields by hand. This will be done
   # automatically by the gem release script.
-  s.files      = %w(.gitignore Gemfile Gemfile.lock LICENSE README.rdoc Rakefile ext/oily_png/decoding.c ext/oily_png/extconf.rb lib/oily_png.rb oily_png.gemspec tasks/github-gem.rake)
-  s.test_files = %w()
+  s.files      = %w(.gitignore Gemfile Gemfile.lock LICENSE README.rdoc Rakefile ext/oily_png/extconf.rb ext/oily_png/png_decoding.c lib/oily_png.rb oily_png.gemspec spec/decoding_spec.rb spec/resources/gray.png spec/resources/operations.png spec/spec_helper.rb tasks/github-gem.rake)
+  s.test_files = %w(spec/decoding_spec.rb)
 end

data/spec/decoding_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe OilyPNG::PNGDecoding do
+
+  it "should call Color.bytesize in the pure ruby version" do
+    ChunkyPNG::Color.should_receive(:bytesize).and_return(3)
+    ChunkyPNG::Canvas.from_file(resource_file('operations.png'))
+  end
+
+  it "should not call Color.bytesize in the native version" do
+    ChunkyPNG::Color.should_not_receive(:bytesize)
+    OilyCanvas.from_file(resource_file('operations.png'))
+  end
+  
+  context 'decoding different filtering methods' do
+    before(:all) { @reference = ChunkyPNG::Canvas.from_file(resource_file('operations.png'))}
+    
+    it "should decode NONE filtering exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:filtering => ChunkyPNG::FILTER_NONE)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode SUB filtering exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:filtering => ChunkyPNG::FILTER_SUB)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode UP filtering exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:filtering => ChunkyPNG::FILTER_UP)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode AVERAGE filtering exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:filtering => ChunkyPNG::FILTER_AVERAGE)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode PAETH filtering exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:filtering => ChunkyPNG::FILTER_PAETH)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+  end
+  
+  context 'decoding different color modes' do
+    before(:all) { @reference = ChunkyPNG::Canvas.from_file(resource_file('gray.png'))}
+    
+    it "should decode RGBA images the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:color_mode => ChunkyPNG::COLOR_TRUECOLOR_ALPHA)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode RGB images exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:color_mode => ChunkyPNG::COLOR_TRUECOLOR)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode indexed images exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:color_mode => ChunkyPNG::COLOR_INDEXED)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode grayscale images exactly the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:color_mode => ChunkyPNG::COLOR_GRAYSCALE)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+    
+    it "should decode grayscale images with transparency the same as ChunkyPNG" do
+      filtered_data = @reference.to_blob(:color_mode => ChunkyPNG::COLOR_GRAYSCALE_ALPHA)
+      ChunkyPNG::Canvas.from_blob(filtered_data).should == OilyCanvas.from_blob(filtered_data)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,40 @@
+require 'rubygems'
+require 'bundler'
+
+Bundler.setup
+
+require 'spec'
+require 'chunky_png'
+require 'oily_png/png_decoding'
+
+class OilyCanvas < ChunkyPNG::Canvas
+  extend OilyPNG::PNGDecoding
+end
+
+module ResourceHelper
+  def resource_files
+    Dir[File.join(File.dirname(__FILE__), 'resources', '*.png')]
+  end
+end
+
+module CanvasHelper
+  
+  def resource_file(name)
+    File.join(File.dirname(__FILE__), 'resources', name)
+  end
+  
+  def display(canvas)
+    filename = resource_file('_tmp.png')
+    canvas.to_datastream.save(filename)
+    `open #{filename}`
+  end
+  
+  def reference_canvas(name)
+    ChunkyPNG::Canvas.from_file(resource_file("#{name}.png"))
+  end
+end
+
+Spec::Runner.configure do |config|
+  config.extend ResourceHelper
+  config.include CanvasHelper
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: oily_png
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Willem van Bergen
@@ -79,10 +79,14 @@ files:
 - LICENSE
 - README.rdoc
 - Rakefile
-- ext/oily_png/decoding.c
 - ext/oily_png/extconf.rb
+- ext/oily_png/png_decoding.c
 - lib/oily_png.rb
 - oily_png.gemspec
+- spec/decoding_spec.rb
+- spec/resources/gray.png
+- spec/resources/operations.png
+- spec/spec_helper.rb
 - tasks/github-gem.rake
 has_rdoc: true
 homepage: http://wiki.github.com/wvanbergen/oily_png
@@ -126,5 +130,5 @@ rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Native mixin to speed up ChunkyPNG
-test_files: []
-
+test_files: 
+- spec/decoding_spec.rb