include/SDL_video.h
changeset 1985 8055185ae4ed
parent 1969 5d3724f64f2b
child 1986 f4c65e3bfaed
equal deleted inserted replaced
1984:b910bcabec26 1985:8055185ae4ed
   174     SDL_RENDERER_PRESENTCOPY = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
   174     SDL_RENDERER_PRESENTCOPY = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
   175     SDL_RENDERER_PRESENTFLIP2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
   175     SDL_RENDERER_PRESENTFLIP2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
   176     SDL_RENDERER_PRESENTFLIP3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
   176     SDL_RENDERER_PRESENTFLIP3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
   177     SDL_RENDERER_PRESENTDISCARD = 0x00000010,   /**< Present leaves the contents of the backbuffer undefined */
   177     SDL_RENDERER_PRESENTDISCARD = 0x00000010,   /**< Present leaves the contents of the backbuffer undefined */
   178     SDL_RENDERER_PRESENTVSYNC = 0x00000020,     /**< Present is synchronized with the refresh rate */
   178     SDL_RENDERER_PRESENTVSYNC = 0x00000020,     /**< Present is synchronized with the refresh rate */
   179     SDL_RENDERER_ACCELERATED = 0x00000040,      /**< The renderer uses hardware acceleration */
   179     SDL_RENDERER_ACCELERATED = 0x0000040,       /**< The renderer uses hardware acceleration */
   180 } SDL_RendererFlags;
   180 } SDL_RendererFlags;
   181 
   181 
   182 /**
   182 /**
   183  * \struct SDL_RendererInfo
   183  * \struct SDL_RendererInfo
   184  *
   184  *
   186  */
   186  */
   187 typedef struct SDL_RendererInfo
   187 typedef struct SDL_RendererInfo
   188 {
   188 {
   189     const char *name;           /**< The name of the renderer */
   189     const char *name;           /**< The name of the renderer */
   190     Uint32 flags;               /**< Supported SDL_RendererFlags */
   190     Uint32 flags;               /**< Supported SDL_RendererFlags */
       
   191     Uint32 mod_modes;           /**< A mask of supported channel modulation */
   191     Uint32 blend_modes;         /**< A mask of supported blend modes */
   192     Uint32 blend_modes;         /**< A mask of supported blend modes */
   192     Uint32 scale_modes;         /**< A mask of supported scale modes */
   193     Uint32 scale_modes;         /**< A mask of supported scale modes */
   193     Uint32 num_texture_formats; /**< The number of available texture formats */
   194     Uint32 num_texture_formats; /**< The number of available texture formats */
   194     Uint32 texture_formats[20]; /**< The available texture formats */
   195     Uint32 texture_formats[20]; /**< The available texture formats */
   195     int max_texture_width;      /**< The maximimum texture width */
   196     int max_texture_width;      /**< The maximimum texture width */
   206     SDL_TEXTUREACCESS_LOCAL,    /**< Lockable system memory */
   207     SDL_TEXTUREACCESS_LOCAL,    /**< Lockable system memory */
   207     SDL_TEXTUREACCESS_REMOTE,   /**< Unlockable video memory */
   208     SDL_TEXTUREACCESS_REMOTE,   /**< Unlockable video memory */
   208 } SDL_TextureAccess;
   209 } SDL_TextureAccess;
   209 
   210 
   210 /**
   211 /**
       
   212  * \enum SDL_TextureModulate
       
   213  *
       
   214  * \brief The texture channel modulation used in SDL_RenderCopy()
       
   215  */
       
   216 typedef enum
       
   217 {
       
   218     SDL_TEXTUREMODULATE_NONE = 0x00000000,     /**< No modulation */
       
   219     SDL_TEXTUREMODULATE_COLOR = 0x00000001,    /**< srcC = srcC * color */
       
   220     SDL_TEXTUREMODULATE_ALPHA = 0x00000002,    /**< srcA = srcA * alpha */
       
   221 } SDL_TextureModulate;
       
   222 
       
   223 /**
   211  * \enum SDL_TextureBlendMode
   224  * \enum SDL_TextureBlendMode
   212  *
   225  *
   213  * \brief The blend mode used in SDL_RenderCopy()
   226  * \brief The texture blend mode used in SDL_RenderCopy()
   214  */
   227  */
   215 typedef enum
   228 typedef enum
   216 {
   229 {
   217     SDL_TEXTUREBLENDMODE_NONE = 0x00000000,     /**< No blending */
   230     SDL_TEXTUREBLENDMODE_NONE = 0x00000000,     /**< No blending */
   218     SDL_TEXTUREBLENDMODE_MASK = 0x00000001,     /**< dst = A ? src : dst (alpha is mask) */
   231     SDL_TEXTUREBLENDMODE_MASK = 0x00000001,     /**< dst = A ? src : dst (alpha is mask) */
   222 } SDL_TextureBlendMode;
   235 } SDL_TextureBlendMode;
   223 
   236 
   224 /**
   237 /**
   225  * \enum SDL_TextureScaleMode
   238  * \enum SDL_TextureScaleMode
   226  *
   239  *
   227  * \brief The scale mode used in SDL_RenderCopy()
   240  * \brief The texture scale mode used in SDL_RenderCopy()
   228  */
   241  */
   229 typedef enum
   242 typedef enum
   230 {
   243 {
   231     SDL_TEXTURESCALEMODE_NONE = 0x00000000,     /**< No scaling, rectangles must match dimensions */
   244     SDL_TEXTURESCALEMODE_NONE = 0x00000000,     /**< No scaling, rectangles must match dimensions */
   232     SDL_TEXTURESCALEMODE_FAST = 0x00000001,     /**< Point sampling or equivalent algorithm */
   245     SDL_TEXTURESCALEMODE_FAST = 0x00000001,     /**< Point sampling or equivalent algorithm */
   270     SDL_PixelFormat *format;    /* Read-only */
   283     SDL_PixelFormat *format;    /* Read-only */
   271     int w, h;                   /* Read-only */
   284     int w, h;                   /* Read-only */
   272     int pitch;                  /* Read-only */
   285     int pitch;                  /* Read-only */
   273     void *pixels;               /* Read-write */
   286     void *pixels;               /* Read-write */
   274 
   287 
       
   288     /* Application data associated with the surfade */
       
   289     void *userdata;             /* Read-write */
       
   290 
   275     /* texture associated with the surface, if any */
   291     /* texture associated with the surface, if any */
   276     SDL_TextureID textureID;
   292     SDL_TextureID textureID;    /* Read-only */
   277 
   293 
   278     /* information needed for surfaces requiring locks */
   294     /* information needed for surfaces requiring locks */
   279     int locked;
   295     int locked;                 /* Read-only */
   280     void *lock_data;
   296     void *lock_data;            /* Read-only */
   281 
   297 
   282     /* clipping information */
   298     /* clipping information */
   283     SDL_Rect clip_rect;         /* Read-only */
   299     SDL_Rect clip_rect;         /* Read-only */
   284 
   300 
   285     /* info for fast blit mapping to other surfaces */
   301     /* info for fast blit mapping to other surfaces */
   996                                                   SDL_Color * colors,
  1012                                                   SDL_Color * colors,
   997                                                   int firstcolor,
  1013                                                   int firstcolor,
   998                                                   int ncolors);
  1014                                                   int ncolors);
   999 
  1015 
  1000 /**
  1016 /**
       
  1017  * \fn int SDL_SetTextureColorMod(SDL_TextureID textureID, Uint8 r, Uint8 g, Uint8 b)
       
  1018  *
       
  1019  * \brief Set an additional color value used in render copy operations
       
  1020  *
       
  1021  * \param texture The texture to update
       
  1022  * \param r The red source color value multiplied into copy operations
       
  1023  * \param g The green source color value multiplied into copy operations
       
  1024  * \param b The blue source color value multiplied into copy operations
       
  1025  *
       
  1026  * \return 0 on success, or -1 if the texture is not valid or color modulation is not supported
       
  1027  *
       
  1028  * \sa SDL_GetTextureColorMod()
       
  1029  */
       
  1030 extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_TextureID textureID,
       
  1031                                                    Uint8 r, Uint8 g, Uint8 b);
       
  1032 
       
  1033 
       
  1034 /**
       
  1035  * \fn int SDL_GetTextureColorMod(SDL_TextureID textureID, Uint8 *r, Uint8 *g, Uint8 *b)
       
  1036  *
       
  1037  * \brief Get the additional color value used in render copy operations
       
  1038  *
       
  1039  * \param texture The texture to query
       
  1040  * \param r A pointer filled in with the source red color value
       
  1041  * \param g A pointer filled in with the source green color value
       
  1042  * \param b A pointer filled in with the source blue color value
       
  1043  *
       
  1044  * \return 0 on success, or -1 if the texture is not valid
       
  1045  *
       
  1046  * \sa SDL_SetTextureColorMod()
       
  1047  */
       
  1048 extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_TextureID textureID,
       
  1049                                                    Uint8 * r, Uint8 * g,
       
  1050                                                    Uint8 * b);
       
  1051 
       
  1052 /**
       
  1053  * \fn int SDL_SetTextureAlphaMod(SDL_TextureID textureID, Uint8 alpha)
       
  1054  *
       
  1055  * \brief Set an additional alpha value used in render copy operations
       
  1056  *
       
  1057  * \param texture The texture to update
       
  1058  * \param alpha The source alpha value multiplied into copy operations.
       
  1059  *
       
  1060  * \return 0 on success, or -1 if the texture is not valid or alpha modulation is not supported
       
  1061  *
       
  1062  * \sa SDL_GetTextureAlphaMod()
       
  1063  */
       
  1064 extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_TextureID textureID,
       
  1065                                                    Uint8 alpha);
       
  1066 
       
  1067 /**
       
  1068  * \fn int SDL_GetTextureAlphaMod(SDL_TextureID textureID, Uint8 *alpha)
       
  1069  *
       
  1070  * \brief Get the additional alpha value used in render copy operations
       
  1071  *
       
  1072  * \param texture The texture to query
       
  1073  * \param alpha A pointer filled in with the source alpha value
       
  1074  *
       
  1075  * \return 0 on success, or -1 if the texture is not valid
       
  1076  *
       
  1077  * \sa SDL_SetTextureAlphaMod()
       
  1078  */
       
  1079 extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_TextureID textureID,
       
  1080                                                    Uint8 * alpha);
       
  1081 
       
  1082 /**
       
  1083  * \fn int SDL_SetTextureBlendMode(SDL_TextureID textureID, int blendMode)
       
  1084  *
       
  1085  * \brief Set the blend mode used for texture copy operations
       
  1086  *
       
  1087  * \param texture The texture to update
       
  1088  * \param blendMode SDL_TextureBlendMode to use for texture blending
       
  1089  *
       
  1090  * \return 0 on success, or -1 if the texture is not valid or the blend mode is not supported
       
  1091  *
       
  1092  * \note If the blend mode is not supported, the closest supported mode is chosen.
       
  1093  *
       
  1094  * \sa SDL_GetTextureBlendMode()
       
  1095  */
       
  1096 extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_TextureID textureID,
       
  1097                                                     int blendMode);
       
  1098 
       
  1099 /**
       
  1100  * \fn int SDL_GetTextureBlendMode(SDL_TextureID textureID, int *blendMode)
       
  1101  *
       
  1102  * \brief Get the blend mode used for texture copy operations
       
  1103  *
       
  1104  * \param texture The texture to query
       
  1105  * \param blendMode A pointer filled in with the current blend mode
       
  1106  *
       
  1107  * \return 0 on success, or -1 if the texture is not valid
       
  1108  *
       
  1109  * \sa SDL_SetTextureBlendMode()
       
  1110  */
       
  1111 extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_TextureID textureID,
       
  1112                                                     int *blendMode);
       
  1113 
       
  1114 /**
       
  1115  * \fn int SDL_SetTextureScaleMode(SDL_TextureID textureID, int scaleMode)
       
  1116  *
       
  1117  * \brief Set the scale mode used for texture copy operations
       
  1118  *
       
  1119  * \param texture The texture to update
       
  1120  * \param scaleMode SDL_TextureScaleMode to use for texture scaling
       
  1121  *
       
  1122  * \return 0 on success, or -1 if the texture is not valid or the scale mode is not supported
       
  1123  *
       
  1124  * \note If the scale mode is not supported, the closest supported mode is chosen.
       
  1125  *
       
  1126  * \sa SDL_GetTextureScaleMode()
       
  1127  */
       
  1128 extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_TextureID textureID,
       
  1129                                                     int scaleMode);
       
  1130 
       
  1131 /**
       
  1132  * \fn int SDL_GetTextureScaleMode(SDL_TextureID textureID, int *scaleMode)
       
  1133  *
       
  1134  * \brief Get the scale mode used for texture copy operations
       
  1135  *
       
  1136  * \param texture The texture to query
       
  1137  * \param scaleMode A pointer filled in with the current scale mode
       
  1138  *
       
  1139  * \return 0 on success, or -1 if the texture is not valid
       
  1140  *
       
  1141  * \sa SDL_SetTextureScaleMode()
       
  1142  */
       
  1143 extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_TextureID textureID,
       
  1144                                                     int *scaleMode);
       
  1145 
       
  1146 /**
  1001  * \fn int SDL_UpdateTexture(SDL_TextureID textureID, const SDL_Rect *rect, const void *pixels, int pitch)
  1147  * \fn int SDL_UpdateTexture(SDL_TextureID textureID, const SDL_Rect *rect, const void *pixels, int pitch)
  1002  *
  1148  *
  1003  * \brief Update the given texture rectangle with new pixel data.
  1149  * \brief Update the given texture rectangle with new pixel data.
  1004  *
  1150  *
  1005  * \param texture The texture to update
  1151  * \param texture The texture to update
  1059 extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
  1205 extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
  1060                                               int numrects,
  1206                                               int numrects,
  1061                                               const SDL_Rect * rects);
  1207                                               const SDL_Rect * rects);
  1062 
  1208 
  1063 /**
  1209 /**
  1064  * \fn void SDL_RenderFill(const SDL_Rect *rect, Uint32 color)
  1210  * \fn void SDL_RenderFill(Uint8 r, Uint8 g, Uint8 b, Uint8 a, const SDL_Rect *rect)
  1065  *
  1211  *
  1066  * \brief Fill the current rendering target with the specified color.
  1212  * \brief Fill the current rendering target with the specified color.
  1067  *
  1213  *
       
  1214  * \param r The red value used to fill the rendering target
       
  1215  * \param g The green value used to fill the rendering target
       
  1216  * \param b The blue value used to fill the rendering target
       
  1217  * \param a The alpha value used to fill the rendering target, usually SDL_ALPHA_OPAQUE (255)
  1068  * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
  1218  * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
  1069  * \param color An ARGB color value.
       
  1070  *
  1219  *
  1071  * \return 0 on success, or -1 if there is no rendering context current
  1220  * \return 0 on success, or -1 if there is no rendering context current
  1072  */
  1221  */
  1073 extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect,
  1222 extern DECLSPEC int SDLCALL SDL_RenderFill(Uint8 r, Uint8 g, Uint8 b, Uint8 a,
  1074                                            Uint32 color);
  1223                                            const SDL_Rect * rect);
  1075 
  1224 
  1076 /**
  1225 /**
  1077  * \fn int SDL_RenderCopy(SDL_TextureID textureID, const SDL_Rect *srcrect, const SDL_Rect *dstrect, Uint32 blendMode, Uint32 scaleMode)
  1226  * \fn int SDL_RenderCopy(SDL_TextureID textureID, const SDL_Rect *srcrect, const SDL_Rect *dstrect)
  1078  *
  1227  *
  1079  * \brief Copy a portion of the texture to the current rendering target.
  1228  * \brief Copy a portion of the texture to the current rendering target.
  1080  *
  1229  *
  1081  * \param texture The source texture.
  1230  * \param texture The source texture.
  1082  * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
  1231  * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
  1083  * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
  1232  * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
  1084  * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
       
  1085  * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
       
  1086  *
  1233  *
  1087  * \return 0 on success, or -1 if there is no rendering context current, or the driver doesn't support the requested operation.
  1234  * \return 0 on success, or -1 if there is no rendering context current, or the driver doesn't support the requested operation.
  1088  *
       
  1089  * \note You can check the video driver info to see what operations are supported.
       
  1090  */
  1235  */
  1091 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
  1236 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
  1092                                            const SDL_Rect * srcrect,
  1237                                            const SDL_Rect * srcrect,
  1093                                            const SDL_Rect * dstrect,
  1238                                            const SDL_Rect * dstrect);
  1094                                            int blendMode, int scaleMode);
       
  1095 
  1239 
  1096 /**
  1240 /**
  1097  * \fn int SDL_RenderReadPixels(const SDL_Rect *rect, void *pixels, int pitch)
  1241  * \fn int SDL_RenderReadPixels(const SDL_Rect *rect, void *pixels, int pitch)
  1098  *
  1242  *
  1099  * \brief Read pixels from the current rendering target.
  1243  * \brief Read pixels from the current rendering target.