Module: Devil

Includes:
IL, ILU
Defined in:
lib/devil.rb,
lib/devil/version.rb

Overview

Provides a high level wrapper for the low-level DevIL Ruby bindings

Defined Under Namespace

Classes: Image

Constant Summary collapse

VERSION = 
"0.1.9.5"

Constants included from ILU

ILU::BILINEAR, ILU::CENTER, ILU::FILTER, ILU::LINEAR, ILU::LOWER_LEFT, ILU::LOWER_RIGHT, ILU::NEAREST, ILU::PLACEMENT, ILU::SCALE_BELL, ILU::SCALE_BOX, ILU::SCALE_BSPLINE, ILU::SCALE_LANCZOS3, ILU::SCALE_MITCHELL, ILU::SCALE_TRIANGLE, ILU::UPPER_LEFT, ILU::UPPER_RIGHT

Constants included from IL

IL::BAD_DIMENSIONS, IL::BGR, IL::BGRA, IL::BMP, IL::CHEAD, IL::COLOR_INDEX, IL::COLOUR_INDEX, IL::CONV_PAL, IL::COULD_NOT_OPEN_FILE, IL::CUR_IMAGE, IL::CUT, IL::DCX, IL::DDS, IL::DOOM, IL::DOOM_FLAT, IL::DOUBLE, IL::EXIF, IL::FILE_ALREADY_EXISTS, IL::FILE_OVERWRITE, IL::FILE_READ_ERROR, IL::FILE_WRITE_ERROR, IL::FLOAT, IL::FORMAT_NOT_SUPPORTED, IL::GIF, IL::HDR, IL::ICO, IL::ILLEGAL_FILE_VALUE, IL::ILLEGAL_OPERATION, IL::IMAGE_BITS_PER_PIXEL, IL::IMAGE_BYTES_PER_PIXEL, IL::IMAGE_DEPTH, IL::IMAGE_FORMAT, IL::IMAGE_HEIGHT, IL::IMAGE_WIDTH, IL::INT, IL::INTERNAL_ERROR, IL::INVALID_CONVERSION, IL::INVALID_ENUM, IL::INVALID_EXTENSION, IL::INVALID_FILE_HEADER, IL::INVALID_PARAM, IL::INVALID_VALUE, IL::JASC_PAL, IL::JFIF, IL::JNG, IL::JPG, IL::JPG_QUALITY, IL::LBM, IL::LIB_GIF_ERROR, IL::LIB_JPEG_ERROR, IL::LIB_MNG_ERROR, IL::LIB_PNG_ERROR, IL::LIB_TIFF_ERROR, IL::LIF, IL::LUMINANCE, IL::LUMINANCE_ALPHA, IL::MDL, IL::MNG, IL::NO_ERROR, IL::ORIGIN_LOWER_LEFT, IL::ORIGIN_SET, IL::ORIGIN_UPPER_LEFT, IL::OUT_FORMAT_SAME, IL::OUT_OF_MEMORY, IL::PCD, IL::PCX, IL::PIC, IL::PIX, IL::PNG, IL::PNM, IL::PSD, IL::PSP, IL::PXR, IL::RAW, IL::RGB, IL::RGBA, IL::SGI, IL::SHORT, IL::STACK_OVERFLOW, IL::STACK_UNDERFLOW, IL::TGA, IL::TIF, IL::TYPE_UNKNOWN, IL::UNKNOWN_ERROR, IL::UNSIGNED_BYTE, IL::UNSIGNED_INT, IL::UNSIGNED_SHORT, IL::WAL, IL::XPM

Class Method Summary collapse

Methods included from ILU

Alienify, BlurAvg, BlurGaussian, BuildMipmaps, CompareImage, Contrast, Crop, EdgeDetectP, EdgeDetectS, Emboss, EnlargeCanvas, Equalize, ErrorString, FlipImage, GammaCorrect, ImageParameter, Init, Mirror, Negative, Noisify, Pixelize, Rotate, Scale, Sharpen, SwapColours

Methods included from IL

ActiveImage, ActiveMipmap, ApplyProfile, BindImage, Blit, ClearColour, ClearImage, CloneCurImage, ConvertImage, CopyImage, DeleteImages, Disable, Enable, FromBlob, GenImages, GetData, GetError, GetInteger, Init, Load, LoadImage, OriginFunc, OverlayImage, Save, SaveImage, SetData, SetInteger, SetPixels, TexImage, ToBlob

Class Method Details

.create_image(width, height, options = {}, &block) ⇒ Object Also known as: create_blank_image

returns a blank image of width and height. Optionally accepts the :color hash param that fills the new image with a color (see: Devil.set_options :clear_color) Optionally accepts a block and yields the newly created image to the block.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/devil.rb', line 50

def create_image(width, height, options={}, &block)
    name = prepare_image
    out_profile = options[:out_profile]
    in_profile = options[:in_profile]

    clear_color = options[:color]

    # created image is formatted RGBA8
    IL.TexImage(width, height, 1, 4, IL::RGBA, IL::UNSIGNED_BYTE, nil)

    # apply a color profile if one is provided
    IL.ApplyProfile(in_profile, out_profile) if out_profile            

    IL.ClearColour(*clear_color) if clear_color
    IL.ClearImage
    IL.ClearColour(*Devil.get_options[:clear_color]) if clear_color

    check_and_run_hook(:create_image_hook)
    error_check
    wrap_and_yield(name, nil, block)
end

.from_blob(blob, width, height) ⇒ Object

convert an image blob with width and height to a bona fide image



103
104
105
106
107
108
109
110
 
# File 'lib/devil.rb', line 103

def from_blob(blob, width, height)
  
    # try to convert automatically from array to packed string
    # if passed an array
    blob = blob.pack("C*") if blob.instance_of?(Array)
  
    Image.new(IL.FromBlob(blob, width, height), nil)
end

.get_options ⇒ Object

return the current Devil configuration.



155
156
157
 
# File 'lib/devil.rb', line 155

def get_options
    @options
end

.init ⇒ Object

initializes Devil and sets defaults. This method should never need to be called directly.



161
162
163
164
165
166
167
 
# File 'lib/devil.rb', line 161

def init
    # initialize DevIL
    IL.Init
    ILU.Init

    set_defaults
end

.load_image(file, options = {}, &block) ⇒ Object Also known as: with_image, load

loads file and returns a new image Optionally accepts a block and yields the newly created image to the block.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
# File 'lib/devil.rb', line 28

def load_image(file, options={}, &block)
    name = prepare_image
    attach_image_from_file(file)
    
    out_profile = options[:out_profile]
    in_profile = options[:in_profile]
    
    # apply a color profile if one is provided
    IL.ApplyProfile(in_profile, out_profile) if out_profile

    check_and_run_hook(:load_image_hook)
    error_check
    wrap_and_yield(name, file, block)
end

.set_defaults ⇒ Object Also known as: restore_defaults

restore Devil’s default configuration.



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/devil.rb', line 170

def set_defaults
    @options = {
        :scale_filter => ILU::SCALE_LANCZOS3,
        :edge_filter => :prewitt,
        :window_size => [1024, 768],
        :clear_color => [255, 248, 230, 0],
        :placement => ILU::CENTER,
        :prepare_image_hook => nil,
        :load_image_hook => nil,
        :create_image_hook => nil,
        :jpg_quality => 99
    }
    
    # configurable options
    ILU.ImageParameter(ILU::FILTER, @options[:scale_filter])
    ILU.ImageParameter(ILU::PLACEMENT, @options[:placement])
    IL.SetInteger(IL::JPG_QUALITY, @options[:jpg_quality])
    IL.ClearColour(*@options[:clear_color])

    # fixed options
    IL.Enable(IL::FILE_OVERWRITE)
    IL.Enable(IL::ORIGIN_SET)
    IL.OriginFunc(IL::ORIGIN_LOWER_LEFT)
end

.set_options(options = {}) ⇒ Object

configure Devil. accepts hash parameters: :scale_filter, :placement, :clear_color, :window_size, :edge_filter.

:scale_filter accepts a valid scaling algorithm: (default is LANCZOS3). Devil::NEAREST, Devil::LINEAR, Devil::BILINEAR, Devil::SCALE_BOX, Devil::SCALE_TRIANGLE, Devil::SCALE_BELL, Devil::SCALE_BSPLINE, Devil::SCALE_LANCZOS3, Devil::SCALE_MITCHELL

:placement determines where in the canvas the image will be placed after the canvas has been enlarged using the ‘enlarge_canvas’ method. Valid parameters are: Devil::CENTER, Devil::LOWER_LEFT, Devil::UPPER_RIGHT, etc

:clear_color sets the current clearing colour to be used by future calls to clear. rotate and enlarge_canvas both use these values to clear blank space in images, too. e.g Devil.set_options(:clear_color => [255, 255, 0, 255]) Above sets the clear color to yellow with full opacity.

:window_size sets the display window size Gosu will use when displaying images that invoked the ‘show’ method. (default is 1024 x 768) e.g Devil.set_options(:window_size => [2000, 768]) Example above sets a window size of 2000x768. Note: :window_size is only relevant when require ‘devil/gosu’ is used.

:edge_filter sets the edge detection algorithm to use when invoking the ‘edge_detect’ method. (defaults to :prewitt) Allowed values are :prewitt and :sobel

hooks: :prepare_image_hook, :create_image_hook, :load_image_hook e.g Devil.set_options :load_image_hook => proc { IL::ConvertImage(IL::RGBA, IL::UNSIGNED_BYTE) }



144
145
146
147
148
149
150
151
152
 
# File 'lib/devil.rb', line 144

def set_options(options={})
    @options.merge!(options)

    # update the config. options 
    ILU.ImageParameter(ILU::FILTER, @options[:scale_filter])
    ILU.ImageParameter(ILU::PLACEMENT, @options[:placement])
    IL.SetInteger(IL::JPG_QUALITY, @options[:jpg_quality])
    IL.ClearColour(*@options[:clear_color])
end

.with_group(*files, &block) ⇒ Object Also known as: with_images

load multiple images and yield them to the block e.g Devil.with_group(“hello.png”, “friend.png”) { |img1, img2| … } all yielded images are cleaned up at end of block so you do not need to explictly call img1.free



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/devil.rb', line 78

def with_group(*files, &block)
    images = files.map do |file|
        name = prepare_image
        attach_image_from_file(file)
        check_and_run_hook(:load_image_hook)
        error_check
        
        Image.new(name, file)
    end

    if block
        begin
            block.call(*images)
        ensure
            images.each { |img| img.free if img.name }
        end
    else
        raise RuntimeError, "a block must be provided."
    end
end