This module provides pixel-oriented graphics operations.
It defines an
ImageBuffer type, which is a thin layer
over a GTK+
Pixbuf. It then provides functions for
doing pixel-oriented graphics on this without having to
do a lot of bit-twiddling math by hand. It also
provides for quickly and easily loading and saving
images, and displaying them on the screen.
In the simplest case, you can import this module alone and never need to touch the actual GTK modules; however, this module provides access to the underlying GTK resources as well, in case you want to use it as part of a larger GTK program.
Note that displaying an image on screen requires
you to run the GTK event loop. If you only want to
load, save and process image files, you can completely
ignore the GTK event loop. (You do still need to call
- init_system :: IO ()
- type Coord = Int
- type Channel = Word8
- data ImageFileType
- type_string :: ImageFileType -> String
- data ImageBuffer
- ib_new :: (Int, Int) -> IO ImageBuffer
- ib_load :: FilePath -> IO ImageBuffer
- ib_save :: ImageBuffer -> ImageFileType -> FilePath -> IO ()
- ib_size :: ImageBuffer -> (Coord, Coord)
- ib_coords :: ImageBuffer -> [(Coord, Coord)]
- ib_coords2 :: ImageBuffer -> [[(Coord, Coord)]]
- ib_valid_coords :: ImageBuffer -> (Coord, Coord) -> Bool
- ib_write_pixel :: ImageBuffer -> (Coord, Coord) -> (Channel, Channel, Channel) -> IO ()
- ib_read_pixel :: ImageBuffer -> (Coord, Coord) -> IO (Channel, Channel, Channel)
- ib_display :: ImageBuffer -> String -> IO ()
- ib_canvas :: ImageBuffer -> IO DrawingArea
- process_event :: IO ()
- wait_event :: IO ()
- main_loop :: IO ()
- ib_pixbuf :: ImageBuffer -> Pixbuf
Initialise the GTK runtime system. This function must
be called before any other functions in this module.
(If not, your program will likely summarily crash with
an obscure error to
Note that Gtk2hs by default will crash with a warning message if the program is compiled with the threaded RTS; this module disables that warning. However, be warned: You must only call the GTK-based functions from thread 0.
Used to indicate image file type.
ImageFileType to a plain string (all
ImageBuffer is a space-efficient grid of 24-bit
RGB pixels (i.e., 8 bits per channel) that the GTK
library can also access. (The latter gives us the
ability to load/save/display the graphics, rather
than just manipulate it in memory.)
Image buffer creation
Make a new
ImageBuffer of the specified size. Valid
coordinates will be in the range (0,0) to (x-1, y-1),
with (0,0) being the top-left corner of the image.
Image buffer output
Image buffer queries
Return all valid coordinates as a list of lists instead of a single flat list. (In case you need to do something at the end of each row.)
Determine whether the specified pixel coordinates are valid
ImageBuffer (i.e., check they're not off the
edge of the image).
Overwrite the specified pixel with the specified colour (R, G, B).
Note that pixel coordinates are not checked, for efficiency reasons. However, supplying invalid pixel coordinates may result in behaviour ranging from corrupted graphical output to random program crashes. See Graphics.EasyRaster.GTK.Paranoid for a version of this function with bounds checking turned on.
Read the current (R, G, B) colour valid of the specified pixel.
Note that pixel coordinates are not checked, for efficiency reasons. However, supplying invalid pixel coordinates will at best result in gibberish being returned, and at worst a segmentation fault. See Graphics.EasyRaster.Paranoid for a version of this function with bounds checking turned on.
This is a quick shortcut for displaying an image
on screen. Given an
ImageBuffer and a window
title, this will display the image in a new window.
Clicking the window's close button will call GTK's
mainQuit function. For example,
ib_display buf "My Window Title" main_loop
buf on screen and halt the program
(or at least thread 0) until the user clicks the
close button. Crude, but useful for quick testing.
Returns a GTK+ canvas object which displays the graphcs
ImageBuffer and will automatically repaint
itself in response to damage.
GTK event loop
Run the GTK "main loop" until GTK's
function is called. (Note that this means that
thread 0 can do no other work while the main
loop is running.)
Low-level GTK access
The following short program should give you an idea of how to use this library. It draws a simple graphic and saves it to disk.
module Main where import Graphics.EasyRaster.GTK main = do init_system ibuf <- ib_new (640, 480) mapM_ (\p -> ib_write_pixel ibuf p (colour p)) (ib_coords ibuf) ib_save ibuf IFT_PNG "Example1.png" colour :: (Coord, Coord) -> (Channel, Channel, Channel) colour (x, y) = (floor $ fromIntegral x / 640 * 255, floor $ fromIntegral y / 480 * 255, 0)