Class: ChunkyPNG::Datastream

### Home Classes Methods

### In Files

- lib/chunky_png/datastream.rb

### Parent

Object

### Methods

- ::empty_bytearray
- ::from_blob
- ::from_file
- ::from_io
- ::from_string
- ::new
- ::verify_signature!
- #chunks
- #each_chunk
- #imagedata
- #metadata
- #save
- #to_blob
- #to_s
- #to_string
- #write

### Files

- BENCHMARKING.rdoc
- CHANGELOG.rdoc
- CONTRIBUTING.rdoc
- README.rdoc

### Class/Module Index

Quicksearch

- ChunkyPNG
- ChunkyPNG::CRCMismatch
- ChunkyPNG::Canvas
- ChunkyPNG::Canvas::Adam7Interlacing
- ChunkyPNG::Canvas::DataUrlExporting
- ChunkyPNG::Canvas::DataUrlImporting
- ChunkyPNG::Canvas::Drawing
- ChunkyPNG::Canvas::Masking
- ChunkyPNG::Canvas::Operations
- ChunkyPNG::Canvas::PNGDecoding
- ChunkyPNG::Canvas::PNGEncoding
- ChunkyPNG::Canvas::Resampling
- ChunkyPNG::Canvas::StreamExporting
- ChunkyPNG::Canvas::StreamImporting
- ChunkyPNG::Chunk
- ChunkyPNG::Chunk::Base
- ChunkyPNG::Chunk::CompressedText
- ChunkyPNG::Chunk::End
- ChunkyPNG::Chunk::Generic
- ChunkyPNG::Chunk::Header
- ChunkyPNG::Chunk::ImageData
- ChunkyPNG::Chunk::InternationalText
- ChunkyPNG::Chunk::Palette
- ChunkyPNG::Chunk::Text
- ChunkyPNG::Chunk::Transparency
- ChunkyPNG::Color
- ChunkyPNG::Datastream
- ChunkyPNG::Dimension
- ChunkyPNG::Exception
- ChunkyPNG::ExpectationFailed
- ChunkyPNG::Image
- ChunkyPNG::NotSupported
- ChunkyPNG::OutOfBounds
- ChunkyPNG::Palette
- ChunkyPNG::Point
- ChunkyPNG::RMagick
- ChunkyPNG::SignatureMismatch
- ChunkyPNG::Vector
- Enumerable
- String

No matching classes.

# ChunkyPNG::Datastream

The Datastream class represents a PNG formatted datastream. It supports both reading from and writing to strings, streams and files.

A PNG datastream begins with the PNG signature, and then contains multiple chunks, starting with a header (IHDR) chunk and finishing with an end (IEND) chunk.

@see ChunkyPNG::Chunk

### Constants

SIGNATURE

  The signature that each PNG file or stream should begin with.

### Attributes

data_chunks[RW]

The chunks that together compose the images pixel data. @return [Array<ChunkyPNG::Chunk::ImageData>]

end_chunk[RW]

The empty chunk that signals the end of this datastream @return [ChunkyPNG::Chunk::Header]

header_chunk[RW]

The header chunk of this datastream. @return [ChunkyPNG::Chunk::Header]

other_chunks[RW]

All other chunks in this PNG file. @return [Array<ChunkyPNG::Chunk::Generic>]

palette_chunk[RW]

The chunk containing the image's palette. @return [ChunkyPNG::Chunk::Palette]

transparency_chunk[RW]

The chunk containing the transparency information of the palette. @return [ChunkyPNG::Chunk::Transparency]

### Public Class Methods

empty_bytearray() click to toggle source

Returns an empty stream using binary encoding that can be used as stream to encode to. @return [String] An empty, binary string.

    # File lib/chunky_png/datastream.rb, line 157
    def self.empty_bytearray
      ChunkyPNG::EMPTY_BYTEARRAY.dup
    end

from_blob(str) click to toggle source

Reads a PNG datastream from a string. @param [String] str The PNG encoded string to load from. @return [ChunkyPNG::Datastream] The loaded datastream instance.

    # File lib/chunky_png/datastream.rb, line 55
    def from_blob(str)
      from_io(StringIO.new(str))
    end

Also aliased as: from_string
from_file(filename) click to toggle source

Reads a PNG datastream from a file. @param [String] filename The path of the file to load from. @return [ChunkyPNG::Datastream] The loaded datastream instance.

    # File lib/chunky_png/datastream.rb, line 64
    def from_file(filename)
      ds = nil
      File.open(filename, 'rb') { |f| ds = from_io(f) }
      ds
    end

from_io(io) click to toggle source

Reads a PNG datastream from an input stream @param [IO] io The stream to read from. @return [ChunkyPNG::Datastream] The loaded datastream instance.

    # File lib/chunky_png/datastream.rb, line 73
    def from_io(io)
      verify_signature!(io)

      ds = self.new
      until io.eof?
        chunk = ChunkyPNG::Chunk.read(io)
        case chunk
          when ChunkyPNG::Chunk::Header;       ds.header_chunk = chunk
          when ChunkyPNG::Chunk::Palette;      ds.palette_chunk = chunk
          when ChunkyPNG::Chunk::Transparency; ds.transparency_chunk = chunk
          when ChunkyPNG::Chunk::ImageData;    ds.data_chunks << chunk
          when ChunkyPNG::Chunk::End;          ds.end_chunk = chunk
          else ds.other_chunks << chunk
        end
      end
      return ds
    end

from_string(str) click to toggle source
Alias for: from_blob
new() click to toggle source

Initializes a new Datastream instance.

    # File lib/chunky_png/datastream.rb, line 41
    def initialize
      @other_chunks = []
      @data_chunks  = []
    end

verify_signature!(io) click to toggle source

Verifies that the current stream is a PNG datastream by checking its signature.

This method reads the PNG signature from the stream, setting the current position of the stream directly after the signature, where the IHDR chunk should begin.

@param [IO] io The stream to read the PNG signature from. @raise [RuntimeError] An exception is raised if the PNG signature is not found at

    the beginning of the stream.

    # File lib/chunky_png/datastream.rb, line 99
    def verify_signature!(io)
      signature = io.read(ChunkyPNG::Datastream::SIGNATURE.length)
      unless ChunkyPNG.force_binary(signature) == ChunkyPNG::Datastream::SIGNATURE
        raise ChunkyPNG::SignatureMismatch, "PNG signature not found, found #{signature.inspect} instead of #{ChunkyPNG::Datastream::SIGNATURE.inspect}!"
      end
    end

### Public Instance Methods

chunks() click to toggle source

Returns an enumerator instance for this datastream's chunks. @return [Enumerable::Enumerator] An enumerator for the :each_chunk method. @see ChunkyPNG::Datastream#each_chunk

    # File lib/chunky_png/datastream.rb, line 131
    def chunks
      enum_for(:each_chunk)
    end

each_chunk() click to toggle source

Enumerates the chunks in this datastream.

This will iterate over the chunks using the order in which the chunks should appear in the PNG file.

@yield [chunk] Yields the chunks in this datastream, one by one in the correct order. @yieldparam [ChunkyPNG::Chunk::Base] chunk A chunk in this datastream. @see ChunkyPNG::Datastream#chunks

    # File lib/chunky_png/datastream.rb, line 119
    def each_chunk
      yield(header_chunk)
      other_chunks.each { |chunk| yield(chunk) }
      yield(palette_chunk)      if palette_chunk
      yield(transparency_chunk) if transparency_chunk
      data_chunks.each  { |chunk| yield(chunk) }
      yield(end_chunk)
    end

imagedata() click to toggle source

Returns the uncompressed image data, combined from all the IDAT chunks @return [String] The uncompressed image data for this datastream

    # File lib/chunky_png/datastream.rb, line 147
    def imagedata
      ChunkyPNG::Chunk::ImageData.combine_chunks(data_chunks)
    end

metadata() click to toggle source

Returns all the textual metadata key/value pairs as hash. @return [Hash] A hash containing metadata fields and their values.

    # File lib/chunky_png/datastream.rb, line 137
    def metadata
      metadata = {}
      other_chunks.select do |chunk|
        metadata[chunk.keyword] = chunk.value if chunk.respond_to?(:keyword)
      end
      metadata
    end

save(filename) click to toggle source

Saves this datastream as a PNG file. @param [String] filename The filename to use.

    # File lib/chunky_png/datastream.rb, line 170
    def save(filename)
      File.open(filename, 'wb') { |f| write(f) }
    end

to_blob() click to toggle source

Encodes this datastream into a string. @return [String] The encoded PNG datastream.

    # File lib/chunky_png/datastream.rb, line 176
    def to_blob
      str = StringIO.new
      write(str)
      return str.string
    end

Also aliased as: to_string, to_s
to_s() click to toggle source
Alias for: to_blob
to_string() click to toggle source
Alias for: to_blob
write(io) click to toggle source

Writes the datastream to the given output stream. @param [IO] io The output stream to write to.

    # File lib/chunky_png/datastream.rb, line 163
    def write(io)
      io << SIGNATURE
      each_chunk { |c| c.write(io) }
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.