docs/man3/SDL_SetVideoMode.3
author Sam Lantinga <slouken@libsdl.org>
Wed, 08 Mar 2006 18:30:12 +0000
changeset 1486 9d77fc9d0ace
parent 181 e5bc29de3f0a
child 2283 546f7c1eb755
permissions -rw-r--r--
Re-added C runtime support for Visual C++ 5,6
slouken@181
     1
.TH "SDL_SetVideoMode" "3" "Tue 11 Sep 2001, 23:01" "SDL" "SDL API Reference" 
slouken@0
     2
.SH "NAME"
slouken@0
     3
SDL_SetVideoMode\- Set up a video mode with the specified width, height and bits-per-pixel\&.
slouken@0
     4
.SH "SYNOPSIS"
slouken@0
     5
.PP
slouken@0
     6
\fB#include "SDL\&.h"
slouken@0
     7
.sp
slouken@0
     8
\fBSDL_Surface *\fBSDL_SetVideoMode\fP\fR(\fBint width, int height, int bpp, Uint32 flags\fR);
slouken@0
     9
.SH "DESCRIPTION"
slouken@0
    10
.PP
slouken@0
    11
Set up a video mode with the specified width, height and bits-per-pixel\&.
slouken@0
    12
.PP
slouken@0
    13
If \fBbpp\fR is 0, it is treated as the current display bits per pixel\&.
slouken@0
    14
.PP
slouken@0
    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\&.
slouken@0
    16
.TP 20
slouken@0
    17
\fBSDL_SWSURFACE\fP
slouken@0
    18
Create the video surface in system memory
slouken@0
    19
.TP 20
slouken@0
    20
\fBSDL_HWSURFACE\fP
slouken@0
    21
Create the video surface in video memory
slouken@0
    22
.TP 20
slouken@0
    23
\fBSDL_ASYNCBLIT\fP
slouken@181
    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\&.
slouken@0
    25
.TP 20
slouken@0
    26
\fBSDL_ANYFORMAT\fP
slouken@181
    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\&.
slouken@0
    28
.TP 20
slouken@0
    29
\fBSDL_HWPALETTE\fP
slouken@181
    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\&.
slouken@0
    31
.TP 20
slouken@0
    32
\fBSDL_DOUBLEBUF\fP
slouken@181
    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\&.
slouken@0
    34
.TP 20
slouken@0
    35
\fBSDL_FULLSCREEN\fP
slouken@181
    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\&.
slouken@0
    37
.TP 20
slouken@0
    38
\fBSDL_OPENGL\fP
slouken@0
    39
Create an OpenGL rendering context\&. You should have previously set OpenGL video attributes with \fI\fBSDL_GL_SetAttribute\fP\fR\&.
slouken@0
    40
.TP 20
slouken@0
    41
\fBSDL_OPENGLBLIT\fP
slouken@181
    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\&.
slouken@0
    43
.TP 20
slouken@0
    44
\fBSDL_RESIZABLE\fP
slouken@0
    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\&.
slouken@0
    46
.TP 20
slouken@0
    47
\fBSDL_NOFRAME\fP
slouken@0
    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\&.
slouken@0
    49
.PP
slouken@0
    50
.RS
slouken@0
    51
\fBNote:  
slouken@0
    52
.PP
slouken@0
    53
Whatever \fBflags\fR \fBSDL_SetVideoMode\fP could satisfy are set in the \fBflags\fR member of the returned surface\&.
slouken@0
    54
.RE
slouken@181
    55
.PP
slouken@181
    56
.RS
slouken@181
    57
\fBNote:  
slouken@181
    58
.PP
slouken@181
    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\&.
slouken@181
    60
.RE
slouken@0
    61
.SH "RETURN VALUE"
slouken@0
    62
.PP
slouken@181
    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\&.
slouken@0
    64
.SH "SEE ALSO"
slouken@0
    65
.PP
slouken@0
    66
\fI\fBSDL_LockSurface\fP\fR, \fI\fBSDL_SetColors\fP\fR, \fI\fBSDL_Flip\fP\fR, \fI\fBSDL_Surface\fR\fR
slouken@181
    67
...\" created by instant / docbook-to-man, Tue 11 Sep 2001, 23:01