declarative image composition using sdl2 (fork of seppeljordan's sdl2-compositor)

root

* Introduction
  This package provides tools for simple image composition through the
  means of the SDL library, version 2.  You can combine, translate,
  rotate, blend, modulate colors and draw in a declarative way.

* Example

  The following program draws a rectangle to the screen, pauses for 5
  seconds and terminates afterwards.  See the comments for further
  explanation.

  #+begin_src haskell :tangle example.hs
    import Control.Concurrent (threadDelay)
    import Data.Text (pack)
    import Linear.V2 (V2(..))
    import Linear.V4 (V4(..))
    import SDL (initialize, InitFlag(InitVideo), createWindow, defaultWindow,
                createRenderer, RendererConfig(rendererTargetTexture), defaultRenderer,
                rendererLogicalSize, ($=), present, clear, quit,
                BlendMode(BlendAlphaBlend))
    import SDL.Compositor (filledRectangleC, rotateC, translateC, runRenderer, overC,
                           modulateAlphaM, preserveBlendMode)

    main :: IO ()
    main = do
      -- intialize SDL
      initialize [InitVideo]
      -- create a window
      window <- createWindow (pack "test window") defaultWindow
      -- create a renderer for the window
      rend <- createRenderer window (-1) (defaultRenderer {rendererTargetTexture = True})
      -- set the logical size of the window to 800x600
      rendererLogicalSize rend $= (Just (V2 800 600))
      -- clear the renderer
      clear rend
      let
        -- 3 rectangles, one in red, one in green and one in blue, width:
        -- 100, height 150
        rectRed = filledRectangleC (V2 100 150) (V4 255 100 100 255)
        rectGreen = filledRectangleC (V2 100 150) (V4 100 255 100 255)
        rectBlue = filledRectangleC (V2 100 150) (V4 100 100 255 255)
        -- translate an image by (250,300) pixels
        translateToCenter = translateC (V2 250 300)
      -- draw everything
      runRenderer rend
        ( ( -- enable alpha blending for the whole subtree
            preserveBlendMode BlendAlphaBlend .
            -- make all the images slightly transparent
            modulateAlphaM 150 .
            -- align the images in the center
            translateToCenter
          )
          ( -- red, green and blue
            rectRed `overC`
            translateC (V2 150 0) (rectGreen `overC`
                                   translateC (V2 150 0) rectBlue)
          )
        )
      -- show the drawn image on the screen
      present rend
      -- pause for 5 seconds
      threadDelay (5 * (10::Int)^(6::Int))
      -- quit SDL
      quit
  #+end_src

* Usage
  You compose images from two kinds of primitives: textures and
  shapes.  Generate a texture through the usual means of SDL.  Use
  =sizedCompositingLeaf= generate a compositional element of the
  texture.  You can also create shapes by using =rectangleC=,
  =filledRectangleC= and =lineC=.

  You can combine images with the =overC= function.  It takes two
  arguments and puts the first one above the second one when
  rendering.  When you have a list of images that you want to combine
  you can use for example =foldl1 overC= to combine all of them.

  Color modulation can be archived via the following commands:

  | =modulateAlphaM= | for alpha channel |
  | =modulateRedM=   | for red channel   |
  | =modulateGreenM= | for green channel |
  | =modulateBlueM=  | for blue channel  |

  For further documentation and the API see hackage.

* License
  Copyright (C) 2015  Sebastian Jordan

  This program is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see
  <http://www.gnu.org/licenses/>.