[cairo-commit] [cairo-www] src/SDL.mdwn

[M. Joonas Pihlaja]

 src/SDL.mdwn |   57 ++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 42 insertions(+), 15 deletions(-)

New commits:
commit 9a5f3ae6256744aa9f434089c8fc6ec90b887e64
Author: M Joonas Pihlaja <jpihlaja at cc.helsinki.fi>
Date:   Sun Feb 15 16:57:54 2009 +0200

    Update SDL.mdwn to not refer to the cairo sdl surface.

diff --git a/src/SDL.mdwn b/src/SDL.mdwn
index 661f0ad..7924d5c 100644
--- a/src/SDL.mdwn
+++ b/src/SDL.mdwn
@@ -3,18 +3,45 @@ portable multimedia applications very easily. Install the latest SDL
 development packages for your distribution, or download the latest SDL
 development kit from [http://www.libsdl.org](http://www.libsdl.org/).
 
-For Visual Studio unzip it and add the SDL\include directory, SDL.lib
-and SDLMain.lib to your project, just like you did with cairo.
-
-Drawing with cairo to an SDL Surface is quite simple, as all you need to
-do is create a `cairo_surface_t` from the SDL_Surface using
-`cairo_sdl_surface_create()`. (This surface is a full cairo surface and so
-may be used as a source for other (non-SDL) contexts, etc.)
-For demonstration purposes, see the SDL/cairo version of the cairo clock
-[[source_code|sdl-clock.c]]. A [[makefile|Makefile]] for this
-code is also available.
-
-Visual Studio tip:
-If you regularly use cairo / SDL, it might be easier to add the cairo
-include and lib directories to your default configuration. Use Tools
--> Options -> Projects and Solutions -> VC++ directories for that.
+Drawing with cairo to an SDL Surface is quite simple, as all you need
+to do is create a `cairo_surface_t` from the SDL_Surface using
+`cairo_image_surface_create_for_data()`.  This works as expected as
+long as SDL and cairo agree on the pixel format.  For example:
+
+	SDL_Surface *sdlsurf = SDL_CreateRGBSurface (
+		flags, width, height, 32,
+		0x00FF0000, /* Rmask */
+		0x0000FF00, /* Gmask */
+		0x000000FF, /* Bmask */
+		0); /* Amask */
+
+	/* ... make sure sdlsurf is locked or doesn't need locking ... */
+
+	cairo_surface_t *cairosurf = cairo_image_surface_create_for_data (
+		sdlsurf->pixels,
+		CAIRO_FORMAT_RGB24,
+		sdlsurf->w,
+		sdlsurf->h,
+		sdlsurf->pitch);
+
+	/* ... normal cairo calls ... */
+
+
+All the usual SDL locking rules apply, so the `pixels` member of your
+`SDL_Surface` needs to be valid and stay put for the lifetime of the
+cairo surface.
+
+SDL's 32 bit pixel formats with per pixel alpha are not supported
+directly by cairo because cairo and SDL disagree on the interpretation
+of pixel values with alpha: SDL uses unpremultiplied pixels but cairo
+uses premultiplied pixels.  However, using
+[cairosdl](http://cgit.freedesktop.org/~joonas/cairosdl/) drawing to
+such `SDL_Surface`s is almost as straightforward as to any other cairo
+surface; chiefly the difference is that one needs to flush the surface
+before the results appear in the `SDL_Surface`.  You can also use cairo
+to composite a cairo surface with transparency to an `SDL_Surface`
+without, and thus sidestep the problem entirely.
+
+Examples of using SDL with cairo are available in the
+[demos](http://cgit.freedesktop.org/~joonas/cairosdl/tree/?h=demos)
+branch of cairosdl.