Graphics.EasyRaster.GTK.Paranoid

This module provides exactly the same interface as Graphics.EasyRaster.GTK, but with run-time sanity checks. This results in greater safety and reduced performance. Typically you will use this module while developing and debugging your application, and then change your import statement when you're happy that any bugs have been corrected.

System initialisation

init_system :: IO ()

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 stderr.)

Note that Gtk2hs will crash with a warning message if the program is compiled with the threaded RTS. (Use the non-paranoid version of init_system to turn this warning off.)

Types

type Coord = Int

The type of pixel coordinates.

type Channel = Word8

The type of pixel channels.

data ImageFileType

Used to indicate image file type.

Constructors

IFT_PNG

PNG image.

IFT_JPEG

JPEG image.

Instances

Bounded ImageFileType

Enum ImageFileType

Eq ImageFileType

Read ImageFileType

Show ImageFileType

type_string :: ImageFileType -> String

Convert an ImageFileType to a plain string (all lower-case).

data ImageBuffer

An 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

ib_new :: (Int, Int) -> IO ImageBuffer

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.

ib_load :: FilePath -> IO ImageBuffer

Load a graphics file into a newly created ImageBuffer. The file type is determined automatically (any type that GTK+ supports), as is the size for the ImageBuffer. (This can be queried later.)

Image buffer output

ib_save :: ImageBuffer -> ImageFileType -> FilePath -> IO ()

Save an ImageBuffer into a file with the specified file type. Note that the filename should include an appropriate suffix (e.g., .png). The type of file is determined by the ImageFileType argument, not by the filename.

Image buffer queries

ib_size :: ImageBuffer -> (Coord, Coord)

Query the size of an ImageBuffer. This returns the width and height in pixels. Valid coordinates for this ImageBuffer are from (0,0) to (x-1, y-1), where (x,y) is the value returned from ib_size.

Note that this is a pure function (since the size of an ImageBuffer is immutable).

ib_coords :: ImageBuffer -> [(Coord, Coord)]

Return a list containing all valid coordinates for this ImageBuffer. Useful when you want to process all pixels in the image; now you can just use mapM or whatever.

ib_coords2 :: ImageBuffer -> [[(Coord, Coord)]]

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.)

ib_valid_coords :: ImageBuffer -> (Coord, Coord) -> Bool

Determine whether the specified pixel coordinates are valid for this ImageBuffer (i.e., check they're not off the edge of the image).

Pixel I/O

ib_write_pixel :: ImageBuffer -> (Coord, Coord) -> (Channel, Channel, Channel) -> IO ()

Overwrite the specified pixel with the (R, G, B) colour.

If the pixel coordinates are out of range, the error function is called.

ib_read_pixel :: ImageBuffer -> (Coord, Coord) -> IO (Channel, Channel, Channel)

Read the (R, G, B) colour of the specified pixel.

If the pixel coordinates are out of range, the error function is called.

Image display

ib_display :: ImageBuffer -> String -> IO ()

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

will display 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.

ib_canvas :: ImageBuffer -> IO DrawingArea

Returns a GTK+ canvas object which displays the graphcs in the ImageBuffer and will automatically repaint itself in response to damage.

GTK event loop

process_event :: IO ()

Process one GTK event if there are any waiting, otherwise do nothing.

wait_event :: IO ()

Process one GTK event. Wait for an event to arrive if necessary.

main_loop :: IO ()

Run the GTK "main loop" until GTK's mainQuit 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

ib_pixbuf :: ImageBuffer -> Pixbuf

Return the underlying GTK Pixbuf used by an ImageBuffer. (In case you want to do something to it with GTK.)

Example code

See Graphics.EasyRaster.GTK for examples.