Wiki Page Content

Differences between revisions 15 and 16
⇤ ← Revision 15 as of 2012-01-24 19:42:42 →
Size: 5093
Editor: MichaelBonfils
Comment: Replace 1.3 with 2.0
← Revision 16 as of 2013-08-08 20:54:11 → ⇥
Size: 3683
Editor: Sam Lantinga
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
||<tablewidth="100%" style="color: #FF0000;" :> DRAFT||
Line 46: Line 45:
The blit semantics for surfaces with and without blending and colorkey are defined as follows:
    RGBA->RGB:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source alpha-channel and per-surface alpha)
        SDL_SRCCOLORKEY ignored.
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy RGB.
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        RGB values of the source color key, ignoring alpha in the
        comparison.
Line 47: Line 56:
<<Color2(green,This section needs to be modified to reflect the concepts in the new version. alpha and colorkey have been replaced in 2.0.)>>
The blit semantics for surfaces with and without alpha and colorkey are defined as follows:		     RGB->RGBA:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source per-surface alpha)
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy RGB, set destination alpha to source per-surface alpha value.
      both:
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        source color key.
Line 50: Line 65:
 RGBA->RGB:
  SDL_SRCALPHA set:
   alpha-blend (using alpha-channel).
 SDL_SRCCOLORKEY ignored.
  SDL_SRCALPHA not set:
   copy RGB.
   if SDL_SRCCOLORKEY set, only copy the pixels matching the RGB values of the source color key, ignoring alpha in the comparison.		     RGBA->RGBA:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
      alpha-blend (using the source alpha-channel and per-surface alpha)
      SDL_SRCCOLORKEY ignored.
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy all of RGBA to the destination.
      if SDL_SRCCOLORKEY set, only copy the pixels matching the
        RGB values of the source color key, ignoring alpha in the
        comparison.
Line 58: Line 75:
 RGB->RGBA:
  SDL_SRCALPHA set:
   alpha-blend (using the source per-surface alpha value);
   set destination alpha to opaque.
  SDL_SRCALPHA not set:
   copy RGB, set destination alpha to source per-surface alpha value.
  both:
   if SDL_SRCCOLORKEY set, only copy the pixels matching the source color key.

 RGBA->RGBA:
  SDL_SRCALPHA set:
   alpha-blend (using the source alpha channel) the RGB values;
   leave destination alpha untouched. [Note: is this correct?]
   SDL_SRCCOLORKEY ignored.
  SDL_SRCALPHA not set:
   copy all of RGBA to the destination.
   if SDL_SRCCOLORKEY set, only copy the pixels matching the RGB values of the source color key, ignoring alpha in the comparison.

 RGB->RGB:
  SDL_SRCALPHA set:
   alpha-blend (using the source per-surface alpha value).
  SDL_SRCALPHA not set:
   copy RGB.
  both:
   if SDL_SRCCOLORKEY set, only copy the pixels matching the source color key.

*<<BR>>The results of blitting operations vary greatly depending on whether SDL_SRCALPHA is set or not. See SDL_!SetAlpha (<<Color2(green,This does not have a page. Does it still exist?)>>) for an explanation of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting, as the following pseudo-code should hopefully explain.
{{{
if (source surface has SDL_SRCALPHA set) {
    if (source surface has alpha channel (that is, format->Amask != 0))
        blit using per-pixel alpha, ignoring any color key
    else {
        if (source surface has SDL_SRCCOLORKEY set)
            blit using the color key AND the per-surface alpha value
        else
            blit using the per-surface alpha value
    }
} else {
    if (source surface has SDL_SRCCOLORKEY set)
        blit using the color key
    else
        ordinary opaque rectangular blit
}
}}}

Note: the SDL blitter does not (yet) have the capability of scaling the blitted surfaces up or down like it is the case with other more sophisticated blitting mechanisms. You have to figure something out for yourself if you want to scale images (e.g. use SDL_gfx).

Note: when you're blitting between two alpha surfaces, normally the alpha of the destination acts as a mask. If you want to just do a "dumb copy" that doesn't blend, you have to turn off the SDL_SRCALPHA flag on the source surface. This is how it's supposed to work, but can be surprising when you're trying to combine one image with another and both have transparent backgrounds. <<BR>>*		     RGB->RGB:
      Source surface blend mode set to SDL_BLENDMODE_BLEND:
        alpha-blend (using the source per-surface alpha)
      Source surface blend mode set to SDL_BLENDMODE_NONE:
        copy RGB.
      both:
        if SDL_SRCCOLORKEY set, only copy the pixels matching the
        source color key.

SDL_BlitSurface

Use this function to perform a fast blit from the source surface to the destination surface.

Contents

  1. SDL_BlitSurface
    1. Syntax
    2. Function Parameters
    3. Return Value
    4. Code Examples
    5. Remarks
    6. Related Functions

Syntax

int SDL_BlitSurface(SDL_Surface*    src,
                    const SDL_Rect* srcrect,
                    SDL_Surface*    dst,
                    SDL_Rect*       dstrect)

Function Parameters

src

the SDL_Surface structure to be copied from

srcrect

the SDL_Rect structure representing the rectangle to be copied, or NULL to copy the entire surface

dst

the SDL_Surface structure that is the blit target

dstrect

the SDL_Rect structure representing the rectangle that is copied into

Return Value

Returns 0 if the blit is successful or a negative error code on failure; call SDL_GetError() for more information.

Code Examples

You can add your code example here

Remarks

You should call SDL_BlitSurface() unless you know exactly how SDL blitting works internally and how to use the other blit functions.

This is the public blit function, and it performs rectangle validation and clipping before passing it to SDL_LowerBlit().

The blit function should not be called on a locked surface.

The width and height in srcrect determine the size of the copied rectangle. Only the position is used in the dstrect (the width and height are ignored). Blits with negative dstrect coordinates will be clipped properly.

If srcrect is NULL, the entire surface is copied. If dstrect is NULL, then the destination position (upper left corner) is (0, 0).

The final blit rectangle is saved in dstrect after all clipping is performed (srcrect is not modified).

The blit semantics for surfaces with and without blending and colorkey are defined as follows:

  • RGBA->RGB:

    • Source surface blend mode set to SDL_BLENDMODE_BLEND:
      • alpha-blend (using the source alpha-channel and per-surface alpha) SDL_SRCCOLORKEY ignored.
      Source surface blend mode set to SDL_BLENDMODE_NONE:
      • copy RGB. if SDL_SRCCOLORKEY set, only copy the pixels matching the RGB values of the source color key, ignoring alpha in the comparison.

    RGB->RGBA:

    • Source surface blend mode set to SDL_BLENDMODE_BLEND:
      • alpha-blend (using the source per-surface alpha)
      Source surface blend mode set to SDL_BLENDMODE_NONE:
      • copy RGB, set destination alpha to source per-surface alpha value.
      both:
      • if SDL_SRCCOLORKEY set, only copy the pixels matching the source color key.

    RGBA->RGBA:

    • Source surface blend mode set to SDL_BLENDMODE_BLEND:
      • alpha-blend (using the source alpha-channel and per-surface alpha) SDL_SRCCOLORKEY ignored.
      Source surface blend mode set to SDL_BLENDMODE_NONE:
      • copy all of RGBA to the destination. if SDL_SRCCOLORKEY set, only copy the pixels matching the RGB values of the source color key, ignoring alpha in the comparison.

    RGB->RGB:

    • Source surface blend mode set to SDL_BLENDMODE_BLEND:
      • alpha-blend (using the source per-surface alpha)
      Source surface blend mode set to SDL_BLENDMODE_NONE:
      • copy RGB.
      both:
      • if SDL_SRCCOLORKEY set, only copy the pixels matching the source color key.

CategoryAPI, CategorySurface

None: SDL_BlitSurface (last edited 2014-03-30 21:07:59 by PhilippWiesemann)

(Page Info.)
Feedback
Please include your contact information if you'd like to receive a reply.
Submit