|
Size: 6869
Comment: update content - w/ Sam (in progress)
|
Size: 5068
Comment: update content - w/ Sam (in progress)
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 13: | Line 13: |
| SDL_Rect* srcrect, | const SDL_Rect* srcrect, |
| Line 27: | Line 27: |
| See [[#video|Remarks]] for details if the return value is -2. | |
| Line 35: | Line 34: |
| <<Color2(green,Changed colour to color.)>> This is the public blit function, and it performs rectangle validation and clipping before passing it to [[SDL_LowerBlit]](). <<Color2(green,Does this remark apply only to Upper``Blit and not to Blit``Surface?)>> |
|
| Line 41: | Line 36: |
| <<Color2(green,The above 2 remarks were re-ordered and have been moved to the top of the section because they seem more appropriately placed there. They were at the bottom in the reverse order.)>> | This is the public blit function, and it performs rectangle validation and clipping before passing it to [[SDL_LowerBlit]](). |
| Line 43: | Line 38: |
| The blit function should not be called on a locked surface. <<Color2(green,This was listed below the following but seemed more appropriately placed here.)>> *<<BR>>(i.e. when you use your own drawing functions you may need to lock a surface, but this is not the case with [[SDL_BlitSurface]]().)<<BR>> Like most surface manipulation functions in SDL, it should not be used together with OpenGL.<<BR>>* |
The blit function should not be called on a locked surface. |
| Line 46: | Line 40: |
| This assumes that the source and destination rectangles are the same size. If either '''srcrect''' or '''dstrect''' are NULL, the entire surface ('''src''' or '''dst''') is copied. The final blit rectangles are saved in '''srcrect''' and '''dstrect''' after all clipping is performed. *<<BR>><<Color2(green,Is this redundant to above? Should some of it be kept because it says more? Is this wording preferable?)>> 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. |
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. |
| Line 52: | Line 44: |
| The final blit rectangle is saved in '''dstrect''' after all clipping is performed ('''srcrect''' is not modified). <<BR>>* | The final blit rectangle is saved in '''dstrect''' after all clipping is performed ('''srcrect''' is not modified). |
| Line 54: | Line 46: |
| <<Color2(green,Should the following go in a code box or is this formatting acceptable? Should \verbatim and \endverbatim be removed?)>> | |
| Line 56: | Line 47: |
| <<Color2(green,This section needs to be modified to reflect the concepts in the new version. alpha and colorkey have been replaced in 1.3.)>> | |
| Line 57: | Line 49: |
| \verbatim | |
| Line 91: | Line 83: |
| \endverbatim <<Anchor(video)>> If either of the surfaces were in video memory, and the blit returns -2, the video memory was lost, so it should be reloaded with artwork and re-blitted: {{{ @code while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { while ( SDL_LockSurface(image) < 0 ) Sleep(10); -- Write image pixels to image->pixels -- SDL_UnlockSurface(image); } @endcode }}} <<Color2(green,Should @code and @endcode be removed here?)>> This happens under DirectX 5.0 when the system switches away from your fullscreen application. The lock will also fail until you have access to the video memory again. |
DRAFT |
SDL_BlitSurface
Use this function to perform a fast blit from the source surface to the destination surface.
Contents
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).
green
The blit semantics for surfaces with and without alpha and colorkey are defined as follows:
RGBA->RGB:
- SDL_SRCALPHA set:
- alpha-blend (using alpha-channel). SDL_SRCCOLORKEY ignored.
- 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:
- SDL_SRCALPHA set:
- alpha-blend (using the source per-surface alpha value); set destination alpha to opaque.
- copy RGB, set destination alpha to source per-surface alpha value.
- 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.
- 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).
- copy RGB.
- if SDL_SRCCOLORKEY set, only copy the pixels matching the source color key.
- SDL_SRCALPHA set:
*
The results of blitting operations vary greatly depending on whether SDL_SRCALPHA is set or not. See SDL_SetAlpha (green
) 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.
*
