include/SDL_compat.h
changeset 3407 d3baf5ac4e37
parent 3164 c5b2884c26b4
child 3536 0267b8b1595c
     1.1 --- a/include/SDL_compat.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_compat.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -20,13 +20,26 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* This file contains functions for backwards compatibility with SDL 1.2 */
     1.8 + /**
     1.9 + *  \defgroup Compatibility SDL 1.2 Compatibility API
    1.10 + */
    1.11 +/*@{*/
    1.12  
    1.13 -/* 
    1.14 -   #define SDL_NO_COMPAT to prevent SDL_compat.h from being included.
    1.15 -   SDL_NO_COMPAT is intended to make it easier to covert SDL 1.2 code to
    1.16 -   SDL 1.3/2.0
    1.17 -*/
    1.18 +/**
    1.19 + *  \file SDL_compat.h
    1.20 + *
    1.21 + *  This file contains functions for backwards compatibility with SDL 1.2.
    1.22 + */
    1.23 +
    1.24 +/**
    1.25 + *  \def SDL_NO_COMPAT
    1.26 + *
    1.27 + *  #define SDL_NO_COMPAT to prevent SDL_compat.h from being included.
    1.28 + *  SDL_NO_COMPAT is intended to make it easier to covert SDL 1.2 code to
    1.29 + *  SDL 1.3/2.0.
    1.30 + */
    1.31 +
    1.32 + /*@}*/
    1.33  
    1.34  #ifdef SDL_NO_COMPAT
    1.35  #define _SDL_compat_h
    1.36 @@ -46,7 +59,16 @@
    1.37  /* *INDENT-ON* */
    1.38  #endif
    1.39  
    1.40 -#define SDL_SWSURFACE       0x00000000  /* Not used */
    1.41 +/**
    1.42 + *  \addtogroup Compatibility
    1.43 + */
    1.44 +/*@{*/
    1.45 +
    1.46 +/**
    1.47 + *  \name Surface flags
    1.48 + */
    1.49 +/*@{*/
    1.50 +#define SDL_SWSURFACE       0x00000000  /**< \note Not used */
    1.51  #define SDL_SRCALPHA        0x00010000
    1.52  #define SDL_SRCCOLORKEY     0x00020000
    1.53  #define SDL_ANYFORMAT       0x00100000
    1.54 @@ -56,10 +78,11 @@
    1.55  #define SDL_RESIZABLE       0x01000000
    1.56  #define SDL_NOFRAME         0x02000000
    1.57  #define SDL_OPENGL          0x04000000
    1.58 -#define SDL_HWSURFACE       0x08000001  /* Not used */
    1.59 -#define SDL_ASYNCBLIT       0x08000000  /* Not used */
    1.60 -#define SDL_RLEACCELOK      0x08000000  /* Not used */
    1.61 -#define SDL_HWACCEL         0x08000000  /* Not used */
    1.62 +#define SDL_HWSURFACE       0x08000001  /**< \note Not used */
    1.63 +#define SDL_ASYNCBLIT       0x08000000  /**< \note Not used */
    1.64 +#define SDL_RLEACCELOK      0x08000000  /**< \note Not used */
    1.65 +#define SDL_HWACCEL         0x08000000  /**< \note Not used */
    1.66 +/*@}*//*Surface flags*/
    1.67  
    1.68  #define SDL_APPMOUSEFOCUS	0x01
    1.69  #define SDL_APPINPUTFOCUS	0x02
    1.70 @@ -103,35 +126,51 @@
    1.71      int current_h;
    1.72  } SDL_VideoInfo;
    1.73  
    1.74 -/* The most common video overlay formats.
    1.75 -   For an explanation of these pixel formats, see:
    1.76 -   http://www.webartz.com/fourcc/indexyuv.htm
    1.77 +/**
    1.78 + *  \name Overlay formats
    1.79 + *
    1.80 + *  The most common video overlay formats.
    1.81 + *  
    1.82 + *  For an explanation of these pixel formats, see:
    1.83 + *  http://www.webartz.com/fourcc/indexyuv.htm
    1.84 + *  
    1.85 + *  For information on the relationship between color spaces, see:
    1.86 + *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    1.87 + */
    1.88 +/*@{*/
    1.89 +#define SDL_YV12_OVERLAY  0x32315659    /**< Planar mode: Y + V + U  (3 planes) */
    1.90 +#define SDL_IYUV_OVERLAY  0x56555949    /**< Planar mode: Y + U + V  (3 planes) */
    1.91 +#define SDL_YUY2_OVERLAY  0x32595559    /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
    1.92 +#define SDL_UYVY_OVERLAY  0x59565955    /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
    1.93 +#define SDL_YVYU_OVERLAY  0x55595659    /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
    1.94 +/*@}*//*Overlay formats*/
    1.95  
    1.96 -   For information on the relationship between color spaces, see:
    1.97 -   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    1.98 +/**
    1.99 + *  The YUV hardware video overlay.
   1.100   */
   1.101 -#define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
   1.102 -#define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
   1.103 -#define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   1.104 -#define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   1.105 -#define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   1.106 -
   1.107 -/* The YUV hardware video overlay */
   1.108  typedef struct SDL_Overlay
   1.109  {
   1.110 -    Uint32 format;              /* Read-only */
   1.111 -    int w, h;                   /* Read-only */
   1.112 -    int planes;                 /* Read-only */
   1.113 -    Uint16 *pitches;            /* Read-only */
   1.114 -    Uint8 **pixels;             /* Read-write */
   1.115 +    Uint32 format;              /**< Read-only */
   1.116 +    int w, h;                   /**< Read-only */
   1.117 +    int planes;                 /**< Read-only */
   1.118 +    Uint16 *pitches;            /**< Read-only */
   1.119 +    Uint8 **pixels;             /**< Read-write */
   1.120  
   1.121 -    /* Hardware-specific surface info */
   1.122 +    /** 
   1.123 +     *  \name Hardware-specific surface info
   1.124 +     */
   1.125 +    /*@{*/
   1.126      struct private_yuvhwfuncs *hwfuncs;
   1.127      struct private_yuvhwdata *hwdata;
   1.128 +    /*@}*//*Hardware-specific surface info*/
   1.129  
   1.130 -    /* Special flags */
   1.131 -    Uint32 hw_overlay:1;        /* Flag: This overlay hardware accelerated? */
   1.132 +    /** 
   1.133 +     *  \name Special flags
   1.134 +     */
   1.135 +    /*@{*/
   1.136 +    Uint32 hw_overlay:1;        /**< Flag: This overlay hardware accelerated? */
   1.137      Uint32 UnusedBits:31;
   1.138 +    /*@}*//*Special flags*/
   1.139  } SDL_Overlay;
   1.140  
   1.141  typedef enum
   1.142 @@ -143,9 +182,17 @@
   1.143  
   1.144  struct SDL_SysWMinfo;
   1.145  
   1.146 -/* Obsolete or renamed key codes */
   1.147 +/**
   1.148 + *  \name Obsolete or renamed key codes
   1.149 + */
   1.150 +/*@{*/
   1.151  
   1.152 -/* These key constants were renamed for clarity or consistency. */
   1.153 +/** 
   1.154 + *  \name Renamed keys
   1.155 + *
   1.156 + *  These key constants were renamed for clarity or consistency. 
   1.157 + */
   1.158 +/*@{*/
   1.159  #define SDLK_0	'0'
   1.160  #define SDLK_1	'1'
   1.161  #define SDLK_2	'2'
   1.162 @@ -214,19 +261,35 @@
   1.163  #define SDLK_NUMLOCK SDLK_NUMLOCKCLEAR
   1.164  #define SDLK_SCROLLOCK SDLK_SCROLLLOCK
   1.165  #define SDLK_PRINT SDLK_PRINTSCREEN
   1.166 +/*@}*//*Renamed keys*/
   1.167  
   1.168 -/* The META modifier is equivalent to the GUI modifier from the USB standard */
   1.169 +/**
   1.170 + *  \name META modifier
   1.171 + *  
   1.172 + *  The META modifier is equivalent to the GUI modifier from the USB standard.
   1.173 + */
   1.174 +/*@{*/
   1.175  #define KMOD_LMETA KMOD_LGUI
   1.176  #define KMOD_RMETA KMOD_RGUI
   1.177  #define KMOD_META KMOD_GUI
   1.178 +/*@}*//*META modifier*/
   1.179  
   1.180 -/* These keys don't appear in the USB specification (or at least not under those names). I'm unsure if the following assignments make sense or if these codes should be defined as actual additional SDLK_ constants. */
   1.181 +/** 
   1.182 + *  \name Not in USB
   1.183 + *
   1.184 + *  These keys don't appear in the USB specification (or at least not under 
   1.185 + *  those names). I'm unsure if the following assignments make sense or if these
   1.186 + *  codes should be defined as actual additional SDLK_ constants.
   1.187 + */
   1.188 +/*@{*/
   1.189  #define SDLK_LSUPER SDLK_LMETA
   1.190  #define SDLK_RSUPER SDLK_RMETA
   1.191  #define SDLK_COMPOSE SDLK_APPLICATION
   1.192  #define SDLK_BREAK SDLK_STOP
   1.193  #define SDLK_EURO SDLK_2
   1.194 +/*@}*//*Not in USB*/
   1.195  
   1.196 +/*@}*//*Obsolete or renamed key codes*/
   1.197  
   1.198  #define SDL_SetModuleHandle(x)
   1.199  #define SDL_AllocSurface    SDL_CreateRGBSurface
   1.200 @@ -287,6 +350,8 @@
   1.201  extern DECLSPEC void SDLCALL SDL_GetKeyRepeat(int *delay, int *interval);
   1.202  extern DECLSPEC int SDLCALL SDL_EnableUNICODE(int enable);
   1.203  
   1.204 +/*@}*//*Compatibility*/
   1.205 +
   1.206  /* Ends C function definitions when using C++ */
   1.207  #ifdef __cplusplus
   1.208  /* *INDENT-OFF* */