Class: FreeImage::Bitmap

Inherits:
FFI::AutoPointer
  • Object
show all
Includes:
Conversions, ICC, Information, Modify, Pixels, Transforms
Defined in:
lib/free-image/bitmap.rb

Overview

Summary

Represents an image that has been loaded into memory. Once the image is loaded, you can get information about it, convert it, modify it. transform it,

Usage

# Open an image form a file
image = FreeImage::BitmapFile.open('test/fixtures/lena.png')

# Get information about it
bg = image.background_color

# Convert it
image = image.convert_to_greyscale

# Modify it
image = image.convert_to_greyscale

# Transform it
image = image.rotate(90)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Transforms

#flip_horizontal!, #flip_vertical!, #rotate, #rotate_ex

Methods included from Pixels

#bits, #pixel_color, #pixel_index, #scanline, #set_pixel_color, #set_pixel_index

Methods included from Modify

#composite, #composite_with_color, #copy, #enlarge_canvas, #fill_background!, #make_thumbnail, #paste!, #rescale

Methods included from Information

#background_color, #background_color=, #bits_per_pixel, #blue_mask, #color_type, #dib_size, #dots_per_meter_x, #dots_per_meter_x=, #dots_per_meter_y, #dots_per_meter_y=, #green_mask, #has_background_color, #has_pixels, #height, #image_type, #info_header, #line, #memory_size, #palette, #pitch, #red_mask, #transparency_count, #transparent, #transparent=, #transparent_index, #transparent_index=, #width

Methods included from ICC

#icc_profile, #icc_profile=, #icc_supported?

Methods included from Conversions

#convert_to_16bits_555, #convert_to_16bits_565, #convert_to_24bits, #convert_to_32bits, #convert_to_4bits, #convert_to_8bits, #convert_to_greyscale, #convert_to_standard_type, #convert_to_type, #dither, #threshold

Constructor Details

#initialize(ptr, source = nil) ⇒ Bitmap

Creates a new image from a c-pointer an image source. Generally you do not want to use this method. Instead, use Bitmap.open.



130
131
132
133
 
# File 'lib/free-image/bitmap.rb', line 130

def initialize(ptr, source = nil)
  @source = source
  super(ptr)
end

Instance Attribute Details

#source ⇒ Object (readonly)

The source of the image. May be a File, in Memory string, IO stream or nil.



46
47
48
 
# File 'lib/free-image/bitmap.rb', line 46

def source
  @source
end

Class Method Details

.create(width, height, bits_per_pixel, red_mask = 0, green_mask = 0, blue_mask = 0) ⇒ Object

Creates a new image with the specified width, height and bits per pixel.

Parameters

width

The width of the new image

height

The height of the new image

bits_per_pixel

The size in bits of a pixel

red_mask

The bit-layout of the red color component in a bitmap

green_mask:P: The bit-layout of the green color component in a bitmap

blue_mask

The bit-layout of the blue color component in a bitmap

The last three parameter are used to tell FreeImage the bit-layout of the color components in the bitmap, e.g. where in a pixel the red, green and blue components are stored.

To give you an idea about how to interpret the color masks: when red_mask is 0xFF000000 this means that the last 8 bits in one pixel are used for the color red. When green_mask is 0x000000FF, it means that the first 8 bits in a pixel are used for the color green.

The new image is initially filled completely with zeroes. Zero in a image is usually interpreted as black. This means that if your bitmap is palletized it will contain a completely black palette. You can access, and hence populate the palette via #palette.

For 8-bit images, a default greyscale palette will also be created.



74
75
76
77
78
 
# File 'lib/free-image/bitmap.rb', line 74

def self.create(width, height, bits_per_pixel, red_mask = 0, green_mask = 0, blue_mask = 0)
  ptr = FreeImage.FreeImage_Allocate(width, height, bits_per_pixel, red_mask, green_mask, blue_mask)
  FreeImage.check_last_error
  new(ptr)
end

.new(ptr, source = nil) ⇒ Object 



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/free-image/bitmap.rb', line 100

def self.new(ptr, source = nil)
  # Ptr must be set
  if ptr.null?
    error = Error.new(:unknown, "Cannot create a bitmap from a null pointer")
    raise(error)
  end

  bitmap = super(ptr, source)

  if block_given?
    begin
      yield bitmap
    ensure
      bitmap.free
    end
  else
    bitmap
  end
end

.open(source) ⇒ Object

Opens a new image from the specified source.

Parameters

source

The source of the image

The source parameter can be a File, Memory or IO stream. It can also be a string which is interpreted as a fully qualified file path.



87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/free-image/bitmap.rb', line 87

def self.open(source)
  bitmap = figure_source(source).open
  if block_given?
    begin
      yield bitmap
    ensure
      bitmap.free
    end
  else
    bitmap
  end
end

.release(ptr) ⇒ Object

Closes an image and releases its associated memory. This is called by the ruby Garbage collector and should not be called directly. If you would like to free an image after using it, please use Bitmap#free.



124
125
126
 
# File 'lib/free-image/bitmap.rb', line 124

def self.release(ptr) #:nodoc:
  FreeImage.FreeImage_Unload(ptr)
end

Instance Method Details

#clone(&block) ⇒ Object

:call-seq:

image.clone -> bitmap
image.clone {|img| block} -> bitmap

Creates an exact copy of the current image.

If an optional block is provided, it will be passed the new image as an argument. The image will be automatically closed when the block completes.



144
145
146
147
148
 
# File 'lib/free-image/bitmap.rb', line 144

def clone(&block)
  ptr = FreeImage.FreeImage_Clone(self)
  FreeImage.check_last_error
  self.class.new(ptr, &block)
end

#save(source, format, flags = 0) ⇒ Object

Save the image to the specified source.

Parameters

dst

The destination where the image will be saved.

format

The format to save the image to.

flags

Format specific flags that control how a bitmap is saved. These flags are defined as constants on the AbstractSource class. Flags can be combined using Ruby’s bitwise or operator (|)



159
160
161
 
# File 'lib/free-image/bitmap.rb', line 159

def save(source, format, flags = 0)
  self.class.figure_source(source).save(self, format, flags)
end