comparison include/SDL_video.h @ 1969:5d3724f64f2b

Clarified the difference between render drivers and render contexts
author Sam Lantinga <slouken@libsdl.org>
date Sun, 06 Aug 2006 00:09:04 +0000
parents 9f589a1f74a5
children 8055185ae4ed
comparison
equal deleted inserted replaced
1968:9f589a1f74a5 1969:5d3724f64f2b
164 } SDL_WindowEventID; 164 } SDL_WindowEventID;
165 165
166 /** 166 /**
167 * \enum SDL_RendererFlags 167 * \enum SDL_RendererFlags
168 * 168 *
169 * \brief Flags used when initializing a render manager. 169 * \brief Flags used when creating a rendering context
170 */ 170 */
171 typedef enum 171 typedef enum
172 { 172 {
173 SDL_RENDERER_SINGLEBUFFER = 0x00000001, /**< Render directly to the window, if possible */ 173 SDL_RENDERER_SINGLEBUFFER = 0x00000001, /**< Render directly to the window, if possible */
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 */
180 } SDL_RendererFlags; 180 } SDL_RendererFlags;
181 181
182 /** 182 /**
183 * \struct SDL_RendererInfo 183 * \struct SDL_RendererInfo
184 * 184 *
185 * \brief Information on the capabilities of a render manager. 185 * \brief Information on the capabilities of a render driver or context
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 */
825 * \brief Destroy a window. 825 * \brief Destroy a window.
826 */ 826 */
827 extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID); 827 extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
828 828
829 /** 829 /**
830 * \fn int SDL_GetNumRenderers(void) 830 * \fn int SDL_GetNumRenderDrivers(void)
831 * 831 *
832 * \brief Get the number of render managers on the current display. 832 * \brief Get the number of 2D rendering drivers available for the current display.
833 * 833 *
834 * A render manager is a set of code that handles rendering and texture 834 * A render driver is a set of code that handles rendering and texture
835 * management on a particular display. Normally there is only one, but 835 * management on a particular display. Normally there is only one, but
836 * some drivers may have several available with different capabilities. 836 * some drivers may have several available with different capabilities.
837 * 837 *
838 * \sa SDL_GetRendererInfo() 838 * \sa SDL_GetRenderDriverInfo()
839 * \sa SDL_CreateRenderer() 839 * \sa SDL_CreateRenderer()
840 */ 840 */
841 extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void); 841 extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
842 842
843 /** 843 /**
844 * \fn int SDL_GetRendererInfo(int index, SDL_RendererInfo *info) 844 * \fn int SDL_GetRenderDriverInfo(int index, SDL_RendererInfo *info)
845 * 845 *
846 * \brief Get information about a specific render manager on the current 846 * \brief Get information about a specific 2D rendering driver for the current display.
847 * display. 847 *
848 * 848 * \param index The index of the driver to query information about.
849 * \param index The index to query information about, or -1 to query the currently renderer 849 * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the rendering driver.
850 * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the renderer
851 * 850 *
852 * \return 0 on success, -1 if the index was out of range 851 * \return 0 on success, -1 if the index was out of range
853 * 852 *
854 * \sa SDL_CreateRenderer() 853 * \sa SDL_CreateRenderer()
855 */ 854 */
856 extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index, 855 extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
857 SDL_RendererInfo * info); 856 SDL_RendererInfo * info);
858 857
859 /** 858 /**
860 * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags) 859 * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
861 * 860 *
862 * \brief Create and make active a 2D rendering context for a window. 861 * \brief Create and make active a 2D rendering context for a window.
863 * 862 *
864 * \param windowID The window used for rendering 863 * \param windowID The window used for rendering
865 * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags. 864 * \param index The index of the rendering driver to initialize, or -1 to initialize the first one supporting the requested flags.
866 * \param flags SDL_RendererFlags 865 * \param flags SDL_RendererFlags
867 * 866 *
868 * \return 0 on success, -1 if the flags were not supported, or -2 if 867 * \return 0 on success, -1 if the flags were not supported, or -2 if
869 * there isn't enough memory to support the requested flags 868 * there isn't enough memory to support the requested flags
870 * 869 *
871 * \sa SDL_SelectRenderer() 870 * \sa SDL_SelectRenderer()
871 * \sa SDL_GetRendererInfo()
872 * \sa SDL_DestroyRenderer() 872 * \sa SDL_DestroyRenderer()
873 */ 873 */
874 extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID, 874 extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
875 int index, Uint32 flags); 875 int index, Uint32 flags);
876 876
881 * 881 *
882 * \return 0 on success, -1 if the selected window doesn't have a 882 * \return 0 on success, -1 if the selected window doesn't have a
883 * rendering context. 883 * rendering context.
884 */ 884 */
885 extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID); 885 extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
886
887 /**
888 * \fn int SDL_GetRendererInfo(SDL_RendererInfo *info)
889 *
890 * \brief Get information about the current rendering context.
891 */
892 extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_RendererInfo * info);
886 893
887 /** 894 /**
888 * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h) 895 * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
889 * 896 *
890 * \brief Create a texture for the current rendering context. 897 * \brief Create a texture for the current rendering context.
892 * \param format The format of the texture 899 * \param format The format of the texture
893 * \param access One of the enumerated values in SDL_TextureAccess 900 * \param access One of the enumerated values in SDL_TextureAccess
894 * \param w The width of the texture in pixels 901 * \param w The width of the texture in pixels
895 * \param h The height of the texture in pixels 902 * \param h The height of the texture in pixels
896 * 903 *
897 * \return The created texture is returned, or 0 if no render manager was active, the format was unsupported, or the width or height were out of range. 904 * \return The created texture is returned, or 0 if no rendering context was active, the format was unsupported, or the width or height were out of range.
898 * 905 *
899 * \sa SDL_QueryTexture() 906 * \sa SDL_QueryTexture()
900 * \sa SDL_DestroyTexture() 907 * \sa SDL_DestroyTexture()
901 */ 908 */
902 extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format, 909 extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
910 * 917 *
911 * \param format The format of the texture, or 0 to pick an appropriate format 918 * \param format The format of the texture, or 0 to pick an appropriate format
912 * \param access One of the enumerated values in SDL_TextureAccess 919 * \param access One of the enumerated values in SDL_TextureAccess
913 * \param surface The surface containing pixel data used to fill the texture 920 * \param surface The surface containing pixel data used to fill the texture
914 * 921 *
915 * \return The created texture is returned, or 0 if no render manager was active, the format was unsupported, or the surface width or height were out of range. 922 * \return The created texture is returned, or 0 if no rendering context was active, the format was unsupported, or the surface width or height were out of range.
916 * 923 *
917 * \note The surface is not modified or freed by this function. 924 * \note The surface is not modified or freed by this function.
918 * 925 *
919 * \sa SDL_QueryTexture() 926 * \sa SDL_QueryTexture()
920 * \sa SDL_DestroyTexture() 927 * \sa SDL_DestroyTexture()
1059 * \brief Fill the current rendering target with the specified color. 1066 * \brief Fill the current rendering target with the specified color.
1060 * 1067 *
1061 * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target. 1068 * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
1062 * \param color An ARGB color value. 1069 * \param color An ARGB color value.
1063 * 1070 *
1064 * \return 0 on success, or -1 if there is no renderer current 1071 * \return 0 on success, or -1 if there is no rendering context current
1065 */ 1072 */
1066 extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect, 1073 extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect,
1067 Uint32 color); 1074 Uint32 color);
1068 1075
1069 /** 1076 /**
1075 * \param srcrect A pointer to the source rectangle, or NULL for the entire texture. 1082 * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
1076 * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target. 1083 * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
1077 * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel. 1084 * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
1078 * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height. 1085 * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
1079 * 1086 *
1080 * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation. 1087 * \return 0 on success, or -1 if there is no rendering context current, or the driver doesn't support the requested operation.
1081 * 1088 *
1082 * \note You can check the video driver info to see what operations are supported. 1089 * \note You can check the video driver info to see what operations are supported.
1083 */ 1090 */
1084 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID, 1091 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
1085 const SDL_Rect * srcrect, 1092 const SDL_Rect * srcrect,