annotate docs/man3/SDL_SetVideoMode.3 @ 4223:63fd67e17705 SDL-1.2

Fixed bug #727 Lorenzo Desole 2009-04-19 07:36:10 PDT I am one of the developers of a multimedia application (My Media System MMS), which uses SDL. MMS is normally running in fullscreen mode but it switches it off before launching external applications (mplayer, xine, etc.). The problem with fullscreen is that when the latter is switched off either via SDL_WM_ToggleFullScreen() or SDL_SetVideoMode(), SDL compares the current screen sizes with the ones saved when the video system was initted, and if they don't match, it calls XF86VidModeSwitchToMode() to switch to the old modeline. This makes it impossible for external programs and for MMS itself to use RandR to change the screen size, because next time fullscreen mode is turned off, it bombs out with the following error: X Error of failed request: BadValue (integer parameter out of range for operation) Major opcode of failed request: 136 (XFree86-VidModeExtension) Minor opcode of failed request: 10 (XF86VidModeSwitchToMode) [...] Obviously this happens only if the new screen resolution is smaller than the original one and XF86VidModeSwitchToMode() can't succeed. I couldn't find any way to inform SDL that the screen resolution it uses as reference is no longer valid. This can be fixed by adding "save_mode(this)" to ./src/video/x11/SDL_x11modes.c, API X11_EnterFullScreen(_THIS), like this: int X11_EnterFullScreen(_THIS) { int okay; + save_mode(this); I can't rule out possible side effects, but I don't see any. While I admit this is a minor issue for the general users, it is a major showstopper for our program where the ability to change screen resolution and refresh rate according to the movie being played, is very important. Thanks in advance.
author Sam Lantinga <slouken@libsdl.org>
date Mon, 21 Sep 2009 11:14:36 +0000
parents 4e3b250c950e
children 1238da4a7112
rev   line source
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
1 .TH "SDL_SetVideoMode" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference"
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
2 .SH "NAME"
4107
4e3b250c950e Erik Heckers fixed bug #493
Sam Lantinga <slouken@libsdl.org>
parents: 181
diff changeset
3 SDL_SetVideoMode \- Set up a video mode with the specified width, height and bits-per-pixel\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
4 .SH "SYNOPSIS"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
5 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
6 \fB#include "SDL\&.h"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
7 .sp
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
8 \fBSDL_Surface *\fBSDL_SetVideoMode\fP\fR(\fBint width, int height, int bpp, Uint32 flags\fR);
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
9 .SH "DESCRIPTION"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
10 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
11 Set up a video mode with the specified width, height and bits-per-pixel\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
12 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
13 If \fBbpp\fR is 0, it is treated as the current display bits per pixel\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
14 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
15 The \fBflags\fR parameter is the same as the \fBflags\fR field of the \fI\fBSDL_Surface\fR\fR structure\&. OR\&'d combinations of the following values are valid\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
16 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
17 \fBSDL_SWSURFACE\fP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
18 Create the video surface in system memory
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
19 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
20 \fBSDL_HWSURFACE\fP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
21 Create the video surface in video memory
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
22 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
23 \fBSDL_ASYNCBLIT\fP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
24 Enables the use of asynchronous updates of the display surface\&. This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
25 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
26 \fBSDL_ANYFORMAT\fP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
27 Normally, if a video surface of the requested bits-per-pixel (\fBbpp\fR) is not available, SDL will emulate one with a shadow surface\&. Passing \fBSDL_ANYFORMAT\fP prevents this and causes SDL to use the video surface, regardless of its pixel depth\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
28 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
29 \fBSDL_HWPALETTE\fP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
30 Give SDL exclusive palette access\&. Without this flag you may not always get the the colors you request with \fI\fBSDL_SetColors\fP\fR or \fI\fBSDL_SetPalette\fP\fR\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
31 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
32 \fBSDL_DOUBLEBUF\fP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
33 Enable hardware double buffering; only valid with SDL_HWSURFACE\&. Calling \fI\fBSDL_Flip\fP\fR will flip the buffers and update the screen\&. All drawing will take place on the surface that is not displayed at the moment\&. If double buffering could not be enabled then \fBSDL_Flip\fP will just perform a \fI\fBSDL_UpdateRect\fP\fR on the entire screen\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
34 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
35 \fBSDL_FULLSCREEN\fP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
36 SDL will attempt to use a fullscreen mode\&. If a hardware resolution change is not possible (for whatever reason), the next higher resolution will be used and the display window centered on a black background\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
37 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
38 \fBSDL_OPENGL\fP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
39 Create an OpenGL rendering context\&. You should have previously set OpenGL video attributes with \fI\fBSDL_GL_SetAttribute\fP\fR\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
40 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
41 \fBSDL_OPENGLBLIT\fP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
42 Create an OpenGL rendering context, like above, but allow normal blitting operations\&. The screen (2D) surface may have an alpha channel, and \fI\fBSDL_UpdateRects\fP\fR must be used for updating changes to the screen surface\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
43 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
44 \fBSDL_RESIZABLE\fP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
45 Create a resizable window\&. When the window is resized by the user a \fI\fBSDL_VIDEORESIZE\fP\fR event is generated and \fBSDL_SetVideoMode\fP can be called again with the new size\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
46 .TP 20
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
47 \fBSDL_NOFRAME\fP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
48 If possible, \fBSDL_NOFRAME\fP causes SDL to create a window with no title bar or frame decoration\&. Fullscreen modes automatically have this flag set\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
49 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
50 .RS
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
51 \fBNote:
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
52 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
53 Whatever \fBflags\fR \fBSDL_SetVideoMode\fP could satisfy are set in the \fBflags\fR member of the returned surface\&.
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
54 .RE
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
55 .PP
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
56 .RS
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
57 \fBNote:
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
58 .PP
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
59 The \fBbpp\fR parameter is the number of bits per pixel, so a \fBbpp\fR of 24 uses the packed representation of 3 bytes/pixel\&. For the more common 4 bytes/pixel mode, use a \fBbpp\fR of 32\&. Somewhat oddly, both 15 and 16 will request a 2 bytes/pixel mode, but different pixel formats\&.
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
60 .RE
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
61 .SH "RETURN VALUE"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
62 .PP
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
63 The framebuffer surface, or \fBNULL\fR if it fails\&. The surface returned is freed by SDL_Quit() and should nt be freed by the caller\&.
0
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
64 .SH "SEE ALSO"
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
65 .PP
74212992fb08 Initial revision
Sam Lantinga <slouken@lokigames.com>
parents:
diff changeset
66 \fI\fBSDL_LockSurface\fP\fR, \fI\fBSDL_SetColors\fP\fR, \fI\fBSDL_Flip\fP\fR, \fI\fBSDL_Surface\fR\fR
181
e5bc29de3f0a Updated from the SDL Documentation Project
Sam Lantinga <slouken@libsdl.org>
parents: 55
diff changeset
67 ...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01