← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libsdl1.2/trusty

« back to all changes in this revision

Viewing changes to include/SDL_video.h

  • Committer: Bazaar Package Importer
  • Author(s): Daniel T Chen
  • Date: 2009-12-08 01:50:15 UTC
  • mfrom: (2.1.6 experimental)
  • Revision ID: james.westby@ubuntu.com-20091208015015-mr68dcbbctrhi5at
Tags: 1.2.14-1ubuntu1
https://launchpad.net/bugs/328932
https://launchpad.net/bugs/320915
* Merge from Debian experimental, remaining changes:
  + debian/control:
    + add libglu1-mesa-dev as a build dependency, so SDL gets built
      with OpenGL support (LP: #328932)
    - dropped build-depends on libarts1-dev, libartsc0-dev. These
      packages will disappear as part of the arts removal
      (LP: #320915)
    - Removed Package: libsdl1.2debian-arts section entirely
    - dropped depends on libsdl1.2debian-arts (= ${binary:Version})
      for libsdl1.2-debian
    - dropped recommends on libartsc0-dev for libsdl1.2-dev
    - Remove svgalib support.
  + debian/rules:
    + set --enable-arts-shared=no and --enable-arts=no in confflags
    - removed --disable-audio-arts from udeb_confflags
    - dropped arts from FLAVOURS=
    + Link using -Wl,-Bsymbolic-functions.

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/SDL_video.h
1
1
/*
2
2
    SDL - Simple DirectMedia Layer
3
 
    Copyright (C) 1997-2006 Sam Lantinga
 
3
    Copyright (C) 1997-2009 Sam Lantinga
4
4
 
5
5
    This library is free software; you can redistribute it and/or
6
6
    modify it under the terms of the GNU Lesser General Public
20
20
    slouken@libsdl.org
21
21
*/
22
22
 
23
 
/* Header file for access to the SDL raw framebuffer window */
 
23
/** @file SDL_video.h
 
24
 *  Header file for access to the SDL raw framebuffer window
 
25
 */
24
26
 
25
27
#ifndef _SDL_video_h
26
28
#define _SDL_video_h
35
37
extern "C" {
36
38
#endif
37
39
 
38
 
/* Transparency definitions: These define alpha as the opacity of a surface */
 
40
/** @name Transparency definitions
 
41
 *  These define alpha as the opacity of a surface
 
42
 */
 
43
/*@{*/
39
44
#define SDL_ALPHA_OPAQUE 255
40
45
#define SDL_ALPHA_TRANSPARENT 0
 
46
/*@}*/
41
47
 
42
 
/* Useful data types */
 
48
/** @name Useful data types */
 
49
/*@{*/
43
50
typedef struct SDL_Rect {
44
51
        Sint16 x, y;
45
52
        Uint16 w, h;
57
64
        int       ncolors;
58
65
        SDL_Color *colors;
59
66
} SDL_Palette;
 
67
/*@}*/
60
68
 
61
 
/* Everything in the pixel format structure is read-only */
 
69
/** Everything in the pixel format structure is read-only */
62
70
typedef struct SDL_PixelFormat {
63
71
        SDL_Palette *palette;
64
72
        Uint8  BitsPerPixel;
76
84
        Uint32 Bmask;
77
85
        Uint32 Amask;
78
86
 
79
 
        /* RGB color key information */
 
87
        /** RGB color key information */
80
88
        Uint32 colorkey;
81
 
        /* Alpha value information (per-surface alpha) */
 
89
        /** Alpha value information (per-surface alpha) */
82
90
        Uint8  alpha;
83
91
} SDL_PixelFormat;
84
92
 
85
 
/* This structure should be treated as read-only, except for 'pixels',
86
 
   which, if not NULL, contains the raw pixel data for the surface.
87
 
*/
 
93
/** This structure should be treated as read-only, except for 'pixels',
 
94
 *  which, if not NULL, contains the raw pixel data for the surface.
 
95
 */
88
96
typedef struct SDL_Surface {
89
 
        Uint32 flags;                           /* Read-only */
90
 
        SDL_PixelFormat *format;                /* Read-only */
91
 
        int w, h;                               /* Read-only */
92
 
        Uint16 pitch;                           /* Read-only */
93
 
        void *pixels;                           /* Read-write */
94
 
        int offset;                             /* Private */
 
97
        Uint32 flags;                           /**< Read-only */
 
98
        SDL_PixelFormat *format;                /**< Read-only */
 
99
        int w, h;                               /**< Read-only */
 
100
        Uint16 pitch;                           /**< Read-only */
 
101
        void *pixels;                           /**< Read-write */
 
102
        int offset;                             /**< Private */
95
103
 
96
 
        /* Hardware-specific surface info */
 
104
        /** Hardware-specific surface info */
97
105
        struct private_hwdata *hwdata;
98
106
 
99
 
        /* clipping information */
100
 
        SDL_Rect clip_rect;                     /* Read-only */
101
 
        Uint32 unused1;                         /* for binary compatibility */
102
 
 
103
 
        /* Allow recursive locks */
104
 
        Uint32 locked;                          /* Private */
105
 
 
106
 
        /* info for fast blit mapping to other surfaces */
107
 
        struct SDL_BlitMap *map;                /* Private */
108
 
 
109
 
        /* format version, bumped at every change to invalidate blit maps */
110
 
        unsigned int format_version;            /* Private */
111
 
 
112
 
        /* Reference count -- used when freeing surface */
113
 
        int refcount;                           /* Read-mostly */
 
107
        /** clipping information */
 
108
        SDL_Rect clip_rect;                     /**< Read-only */
 
109
        Uint32 unused1;                         /**< for binary compatibility */
 
110
 
 
111
        /** Allow recursive locks */
 
112
        Uint32 locked;                          /**< Private */
 
113
 
 
114
        /** info for fast blit mapping to other surfaces */
 
115
        struct SDL_BlitMap *map;                /**< Private */
 
116
 
 
117
        /** format version, bumped at every change to invalidate blit maps */
 
118
        unsigned int format_version;            /**< Private */
 
119
 
 
120
        /** Reference count -- used when freeing surface */
 
121
        int refcount;                           /**< Read-mostly */
114
122
} SDL_Surface;
115
123
 
116
 
/* These are the currently supported flags for the SDL_surface */
117
 
/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
118
 
#define SDL_SWSURFACE   0x00000000      /* Surface is in system memory */
119
 
#define SDL_HWSURFACE   0x00000001      /* Surface is in video memory */
120
 
#define SDL_ASYNCBLIT   0x00000004      /* Use asynchronous blits if possible */
121
 
/* Available for SDL_SetVideoMode() */
122
 
#define SDL_ANYFORMAT   0x10000000      /* Allow any video depth/pixel-format */
123
 
#define SDL_HWPALETTE   0x20000000      /* Surface has exclusive palette */
124
 
#define SDL_DOUBLEBUF   0x40000000      /* Set up double-buffered video mode */
125
 
#define SDL_FULLSCREEN  0x80000000      /* Surface is a full screen display */
126
 
#define SDL_OPENGL      0x00000002      /* Create an OpenGL rendering context */
127
 
#define SDL_OPENGLBLIT  0x0000000A      /* Create an OpenGL rendering context and use it for blitting */
128
 
#define SDL_RESIZABLE   0x00000010      /* This video mode may be resized */
129
 
#define SDL_NOFRAME     0x00000020      /* No window caption or edge frame */
130
 
/* Used internally (read-only) */
131
 
#define SDL_HWACCEL     0x00000100      /* Blit uses hardware acceleration */
132
 
#define SDL_SRCCOLORKEY 0x00001000      /* Blit uses a source color key */
133
 
#define SDL_RLEACCELOK  0x00002000      /* Private flag */
134
 
#define SDL_RLEACCEL    0x00004000      /* Surface is RLE encoded */
135
 
#define SDL_SRCALPHA    0x00010000      /* Blit uses source alpha blending */
136
 
#define SDL_PREALLOC    0x01000000      /* Surface uses preallocated memory */
137
 
 
138
 
/* Evaluates to true if the surface needs to be locked before access */
 
124
/** @name SDL_Surface Flags
 
125
 *  These are the currently supported flags for the SDL_surface
 
126
 */
 
127
/*@{*/
 
128
 
 
129
/** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
 
130
/*@{*/
 
131
#define SDL_SWSURFACE   0x00000000      /**< Surface is in system memory */
 
132
#define SDL_HWSURFACE   0x00000001      /**< Surface is in video memory */
 
133
#define SDL_ASYNCBLIT   0x00000004      /**< Use asynchronous blits if possible */
 
134
/*@}*/
 
135
 
 
136
/** Available for SDL_SetVideoMode() */
 
137
/*@{*/
 
138
#define SDL_ANYFORMAT   0x10000000      /**< Allow any video depth/pixel-format */
 
139
#define SDL_HWPALETTE   0x20000000      /**< Surface has exclusive palette */
 
140
#define SDL_DOUBLEBUF   0x40000000      /**< Set up double-buffered video mode */
 
141
#define SDL_FULLSCREEN  0x80000000      /**< Surface is a full screen display */
 
142
#define SDL_OPENGL      0x00000002      /**< Create an OpenGL rendering context */
 
143
#define SDL_OPENGLBLIT  0x0000000A      /**< Create an OpenGL rendering context and use it for blitting */
 
144
#define SDL_RESIZABLE   0x00000010      /**< This video mode may be resized */
 
145
#define SDL_NOFRAME     0x00000020      /**< No window caption or edge frame */
 
146
/*@}*/
 
147
 
 
148
/** Used internally (read-only) */
 
149
/*@{*/
 
150
#define SDL_HWACCEL     0x00000100      /**< Blit uses hardware acceleration */
 
151
#define SDL_SRCCOLORKEY 0x00001000      /**< Blit uses a source color key */
 
152
#define SDL_RLEACCELOK  0x00002000      /**< Private flag */
 
153
#define SDL_RLEACCEL    0x00004000      /**< Surface is RLE encoded */
 
154
#define SDL_SRCALPHA    0x00010000      /**< Blit uses source alpha blending */
 
155
#define SDL_PREALLOC    0x01000000      /**< Surface uses preallocated memory */
 
156
/*@}*/
 
157
 
 
158
/*@}*/
 
159
 
 
160
/** Evaluates to true if the surface needs to be locked before access */
139
161
#define SDL_MUSTLOCK(surface)   \
140
162
  (surface->offset ||           \
141
163
  ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
142
164
 
143
 
/* typedef for private surface blitting functions */
 
165
/** typedef for private surface blitting functions */
144
166
typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
145
167
                        struct SDL_Surface *dst, SDL_Rect *dstrect);
146
168
 
147
169
 
148
 
/* Useful for determining the video hardware capabilities */
 
170
/** Useful for determining the video hardware capabilities */
149
171
typedef struct SDL_VideoInfo {
150
 
        Uint32 hw_available :1; /* Flag: Can you create hardware surfaces? */
151
 
        Uint32 wm_available :1; /* Flag: Can you talk to a window manager? */
 
172
        Uint32 hw_available :1; /**< Flag: Can you create hardware surfaces? */
 
173
        Uint32 wm_available :1; /**< Flag: Can you talk to a window manager? */
152
174
        Uint32 UnusedBits1  :6;
153
175
        Uint32 UnusedBits2  :1;
154
 
        Uint32 blit_hw      :1; /* Flag: Accelerated blits HW --> HW */
155
 
        Uint32 blit_hw_CC   :1; /* Flag: Accelerated blits with Colorkey */
156
 
        Uint32 blit_hw_A    :1; /* Flag: Accelerated blits with Alpha */
157
 
        Uint32 blit_sw      :1; /* Flag: Accelerated blits SW --> HW */
158
 
        Uint32 blit_sw_CC   :1; /* Flag: Accelerated blits with Colorkey */
159
 
        Uint32 blit_sw_A    :1; /* Flag: Accelerated blits with Alpha */
160
 
        Uint32 blit_fill    :1; /* Flag: Accelerated color fill */
 
176
        Uint32 blit_hw      :1; /**< Flag: Accelerated blits HW --> HW */
 
177
        Uint32 blit_hw_CC   :1; /**< Flag: Accelerated blits with Colorkey */
 
178
        Uint32 blit_hw_A    :1; /**< Flag: Accelerated blits with Alpha */
 
179
        Uint32 blit_sw      :1; /**< Flag: Accelerated blits SW --> HW */
 
180
        Uint32 blit_sw_CC   :1; /**< Flag: Accelerated blits with Colorkey */
 
181
        Uint32 blit_sw_A    :1; /**< Flag: Accelerated blits with Alpha */
 
182
        Uint32 blit_fill    :1; /**< Flag: Accelerated color fill */
161
183
        Uint32 UnusedBits3  :16;
162
 
        Uint32 video_mem;       /* The total amount of video memory (in K) */
163
 
        SDL_PixelFormat *vfmt;  /* Value: The format of the video surface */
164
 
        int    current_w;       /* Value: The current video mode width */
165
 
        int    current_h;       /* Value: The current video mode height */
 
184
        Uint32 video_mem;       /**< The total amount of video memory (in K) */
 
185
        SDL_PixelFormat *vfmt;  /**< Value: The format of the video surface */
 
186
        int    current_w;       /**< Value: The current video mode width */
 
187
        int    current_h;       /**< Value: The current video mode height */
166
188
} SDL_VideoInfo;
167
189
 
168
190
 
169
 
/* The most common video overlay formats.
170
 
   For an explanation of these pixel formats, see:
171
 
        http://www.webartz.com/fourcc/indexyuv.htm
172
 
 
173
 
   For information on the relationship between color spaces, see:
174
 
   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
 
191
/** @name Overlay Formats
 
192
 *  The most common video overlay formats.
 
193
 *  For an explanation of these pixel formats, see:
 
194
 *      http://www.webartz.com/fourcc/indexyuv.htm
 
195
 *
 
196
 *  For information on the relationship between color spaces, see:
 
197
 *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
175
198
 */
176
 
#define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
177
 
#define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
178
 
#define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
179
 
#define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
180
 
#define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
 
199
/*@{*/
 
200
#define SDL_YV12_OVERLAY  0x32315659    /**< Planar mode: Y + V + U  (3 planes) */
 
201
#define SDL_IYUV_OVERLAY  0x56555949    /**< Planar mode: Y + U + V  (3 planes) */
 
202
#define SDL_YUY2_OVERLAY  0x32595559    /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
 
203
#define SDL_UYVY_OVERLAY  0x59565955    /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
 
204
#define SDL_YVYU_OVERLAY  0x55595659    /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
 
205
/*@}*/
181
206
 
182
 
/* The YUV hardware video overlay */
 
207
/** The YUV hardware video overlay */
183
208
typedef struct SDL_Overlay {
184
 
        Uint32 format;                          /* Read-only */
185
 
        int w, h;                               /* Read-only */
186
 
        int planes;                             /* Read-only */
187
 
        Uint16 *pitches;                        /* Read-only */
188
 
        Uint8 **pixels;                         /* Read-write */
 
209
        Uint32 format;                          /**< Read-only */
 
210
        int w, h;                               /**< Read-only */
 
211
        int planes;                             /**< Read-only */
 
212
        Uint16 *pitches;                        /**< Read-only */
 
213
        Uint8 **pixels;                         /**< Read-write */
189
214
 
190
 
        /* Hardware-specific surface info */
 
215
        /** @name Hardware-specific surface info */
 
216
        /*@{*/
191
217
        struct private_yuvhwfuncs *hwfuncs;
192
218
        struct private_yuvhwdata *hwdata;
 
219
        /*@{*/
193
220
 
194
 
        /* Special flags */
195
 
        Uint32 hw_overlay :1;   /* Flag: This overlay hardware accelerated? */
 
221
        /** @name Special flags */
 
222
        /*@{*/
 
223
        Uint32 hw_overlay :1;   /**< Flag: This overlay hardware accelerated? */
196
224
        Uint32 UnusedBits :31;
 
225
        /*@}*/
197
226
} SDL_Overlay;
198
227
 
199
228
 
200
 
/* Public enumeration for setting the OpenGL window attributes. */
 
229
/** Public enumeration for setting the OpenGL window attributes. */
201
230
typedef enum {
202
231
    SDL_GL_RED_SIZE,
203
232
    SDL_GL_GREEN_SIZE,
218
247
    SDL_GL_SWAP_CONTROL
219
248
} SDL_GLattr;
220
249
 
221
 
/* flags for SDL_SetPalette() */
 
250
/** @name flags for SDL_SetPalette() */
 
251
/*@{*/
222
252
#define SDL_LOGPAL 0x01
223
253
#define SDL_PHYSPAL 0x02
 
254
/*@}*/
224
255
 
225
256
/* Function prototypes */
226
257
 
227
 
/* These functions are used internally, and should not be used unless you
 
258
/**
 
259
 * @name Video Init and Quit
 
260
 * These functions are used internally, and should not be used unless you
228
261
 * have a specific need to specify the video driver you want to use.
229
262
 * You should normally use SDL_Init() or SDL_InitSubSystem().
230
 
 *
231
 
 * SDL_VideoInit() initializes the video subsystem -- sets up a connection
 
263
 */
 
264
/*@{*/
 
265
/**
 
266
 * Initializes the video subsystem. Sets up a connection
232
267
 * to the window manager, etc, and determines the current video mode and
233
268
 * pixel format, but does not initialize a window or graphics mode.
234
269
 * Note that event handling is activated by this routine.
239
274
 */
240
275
extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
241
276
extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
 
277
/*@}*/
242
278
 
243
 
/* This function fills the given character buffer with the name of the
 
279
/**
 
280
 * This function fills the given character buffer with the name of the
244
281
 * video driver, and returns a pointer to it if the video driver has
245
282
 * been initialized.  It returns NULL if no driver has been initialized.
246
283
 */
247
284
extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
248
285
 
249
 
/*
 
286
/**
250
287
 * This function returns a pointer to the current display surface.
251
288
 * If SDL is doing format conversion on the display surface, this
252
289
 * function returns the publicly visible surface, not the real video
254
291
 */
255
292
extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
256
293
 
257
 
/*
 
294
/**
258
295
 * This function returns a read-only pointer to information about the
259
296
 * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
260
297
 * member of the returned structure will contain the pixel format of the
262
299
 */
263
300
extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
264
301
 
265
 
/* 
 
302
/**
266
303
 * Check to see if a particular video mode is supported.
267
304
 * It returns 0 if the requested mode is not supported under any bit depth,
268
305
 * or returns the bits-per-pixel of the closest available mode with the
275
312
 */
276
313
extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
277
314
 
278
 
/*
 
315
/**
279
316
 * Return a pointer to an array of available screen dimensions for the
280
317
 * given format and video flags, sorted largest to smallest.  Returns 
281
318
 * NULL if there are no dimensions available for a particular format, 
286
323
 */
287
324
extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
288
325
 
289
 
/*
 
326
/**
290
327
 * Set up a video mode with the specified width, height and bits-per-pixel.
291
328
 *
292
329
 * If 'bpp' is 0, it is treated as the current display bits per pixel.
347
384
extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
348
385
                        (int width, int height, int bpp, Uint32 flags);
349
386
 
350
 
/*
 
387
/** @name SDL_Update Functions
 
388
 * These functions should not be called while 'screen' is locked.
 
389
 */
 
390
/*@{*/
 
391
/**
351
392
 * Makes sure the given list of rectangles is updated on the given screen.
 
393
 */
 
394
extern DECLSPEC void SDLCALL SDL_UpdateRects
 
395
                (SDL_Surface *screen, int numrects, SDL_Rect *rects);
 
396
/**
352
397
 * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
353
398
 * screen.
354
 
 * These functions should not be called while 'screen' is locked.
355
399
 */
356
 
extern DECLSPEC void SDLCALL SDL_UpdateRects
357
 
                (SDL_Surface *screen, int numrects, SDL_Rect *rects);
358
400
extern DECLSPEC void SDLCALL SDL_UpdateRect
359
401
                (SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
 
402
/*@}*/
360
403
 
361
 
/*
 
404
/**
362
405
 * On hardware that supports double-buffering, this function sets up a flip
363
406
 * and returns.  The hardware will wait for vertical retrace, and then swap
364
407
 * video buffers before the next video surface blit or lock will return.
370
413
 */
371
414
extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
372
415
 
373
 
/*
 
416
/**
374
417
 * Set the gamma correction for each of the color channels.
375
418
 * The gamma values range (approximately) between 0.1 and 10.0
376
419
 * 
380
423
 */
381
424
extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
382
425
 
383
 
/*
 
426
/**
384
427
 * Set the gamma translation table for the red, green, and blue channels
385
428
 * of the video hardware.  Each table is an array of 256 16-bit quantities,
386
429
 * representing a mapping between the input and output for that channel.
394
437
 */
395
438
extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
396
439
 
397
 
/*
 
440
/**
398
441
 * Retrieve the current values of the gamma translation tables.
399
442
 * 
400
443
 * You must pass in valid pointers to arrays of 256 16-bit quantities.
405
448
 */
406
449
extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
407
450
 
408
 
/*
 
451
/**
409
452
 * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
410
453
 * is not a palettized surface, this function does nothing, returning 0.
411
454
 * If all of the colors were set as passed to SDL_SetColors(), it will
423
466
extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
424
467
                        SDL_Color *colors, int firstcolor, int ncolors);
425
468
 
426
 
/*
 
469
/**
427
470
 * Sets a portion of the colormap for a given 8-bit surface.
428
471
 * 'flags' is one or both of:
429
472
 * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
443
486
                                   SDL_Color *colors, int firstcolor,
444
487
                                   int ncolors);
445
488
 
446
 
/*
 
489
/**
447
490
 * Maps an RGB triple to an opaque pixel value for a given pixel format
448
491
 */
449
492
extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
450
493
(const SDL_PixelFormat * const format,
451
494
 const Uint8 r, const Uint8 g, const Uint8 b);
452
495
 
453
 
/*
 
496
/**
454
497
 * Maps an RGBA quadruple to a pixel value for a given pixel format
455
498
 */
456
499
extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
457
500
(const SDL_PixelFormat * const format,
458
501
 const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
459
502
 
460
 
/*
 
503
/**
461
504
 * Maps a pixel value into the RGB components for a given pixel format
462
505
 */
463
 
extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
 
506
extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
 
507
                                const SDL_PixelFormat * const fmt,
464
508
                                Uint8 *r, Uint8 *g, Uint8 *b);
465
509
 
466
 
/*
 
510
/**
467
511
 * Maps a pixel value into the RGBA components for a given pixel format
468
512
 */
469
 
extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
470
 
                                 Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
 
513
extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
 
514
                                const SDL_PixelFormat * const fmt,
 
515
                                Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
471
516
 
472
 
/*
 
517
/** @sa SDL_CreateRGBSurface */
 
518
#define SDL_AllocSurface    SDL_CreateRGBSurface
 
519
/**
473
520
 * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
474
521
 * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
475
522
 * If the depth is greater than 8 bits, the pixel format is set using the
503
550
 * reason the surface could not be placed in video memory, it will not have
504
551
 * the SDL_HWSURFACE flag set, and will be created in system memory instead.
505
552
 */
506
 
#define SDL_AllocSurface    SDL_CreateRGBSurface
507
553
extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
508
554
                        (Uint32 flags, int width, int height, int depth, 
509
555
                        Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
 
556
/** @sa SDL_CreateRGBSurface */
510
557
extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
511
558
                        int width, int height, int depth, int pitch,
512
559
                        Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
513
560
extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
514
561
 
515
 
/*
 
562
/**
516
563
 * SDL_LockSurface() sets up a surface for directly accessing the pixels.
517
564
 * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
518
565
 * to and read from 'surface->pixels', using the pixel format stored in 
533
580
extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
534
581
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
535
582
 
536
 
/*
 
583
/**
537
584
 * Load a surface from a seekable SDL data source (memory or file.)
538
585
 * If 'freesrc' is non-zero, the source will be closed after being read.
539
586
 * Returns the new surface, or NULL if there was an error.
541
588
 */
542
589
extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
543
590
 
544
 
/* Convenience macro -- load a surface from a file */
 
591
/** Convenience macro -- load a surface from a file */
545
592
#define SDL_LoadBMP(file)       SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
546
593
 
547
 
/*
 
594
/**
548
595
 * Save a surface to a seekable SDL data source (memory or file.)
549
596
 * If 'freedst' is non-zero, the source will be closed after being written.
550
597
 * Returns 0 if successful or -1 if there was an error.
552
599
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
553
600
                (SDL_Surface *surface, SDL_RWops *dst, int freedst);
554
601
 
555
 
/* Convenience macro -- save a surface to a file */
 
602
/** Convenience macro -- save a surface to a file */
556
603
#define SDL_SaveBMP(surface, file) \
557
604
                SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
558
605
 
559
 
/*
 
606
/**
560
607
 * Sets the color key (transparent pixel) in a blittable surface.
561
608
 * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
562
609
 * 'key' will be the transparent pixel in the source image of a blit.
568
615
extern DECLSPEC int SDLCALL SDL_SetColorKey
569
616
                        (SDL_Surface *surface, Uint32 flag, Uint32 key);
570
617
 
571
 
/*
 
618
/**
572
619
 * This function sets the alpha value for the entire surface, as opposed to
573
620
 * using the alpha component of each pixel. This value measures the range
574
621
 * of transparency of the surface, 0 being completely transparent to 255
585
632
 */
586
633
extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
587
634
 
588
 
/*
 
635
/**
589
636
 * Sets the clipping rectangle for the destination surface in a blit.
590
637
 *
591
638
 * If the clip rectangle is NULL, clipping will be disabled.
599
646
 */
600
647
extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
601
648
 
602
 
/*
 
649
/**
603
650
 * Gets the clipping rectangle for the destination surface in a blit.
604
651
 * 'rect' must be a pointer to a valid rectangle which will be filled
605
652
 * with the correct values.
606
653
 */
607
654
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
608
655
 
609
 
/*
 
656
/**
610
657
 * Creates a new surface of the specified format, and then copies and maps 
611
658
 * the given surface to it so the blit of the converted surface will be as 
612
659
 * fast as possible.  If this function fails, it returns NULL.
621
668
extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
622
669
                        (SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
623
670
 
624
 
/*
 
671
/**
625
672
 * This performs a fast blit from the source surface to the destination
626
673
 * surface.  It assumes that the source and destination rectangles are
627
674
 * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
677
724
 * If either of the surfaces were in video memory, and the blit returns -2,
678
725
 * the video memory was lost, so it should be reloaded with artwork and 
679
726
 * re-blitted:
680
 
        while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
681
 
                while ( SDL_LockSurface(image) < 0 )
682
 
                        Sleep(10);
683
 
                -- Write image pixels to image->pixels --
684
 
                SDL_UnlockSurface(image);
685
 
        }
 
727
 * @code
 
728
 *      while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
 
729
 *              while ( SDL_LockSurface(image) < 0 )
 
730
 *                      Sleep(10);
 
731
 *              -- Write image pixels to image->pixels --
 
732
 *              SDL_UnlockSurface(image);
 
733
 *      }
 
734
 * @endcode
 
735
 *
686
736
 * This happens under DirectX 5.0 when the system switches away from your
687
737
 * fullscreen application.  The lock will also fail until you have access
688
738
 * to the video memory again.
 
739
 *
 
740
 * You should call SDL_BlitSurface() unless you know exactly how SDL
 
741
 * blitting works internally and how to use the other blit functions.
689
742
 */
690
 
/* You should call SDL_BlitSurface() unless you know exactly how SDL
691
 
   blitting works internally and how to use the other blit functions.
692
 
*/
693
743
#define SDL_BlitSurface SDL_UpperBlit
694
744
 
695
 
/* This is the public blit function, SDL_BlitSurface(), and it performs
696
 
   rectangle validation and clipping before passing it to SDL_LowerBlit()
697
 
*/
 
745
/** This is the public blit function, SDL_BlitSurface(), and it performs
 
746
 *  rectangle validation and clipping before passing it to SDL_LowerBlit()
 
747
 */
698
748
extern DECLSPEC int SDLCALL SDL_UpperBlit
699
749
                        (SDL_Surface *src, SDL_Rect *srcrect,
700
750
                         SDL_Surface *dst, SDL_Rect *dstrect);
701
 
/* This is a semi-private blit function and it performs low-level surface
702
 
   blitting only.
703
 
*/
 
751
/** This is a semi-private blit function and it performs low-level surface
 
752
 *  blitting only.
 
753
 */
704
754
extern DECLSPEC int SDLCALL SDL_LowerBlit
705
755
                        (SDL_Surface *src, SDL_Rect *srcrect,
706
756
                         SDL_Surface *dst, SDL_Rect *dstrect);
707
757
 
708
 
/*
 
758
/**
709
759
 * This function performs a fast fill of the given rectangle with 'color'
710
760
 * The given rectangle is clipped to the destination surface clip area
711
761
 * and the final fill rectangle is saved in the passed in pointer.
717
767
extern DECLSPEC int SDLCALL SDL_FillRect
718
768
                (SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
719
769
 
720
 
/* 
 
770
/**
721
771
 * This function takes a surface and copies it to a new surface of the
722
772
 * pixel format and colors of the video framebuffer, suitable for fast
723
773
 * blitting onto the display surface.  It calls SDL_ConvertSurface()
730
780
 */
731
781
extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
732
782
 
733
 
/* 
 
783
/**
734
784
 * This function takes a surface and copies it to a new surface of the
735
785
 * pixel format and colors of the video framebuffer (if possible),
736
786
 * suitable for fast alpha blitting onto the display surface.
746
796
 
747
797
 
748
798
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
749
 
/* YUV video surface overlay functions                                       */
 
799
/** @name YUV video surface overlay functions                                */ /*@{*/
750
800
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
751
801
 
752
 
/* This function creates a video output overlay
753
 
   Calling the returned surface an overlay is something of a misnomer because
754
 
   the contents of the display surface underneath the area where the overlay
755
 
   is shown is undefined - it may be overwritten with the converted YUV data.
756
 
*/
 
802
/** This function creates a video output overlay
 
803
 *  Calling the returned surface an overlay is something of a misnomer because
 
804
 *  the contents of the display surface underneath the area where the overlay
 
805
 *  is shown is undefined - it may be overwritten with the converted YUV data.
 
806
 */
757
807
extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
758
808
                                Uint32 format, SDL_Surface *display);
759
809
 
760
 
/* Lock an overlay for direct access, and unlock it when you are done */
 
810
/** Lock an overlay for direct access, and unlock it when you are done */
761
811
extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
762
812
extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
763
813
 
764
 
/* Blit a video overlay to the display surface.
765
 
   The contents of the video surface underneath the blit destination are
766
 
   not defined.  
767
 
   The width and height of the destination rectangle may be different from
768
 
   that of the overlay, but currently only 2x scaling is supported.
769
 
*/
 
814
/** Blit a video overlay to the display surface.
 
815
 *  The contents of the video surface underneath the blit destination are
 
816
 *  not defined.  
 
817
 *  The width and height of the destination rectangle may be different from
 
818
 *  that of the overlay, but currently only 2x scaling is supported.
 
819
 */
770
820
extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
771
821
 
772
 
/* Free a video overlay */
 
822
/** Free a video overlay */
773
823
extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
774
824
 
775
 
 
776
 
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
777
 
/* OpenGL support functions.                                                 */
778
 
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
779
 
 
780
 
/*
 
825
/*@}*/
 
826
 
 
827
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
828
/** @name OpenGL support functions.                                          */ /*@{*/
 
829
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
830
 
 
831
/**
781
832
 * Dynamically load an OpenGL library, or the default one if path is NULL
782
833
 *
783
834
 * If you do this, you need to retrieve all of the GL functions used in
785
836
 */
786
837
extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
787
838
 
788
 
/*
 
839
/**
789
840
 * Get the address of a GL function
790
841
 */
791
842
extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
792
843
 
793
 
/*
 
844
/**
794
845
 * Set an attribute of the OpenGL subsystem before intialization.
795
846
 */
796
847
extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
797
848
 
798
 
/*
 
849
/**
799
850
 * Get an attribute of the OpenGL subsystem from the windowing
800
851
 * interface, such as glX. This is of course different from getting
801
852
 * the values from SDL's internal OpenGL subsystem, which only
806
857
 */
807
858
extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
808
859
 
809
 
/*
 
860
/**
810
861
 * Swap the OpenGL buffers, if double-buffering is supported.
811
862
 */
812
863
extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
813
864
 
814
 
/*
 
865
/** @name OpenGL Internal Functions
815
866
 * Internal functions that should not be called unless you have read
816
867
 * and understood the source code for these functions.
817
868
 */
 
869
/*@{*/
818
870
extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
819
871
extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
820
872
extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
821
 
 
822
 
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
823
 
/* These functions allow interaction with the window manager, if any.        */
824
 
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
825
 
 
826
 
/*
827
 
 * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
 
873
/*@}*/
 
874
 
 
875
/*@}*/
 
876
 
 
877
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
878
/** @name Window Manager Functions                                           */
 
879
/** These functions allow interaction with the window manager, if any.       */ /*@{*/
 
880
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
881
 
 
882
/**
 
883
 * Sets the title and icon text of the display window (UTF-8 encoded)
828
884
 */
829
885
extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
 
886
/**
 
887
 * Gets the title and icon text of the display window (UTF-8 encoded)
 
888
 */
830
889
extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
831
890
 
832
 
/*
 
891
/**
833
892
 * Sets the icon for the display window.
834
893
 * This function must be called before the first call to SDL_SetVideoMode().
835
894
 * It takes an icon surface, and a mask in MSB format.
837
896
 */
838
897
extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
839
898
 
840
 
/*
 
899
/**
841
900
 * This function iconifies the window, and returns 1 if it succeeded.
842
901
 * If the function succeeds, it generates an SDL_APPACTIVE loss event.
843
902
 * This function is a noop and returns 0 in non-windowed environments.
844
903
 */
845
904
extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
846
905
 
847
 
/*
 
906
/**
848
907
 * Toggle fullscreen mode without changing the contents of the screen.
849
908
 * If the display surface does not require locking before accessing
850
909
 * the pixel information, then the memory pointers will not change.
861
920
 */
862
921
extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
863
922
 
864
 
/*
865
 
 * This function allows you to set and query the input grab state of
866
 
 * the application.  It returns the new input grab state.
867
 
 */
868
923
typedef enum {
869
924
        SDL_GRAB_QUERY = -1,
870
925
        SDL_GRAB_OFF = 0,
871
926
        SDL_GRAB_ON = 1,
872
 
        SDL_GRAB_FULLSCREEN     /* Used internally */
 
927
        SDL_GRAB_FULLSCREEN     /**< Used internally */
873
928
} SDL_GrabMode;
874
 
/*
 
929
/**
 
930
 * This function allows you to set and query the input grab state of
 
931
 * the application.  It returns the new input grab state.
 
932
 *
875
933
 * Grabbing means that the mouse is confined to the application window,
876
934
 * and nearly all keyboard input is passed directly to the application,
877
935
 * and not interpreted by a window manager, if any.
878
936
 */
879
937
extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
880
938
 
881
 
/* Not in public API at the moment - do not use! */
 
939
/*@}*/
 
940
 
 
941
/** @internal Not in public API at the moment - do not use! */
882
942
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
883
943
                                    SDL_Surface *dst, SDL_Rect *dstrect);
884
944