module

CrImage::ICO

ICO (Windows Icon) format support

ICO is a container format that stores multiple images at different resolutions in a single file. This is commonly used for favicons, application icons, and Windows desktop shortcuts.

Features

  • Multi-resolution support (up to 256 images per file)
  • Standard icon sizes: 16x16, 32x32, 48x48, 64x64, 128x128, 256x256
  • Full transparency support via alpha channel
  • BMP and PNG encoding support
  • Automatic format detection

Usage

# Write single icon
img = CrImage.rgba(32, 32)
CrImage::ICO.write("icon.ico", img)

# Write multi-resolution icon
icons = [16, 32, 48].map { |size| CrImage.rgba(size, size) }
CrImage::ICO.write_multi("favicon.ico", icons)

# Read icon (returns largest)
icon = CrImage::ICO.read("favicon.ico")

# Read all sizes
all = CrImage::ICO.read_all("favicon.ico")
largest = all.largest
icon_32 = all.find_size(32, 32)

Specification

https://en.wikipedia.org/wiki/ICO_(file_format)

Constants

CUR_MAGIC = Bytes[0, 0, 2, 0]

CUR (cursor) file header magic bytes

ICO_MAGIC = Bytes[0, 0, 1, 0]

ICO file header magic bytes

PNG_MAGIC = Bytes[137, 80, 78, 71]

PNG magic bytes for detecting PNG-encoded icons

Class methods

read(path : String) : CrImage::Image

Reads an ICO file and returns the largest icon

icon = CrImage::ICO.read("favicon.ico")
puts "#{icon.bounds.width}x#{icon.bounds.height}"
Source
read(io : IO) : CrImage::Image

Reads an ICO from IO and returns the largest icon

File.open("icon.ico", "rb") do |file|
  icon = CrImage::ICO.read(file)
end
Source
read_all(path : String) : Icon

Reads all icons from an ICO file

Returns an Icon object containing all images and their metadata. Use this when you need access to multiple resolutions.

all = CrImage::ICO.read_all("favicon.ico")
all.images.each_with_index do |img, i|
  puts "Size #{i}: #{img.bounds.width}x#{img.bounds.height}"
end
Source
read_all(io : IO) : Icon

Reads all icons from IO

Source
read_config(path : String) : CrImage::Config

Reads ICO configuration without decoding full image

Returns metadata for the largest icon. Faster than full read when you only need dimensions and color model.

config = CrImage::ICO.read_config("favicon.ico")
puts "#{config.width}x#{config.height}"
Source
read_config(io : IO) : CrImage::Config

Reads ICO configuration from IO without decoding full image

Source
write(path : String, image : CrImage::Image) : Nil

Writes a single image as an ICO file

Creates an ICO file containing one icon at the image's size. The image is encoded as 32-bit BMP with alpha channel.

img = CrImage.rgba(32, 32)
# ... draw icon ...
CrImage::ICO.write("icon.ico", img)
Source
write(io : IO, image : CrImage::Image) : Nil

Writes a single image to IO as ICO

Source
write_multi(path : String, images : Array(CrImage::Image)) : Nil

Writes multiple images as a multi-resolution ICO file

Creates an ICO file containing multiple icon sizes. This is the recommended format for favicons and application icons.

Standard sizes: 16, 32, 48, 64, 128, 256 pixels Maximum: 256 images per file

icons = [16, 32, 48].map do |size|
  img = CrImage.rgba(size, size)
  # ... draw icon at this size ...
  img
end
CrImage::ICO.write_multi("favicon.ico", icons)
Source
write_multi(io : IO, images : Array(CrImage::Image)) : Nil

Writes multiple images to IO as multi-resolution ICO

Source

Nested types