sdl2-image-2.1.0.0: Haskell bindings to SDL2_image

Copyright | (c) 2015 Siniša Biđin 2021 Daniel Firth
License | MIT
Maintainer | sinisa@bidin.eu, dan.firth@homotopic.tech
Stability | experimental
Safe Haskell | None
Language | Haskell2010

SDL.Image

Contents

- Loading images
- Loading TGA images
- Format detection
- Other

Description

Bindings to the `SDL2_image` library. These should allow you to load various types of images as `SDL` `Surface`s, as well as detect image formats.

You can safely assume that any monadic function listed here is capable of throwing an `SDLException` in case it encounters an error.

Synopsis

- load :: MonadIO m => FilePath -> m Surface
- decode :: MonadIO m => ByteString -> m Surface
- loadTexture :: MonadIO m => Renderer -> FilePath -> m Texture
- decodeTexture :: MonadIO m => Renderer -> ByteString -> m Texture
- loadTGA :: MonadIO m => FilePath -> m Surface
- decodeTGA :: MonadIO m => ByteString -> m Surface
- loadTextureTGA :: MonadIO m => Renderer -> FilePath -> m Texture
- decodeTextureTGA :: MonadIO m => Renderer -> ByteString -> m Texture
- formattedAs :: Format -> ByteString -> Bool
- format :: ByteString -> Maybe Format
- data Format
  - = CUR
  - | ICO
  - | BMP
  - | PNM
  - | XPM
  - | XCF
  - | PCX
  - | GIF
  - | LBM
  - | XV
  - | JPG
  - | PNG
  - | TIF
  - | WEBP
- initialize :: (Foldable f, MonadIO m) => f InitFlag -> m ()
- data InitFlag
  - = InitJPG
  - | InitPNG
  - | InitTIF
  - | InitWEBP
- version :: (Integral a, MonadIO m) => m (a, a, a)
- quit :: MonadIO m => m ()

# Loading images

Use the following functions to read any `PNG`, `JPG`, `TIF`, `GIF`, `WEBP`, `CUR`, `ICO`, `BMP`, `PNM`, `XPM`, `XCF`, `PCX` and `XV` formatted data.

If you have `TGA`-formatted data, you might wish to use the functions from the following section instead.

load :: MonadIO m => FilePath -> m Surface Source #

Loads any given file of a supported image type as a `Surface`, including `TGA` if the filename ends with `".tga"`.

If you have `TGA` files that don't have names ending with `".tga"`, use `loadTGA` instead.

decode :: MonadIO m => ByteString -> m Surface Source #

Reads an image from a `ByteString`.

This will work for all supported image types, except TGA. If you need to decode a `TGA` `ByteString`, use `decodeTGA` instead.

loadTexture :: MonadIO m => Renderer -> FilePath -> m Texture Source #

Same as `load`, but returning a `Texture` instead.

For `TGA` files not ending in ".tga", use `loadTextureTGA` instead.

decodeTexture :: MonadIO m => Renderer -> ByteString -> m Texture Source #

Same as `decode`, but returning a `Texture` instead.

If you need to decode a `TGA` `ByteString`, use `decodeTextureTGA` instead.

# Loading TGA images

Since `TGA` images don't contain a specific unique signature, the following functions might succeed even when given files not formatted as `TGA` images.

Only use these functions if you're certain the inputs are `TGA`-formatted, otherwise they'll throw an exception.

loadTGA :: MonadIO m => FilePath -> m Surface Source #

If your `TGA` files aren't in a filename ending with `".tga"`, you can load them using this function.

decodeTGA :: MonadIO m => ByteString -> m Surface Source #

Reads a `TGA` image from a `ByteString`.

Assumes the input is a `TGA`-formatted image.

loadTextureTGA :: MonadIO m => Renderer -> FilePath -> m Texture Source #

Same as `loadTGA`, only returning a `Texture` instead.

decodeTextureTGA :: MonadIO m => Renderer -> ByteString -> m Texture Source #

Same as `decodeTGA`, but returns a `Texture` instead.

# Format detection

formattedAs :: Format -> ByteString -> Bool Source #

Tests whether a `ByteString` contains an image of a given format.

format :: ByteString -> Maybe Format Source #

Tries to detect the image format by attempting `formattedAs` with each possible `Format`.

If you're trying to test for a specific format, use a specific `formattedAs` directly instead.

data Format Source #

Each of the supported image formats.

Constructors

CUR |
ICO |
BMP |
PNM |
XPM |
XCF |
PCX |
GIF |
LBM |
XV |
JPG |
PNG |
TIF |
WEBP |

#### Instances

Instances details

Bounded Format Source # |
Instance details Defined in SDL.Image Methods minBound :: Format Source # maxBound :: Format Source #
Enum Format Source # |
Instance details Defined in SDL.Image Methods succ :: Format -> Format Source # pred :: Format -> Format Source # toEnum :: Int -> Format Source # fromEnum :: Format -> Int Source # enumFrom :: Format -> [Format] Source # enumFromThen :: Format -> Format -> [Format] Source # enumFromTo :: Format -> Format -> [Format] Source # enumFromThenTo :: Format -> Format -> Format -> [Format] Source #
Generic Format Source # |

Instance details

Defined in SDL.Image

Associated Types

type Rep Format |

Instance details

Defined in SDL.Image

type Rep Format = D1 ('MetaData "Format" "SDL.Image" "sdl2-image-2.1.0.0-F8r9WuPZxNoEKf0vV44rRX" 'False) (((C1 ('MetaCons "CUR" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "ICO" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "BMP" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "PNM" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "XPM" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "XCF" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PCX" 'PrefixI 'False) (U1 :: Type -> Type)))) :+: ((C1 ('MetaCons "GIF" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "LBM" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "XV" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "JPG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PNG" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "TIF" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WEBP" 'PrefixI 'False) (U1 :: Type -> Type)))))

Methods

from :: Format -> Rep Format x Source #

to :: Rep Format x -> Format Source #

Read Format Source # |
Instance details Defined in SDL.Image Methods readsPrec :: Int -> ReadS Format Source # readList :: ReadS [Format] Source # readPrec :: ReadPrec Format Source # readListPrec :: ReadPrec [Format] Source #
Show Format Source # |
Instance details Defined in SDL.Image Methods showsPrec :: Int -> Format -> ShowS Source # show :: Format -> String Source # showList :: [Format] -> ShowS Source #
Eq Format Source # |
Instance details Defined in SDL.Image Methods (==) :: Format -> Format -> Bool Source # (/=) :: Format -> Format -> Bool Source #
Ord Format Source # |
Instance details Defined in SDL.Image Methods compare :: Format -> Format -> Ordering Source # (<) :: Format -> Format -> Bool Source # (<=) :: Format -> Format -> Bool Source # (>) :: Format -> Format -> Bool Source # (>=) :: Format -> Format -> Bool Source # max :: Format -> Format -> Format Source # min :: Format -> Format -> Format Source #
type Rep Format Source # |

Instance details

Defined in SDL.Image

type Rep Format = D1 ('MetaData "Format" "SDL.Image" "sdl2-image-2.1.0.0-F8r9WuPZxNoEKf0vV44rRX" 'False) (((C1 ('MetaCons "CUR" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "ICO" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "BMP" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "PNM" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "XPM" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "XCF" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PCX" 'PrefixI 'False) (U1 :: Type -> Type)))) :+: ((C1 ('MetaCons "GIF" 'PrefixI 'False) (U1 :: Type -> Type) :+: (C1 ('MetaCons "LBM" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "XV" 'PrefixI 'False) (U1 :: Type -> Type))) :+: ((C1 ('MetaCons "JPG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "PNG" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "TIF" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "WEBP" 'PrefixI 'False) (U1 :: Type -> Type)))))

# Other

initialize :: (Foldable f, MonadIO m) => f InitFlag -> m () Source #

Initializes `SDL2_image` by loading support for the chosen image formats. Explicit initialization is optional.

You should call this function if you prefer to load image support yourself, at a time when your process isn't as busy. Otherwise, image support will be loaded dynamically when you attempt to load a `JPG`, `PNG`, `TIF` or `WEBP`-formatted file.

You may call this function multiple times.

data InitFlag Source #

Flags intended to be fed to `initialize`.

Each designates early loading of support for a particular image format.

Constructors

InitJPG | Load support for reading `JPG` files.
InitPNG | Same, but for `PNG` files.
InitTIF | `TIF` files.
InitWEBP | `WEBP` files.

#### Instances

Instances details

Bounded InitFlag Source # |
Instance details Defined in SDL.Image Methods minBound :: InitFlag Source # maxBound :: InitFlag Source #
Enum InitFlag Source # |

Instance details

Defined in SDL.Image

Methods

succ :: InitFlag -> InitFlag Source #

pred :: InitFlag -> InitFlag Source #

toEnum :: Int -> InitFlag Source #

fromEnum :: InitFlag -> Int Source #

enumFrom :: InitFlag -> [InitFlag] Source #

enumFromThen :: InitFlag -> InitFlag -> [InitFlag] Source #

enumFromTo :: InitFlag -> InitFlag -> [InitFlag] Source #

enumFromThenTo :: InitFlag -> InitFlag -> InitFlag -> [InitFlag] Source #

Generic InitFlag Source # |

Instance details

Defined in SDL.Image

Associated Types

type Rep InitFlag |

Instance details

Defined in SDL.Image

type Rep InitFlag = D1 ('MetaData "InitFlag" "SDL.Image" "sdl2-image-2.1.0.0-F8r9WuPZxNoEKf0vV44rRX" 'False) ((C1 ('MetaCons "InitJPG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InitPNG" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "InitTIF" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InitWEBP" 'PrefixI 'False) (U1 :: Type -> Type)))

Methods

from :: InitFlag -> Rep InitFlag x Source #

to :: Rep InitFlag x -> InitFlag Source #

Read InitFlag Source # |
Instance details Defined in SDL.Image Methods readsPrec :: Int -> ReadS InitFlag Source # readList :: ReadS [InitFlag] Source # readPrec :: ReadPrec InitFlag Source # readListPrec :: ReadPrec [InitFlag] Source #
Show InitFlag Source # |
Instance details Defined in SDL.Image Methods showsPrec :: Int -> InitFlag -> ShowS Source # show :: InitFlag -> String Source # showList :: [InitFlag] -> ShowS Source #
Eq InitFlag Source # |
Instance details Defined in SDL.Image Methods (==) :: InitFlag -> InitFlag -> Bool Source # (/=) :: InitFlag -> InitFlag -> Bool Source #
Ord InitFlag Source # |
Instance details Defined in SDL.Image Methods compare :: InitFlag -> InitFlag -> Ordering Source # (<) :: InitFlag -> InitFlag -> Bool Source # (<=) :: InitFlag -> InitFlag -> Bool Source # (>) :: InitFlag -> InitFlag -> Bool Source # (>=) :: InitFlag -> InitFlag -> Bool Source # max :: InitFlag -> InitFlag -> InitFlag Source # min :: InitFlag -> InitFlag -> InitFlag Source #
type Rep InitFlag Source # |

Instance details

Defined in SDL.Image

type Rep InitFlag = D1 ('MetaData "InitFlag" "SDL.Image" "sdl2-image-2.1.0.0-F8r9WuPZxNoEKf0vV44rRX" 'False) ((C1 ('MetaCons "InitJPG" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InitPNG" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "InitTIF" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InitWEBP" 'PrefixI 'False) (U1 :: Type -> Type)))

version :: (Integral a, MonadIO m) => m (a, a, a) Source #

Gets the major, minor, patch versions of the linked `SDL2_image` library.

quit :: MonadIO m => m () Source #

Cleans up any loaded image libraries, freeing memory. You only need to call this function once.