Mercurial > sdl-ios-xcode

view docs/man3/SDL_SetAlpha.3 @ 1212:7663bb0f52c7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
To: sdl@libsdl.org From: Christian Walther <cwalther@gmx.ch> Date: Thu, 15 Dec 2005 21:19:53 +0100 Subject: [SDL] More mouse enhancements for Mac OS X The attached patch brings two more enhancements to mouse handling on Mac OS X (Quartz): 1. Currently, after launching an SDL application, SDL's notion of the mouse position is stuck in the top left corner (0,0) until the first time the mouse is moved. That's because the UpdateMouse() function isn't implemented in the Quartz driver. This patch adds it. 2. When grabbing input while the mouse cursor is hidden, the function CGAssociateMouseAndMouseCursorPosition(0) is called, which prevents the system's notion of the mouse location from moving (and therefore leaving the SDL window) even when the mouse is moved. However, apparently the Wacom tablet driver (and maybe other special pointing device drivers) doesn't care about that setting and still allows the mouse location to go outside of the window. Interestingly, the system cursor, which is made visible by the existing code in SDL in that case, does not follow the mouse location, but appears in the middle of the SDL window. The mouse location being outside of the window however means that mouse button events go to background applications (or the dock or whatever is there), which is very confusing to the user who sees no cursor outside of the SDL window. I have not found any way of intercepting these events (and that's probably by design, as "normal" applications shouldn't prevent the user from bringing other applications' windows to the front by clicking on them). An idea would be placing a fully transparent, screen-filling window in front of everything, but I fear that this might affect rendering performance (by doing unnecessary compositing, using up memory, or whatever). The deluxe solution to the problem would be talking to the tablet driver using AppleEvents to tell it to constrain its mapped area to the window (see Wacom's "TabletEventDemo" sample app, http://www.wacomeng.com/devsupport/mac/downloads.html), but I think that the bloat that solution would add to SDL would outweigh its usefulness. What I did instead in my patch is reassociating mouse and cursor when the mouse leaves the window while an invisible grab is in effect, and restoring the grab when the window is entered. That way, the grab can still be effectively broken by a tablet, but at least it's obvious to the user that it is broken. That change is minimal - it doesn't affect operation with a mouse (or a trackpad), and the code that it adds is not executed on every PumpEvents() call, only when entering and leaving the window. Unless there are any concerns about the patch, please apply. Feel free to shorten the lengthy comment in SDL_QuartzEvents.m if you think it's too verbose. Thanks -Christian
author Ryan C. Gordon <icculus@icculus.org>
date Mon, 02 Jan 2006 00:31:00 +0000
parents e5bc29de3f0a
children 546f7c1eb755
line wrap: on
line source

.TH "SDL_SetAlpha" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference" 
.SH "NAME"
SDL_SetAlpha\- Adjust the alpha properties of a surface
.SH "SYNOPSIS"
.PP
\fB#include "SDL\&.h"
.sp
\fBint \fBSDL_SetAlpha\fP\fR(\fBSDL_Surface *surface, Uint32 flag, Uint8 alpha\fR);
.SH "DESCRIPTION"
.PP
.RS
\fBNote:  
.PP
This function and the semantics of SDL alpha blending have changed since version 1\&.1\&.4\&. Up until version 1\&.1\&.5, an alpha value of 0 was considered opaque and a value of 255 was considered transparent\&. This has now been inverted: 0 (\fBSDL_ALPHA_TRANSPARENT\fP) is now considered transparent and 255 (\fBSDL_ALPHA_OPAQUE\fP) is now considered opaque\&.
.RE
.PP
\fBSDL_SetAlpha\fP is used for setting the per-surface alpha value and/or enabling and disabling alpha blending\&.
.PP
The\fBsurface\fR parameter specifies which surface whose alpha attributes you wish to adjust\&. \fBflags\fR is used to specify whether alpha blending should be used (\fBSDL_SRCALPHA\fP) and whether the surface should use RLE acceleration for blitting (\fBSDL_RLEACCEL\fP)\&. \fBflags\fR can be an OR\&'d combination of these two options, one of these options or 0\&. If \fBSDL_SRCALPHA\fP is not passed as a flag then all alpha information is ignored when blitting the surface\&. The \fBalpha\fR parameter is the per-surface alpha value; a surface need not have an alpha channel to use per-surface alpha and blitting can still be accelerated with \fBSDL_RLEACCEL\fP\&.
.PP
.RS
\fBNote:  
.PP
The per-surface alpha value of 128 is considered a special case and is optimised, so it\&'s much faster than other per-surface values\&.
.RE
.PP
Alpha effects surface blitting in the following ways:
.TP 20
RGBA->RGB with \fBSDL_SRCALPHA\fP
The source is alpha-blended with the destination, using the alpha channel\&. \fBSDL_SRCCOLORKEY\fP and the per-surface alpha are ignored\&.
.TP 20
RGBA->RGB without \fBSDL_SRCALPHA\fP
The RGB data is copied from the source\&. The source alpha channel and the per-surface alpha value are ignored\&.
.TP 20
RGB->RGBA with \fBSDL_SRCALPHA\fP
The source is alpha-blended with the destination using the per-surface alpha value\&. If \fBSDL_SRCCOLORKEY\fP is set, only the pixels not matching the colorkey value are copied\&. The alpha channel of the copied pixels is set to opaque\&.
.TP 20
RGB->RGBA without \fBSDL_SRCALPHA\fP
The RGB data is copied from the source and the alpha value of the copied pixels is set to opaque\&. If \fBSDL_SRCCOLORKEY\fP is set, only the pixels not matching the colorkey value are copied\&. 
.TP 20
RGBA->RGBA with \fBSDL_SRCALPHA\fP
The source is alpha-blended with the destination using the source alpha channel\&. The alpha channel in the destination surface is left untouched\&. \fBSDL_SRCCOLORKEY\fP is ignored\&.
.TP 20
RGBA->RGBA without \fBSDL_SRCALPHA\fP
The RGBA data is copied to the destination surface\&. If \fBSDL_SRCCOLORKEY\fP is set, only the pixels not matching the colorkey value are copied\&.
.TP 20
RGB->RGB with \fBSDL_SRCALPHA\fP
The source is alpha-blended with the destination using the per-surface alpha value\&. If \fBSDL_SRCCOLORKEY\fP is set, only the pixels not matching the colorkey value are copied\&.
.TP 20
RGB->RGB without \fBSDL_SRCALPHA\fP
The RGB data is copied from the source\&. If \fBSDL_SRCCOLORKEY\fP is set, only the pixels not matching the colorkey value are copied\&.
.PP
.RS
\fBNote:  
.PP
 Note that RGBA->RGBA blits (with SDL_SRCALPHA set) keep the alpha of the destination surface\&. This means that you cannot compose two arbitrary RGBA surfaces this way and get the result you would expect from "overlaying" them; the destination alpha will work as a mask\&.
.PP
Also note that per-pixel and per-surface alpha cannot be combined; the per-pixel alpha is always used if available
.RE
.SH "RETURN VALUE"
.PP
This function returns \fB0\fR, or \fB-1\fR if there was an error\&.
.SH "SEE ALSO"
.PP
\fI\fBSDL_MapRGBA\fP\fR, \fI\fBSDL_GetRGBA\fP\fR, \fI\fBSDL_DisplayFormatAlpha\fP\fR, \fI\fBSDL_BlitSurface\fP\fR
...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01