Clarified the difference between render drivers and render contexts

--HG--
extra : convert_revision : svn%3Ac70aab31-4412-0410-b14c-859654838e24/trunk%402016

include/SDL_video.h

@@ -166,7 +166,7 @@ typedef enum
 /**
  * \enum SDL_RendererFlags
  *
- * \brief Flags used when initializing a render manager.
+ * \brief Flags used when creating a rendering context
  */
 typedef enum
 {
@@ -182,7 +182,7 @@ typedef enum
 /**
  * \struct SDL_RendererInfo
  *
- * \brief Information on the capabilities of a render manager.
+ * \brief Information on the capabilities of a render driver or context
  */
 typedef struct SDL_RendererInfo
 {
@@ -827,34 +827,33 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_WindowID windowID,
 extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
 
 /**
- * \fn int SDL_GetNumRenderers(void)
+ * \fn int SDL_GetNumRenderDrivers(void)
  *
- * \brief Get the number of render managers on the current display.
+ * \brief Get the number of 2D rendering drivers available for the current display.
  *
- * A render manager is a set of code that handles rendering and texture
+ * A render driver is a set of code that handles rendering and texture
  * management on a particular display.  Normally there is only one, but
  * some drivers may have several available with different capabilities.
  *
- * \sa SDL_GetRendererInfo()
+ * \sa SDL_GetRenderDriverInfo()
  * \sa SDL_CreateRenderer()
  */
-extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void);
+extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
 
 /**
- * \fn int SDL_GetRendererInfo(int index, SDL_RendererInfo *info)
+ * \fn int SDL_GetRenderDriverInfo(int index, SDL_RendererInfo *info)
  *
- * \brief Get information about a specific render manager on the current
- *        display.
+ * \brief Get information about a specific 2D rendering driver for the current display.
  *
- * \param index The index to query information about, or -1 to query the currently renderer
- * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the renderer
+ * \param index The index of the driver to query information about.
+ * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the rendering driver.
  *
  * \return 0 on success, -1 if the index was out of range
  *
  * \sa SDL_CreateRenderer()
  */
-extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index,
-                                                SDL_RendererInfo * info);
+extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
+                                                    SDL_RendererInfo * info);
 
 /**
  * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
@@ -862,13 +861,14 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index,
  * \brief Create and make active a 2D rendering context for a window.
  *
  * \param windowID The window used for rendering
- * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags.
+ * \param index The index of the rendering driver to initialize, or -1 to initialize the first one supporting the requested flags.
  * \param flags SDL_RendererFlags
  *
  * \return 0 on success, -1 if the flags were not supported, or -2 if
  *         there isn't enough memory to support the requested flags
  *
  * \sa SDL_SelectRenderer()
+ * \sa SDL_GetRendererInfo()
  * \sa SDL_DestroyRenderer()
  */
 extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
@@ -884,6 +884,13 @@ extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
  */
 extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
 
+/**
+ * \fn int SDL_GetRendererInfo(SDL_RendererInfo *info)
+ *
+ * \brief Get information about the current rendering context.
+ */
+extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_RendererInfo * info);
+
 /**
  * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
  *
@@ -894,7 +901,7 @@ extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
  * \param w The width of the texture in pixels
  * \param h The height of the texture in pixels
  *
- * \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.
+ * \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.
  *
  * \sa SDL_QueryTexture()
  * \sa SDL_DestroyTexture()
@@ -912,7 +919,7 @@ extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
  * \param access One of the enumerated values in SDL_TextureAccess
  * \param surface The surface containing pixel data used to fill the texture
  *
- * \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.
+ * \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.
  *
  * \note The surface is not modified or freed by this function.
  *
@@ -1061,7 +1068,7 @@ extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
  * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
  * \param color An ARGB color value.
  *
- * \return 0 on success, or -1 if there is no renderer current
+ * \return 0 on success, or -1 if there is no rendering context current
  */
 extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect,
                                            Uint32 color);
@@ -1077,7 +1084,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect,
  * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
  * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
  *
- * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation.
+ * \return 0 on success, or -1 if there is no rendering context current, or the driver doesn't support the requested operation.
  *
  * \note You can check the video driver info to see what operations are supported.
  */

src/SDL_compat.c

@@ -467,7 +467,7 @@ SDL_SetVideoMode(int width, int height, int bpp, Uint32 flags)
          SDL_RENDERER_SINGLEBUFFER | SDL_RENDERER_PRESENTDISCARD) < 0) {
         return NULL;
     }
-    SDL_GetRendererInfo(-1, &SDL_VideoRendererInfo);
+    SDL_GetRenderDriverInfo(-1, &SDL_VideoRendererInfo);
 
     /* Create a texture for the screen surface */
     SDL_VideoTexture =

src/video/SDL_video.c

@@ -1362,7 +1362,7 @@ SDL_AddRenderDriver(int displayIndex, const SDL_RenderDriver * driver)
 }
 
 int
-SDL_GetNumRenderers(void)
+SDL_GetNumRenderDrivers(void)
 {
     if (_this) {
         return SDL_CurrentDisplay.num_render_drivers;
@@ -1371,27 +1371,19 @@ SDL_GetNumRenderers(void)
 }
 
 int
-SDL_GetRendererInfo(int index, SDL_RendererInfo * info)
+SDL_GetRenderDriverInfo(int index, SDL_RendererInfo * info)
 {
     if (!_this) {
         SDL_UninitializedVideo();
         return -1;
     }
 
-    if (index >= SDL_GetNumRenderers()) {
+    if (index < 0 || index >= SDL_GetNumRenderDrivers()) {
         SDL_SetError("index must be in the range of 0 - %d",
-                     SDL_GetNumRenderers() - 1);
+                     SDL_GetNumRenderDrivers() - 1);
         return -1;
     }
-    if (index < 0) {
-        if (!SDL_CurrentDisplay.current_renderer) {
-            SDL_SetError("There is no current renderer");
-            return -1;
-        }
-        *info = SDL_CurrentDisplay.current_renderer->info;
-    } else {
-        *info = SDL_CurrentDisplay.render_drivers[index].info;
-    }
+    *info = SDL_CurrentDisplay.render_drivers[index].info;
     return 0;
 }
 
@@ -1406,7 +1398,7 @@ SDL_CreateRenderer(SDL_WindowID windowID, int index, Uint32 flags)
 
     if (index < 0) {
         const char *override = SDL_getenv("SDL_VIDEO_RENDERER");
-        int n = SDL_GetNumRenderers();
+        int n = SDL_GetNumRenderDrivers();
         for (index = 0; index < n; ++index) {
             SDL_RenderDriver *driver =
                 &SDL_CurrentDisplay.render_drivers[index];
@@ -1427,9 +1419,9 @@ SDL_CreateRenderer(SDL_WindowID windowID, int index, Uint32 flags)
         }
     }
 
-    if (index >= SDL_GetNumRenderers()) {
+    if (index >= SDL_GetNumRenderDrivers()) {
         SDL_SetError("index must be -1 or in the range of 0 - %d",
-                     SDL_GetNumRenderers() - 1);
+                     SDL_GetNumRenderDrivers() - 1);
         return -1;
     }
 
@@ -1464,6 +1456,22 @@ SDL_SelectRenderer(SDL_WindowID windowID)
     return 0;
 }
 
+int
+SDL_GetRendererInfo(SDL_RendererInfo * info)
+{
+    if (!_this) {
+        SDL_UninitializedVideo();
+        return -1;
+    }
+
+    if (!SDL_CurrentDisplay.current_renderer) {
+        SDL_SetError("There is no current renderer");
+        return -1;
+    }
+    *info = SDL_CurrentDisplay.current_renderer->info;
+    return 0;
+}
+
 SDL_TextureID
 SDL_CreateTexture(Uint32 format, int access, int w, int h)
 {

src/video/cocoa/SDL_cocoamodes.m

@@ -94,16 +94,16 @@ GetDisplayMode(CFDictionaryRef moderef, SDL_DisplayMode *mode)
     number = CFDictionaryGetValue(moderef, kCGDisplayRefreshRate);
     CFNumberGetValue(number, kCFNumberLongType, &refreshRate);
 
-    mode->format = SDL_PixelFormat_Unknown;
+    mode->format = SDL_PIXELFORMAT_UNKNOWN;
     switch (bpp) {
     case 8:
-        mode->format = SDL_PixelFormat_Index8;
+        mode->format = SDL_PIXELFORMAT_INDEX8;
         break;
     case 16:
-        mode->format = SDL_PixelFormat_RGB555;
+        mode->format = SDL_PIXELFORMAT_RGB555;
         break;
     case 32:
-        mode->format = SDL_PixelFormat_RGB888;
+        mode->format = SDL_PIXELFORMAT_RGB888;
         break;
     }
     mode->w = width;

test/common.c

@@ -603,13 +603,13 @@ CommonInit(CommonState * state)
         if (state->verbose & VERBOSE_RENDER) {
             SDL_RendererInfo info;
 
-            n = SDL_GetNumRenderers();
+            n = SDL_GetNumRenderDrivers();
             if (n == 0) {
                 fprintf(stderr, "No built-in render drivers\n");
             } else {
                 fprintf(stderr, "Built-in render drivers:\n");
                 for (i = 0; i < n; ++i) {
-                    SDL_GetRendererInfo(i, &info);
+                    SDL_GetRenderDriverInfo(i, &info);
                     PrintRenderer(&info);
                 }
             }
@@ -666,9 +666,9 @@ CommonInit(CommonState * state)
                 m = -1;
                 if (state->renderdriver) {
                     SDL_RendererInfo info;
-                    n = SDL_GetNumRenderers();
+                    n = SDL_GetNumRenderDrivers();
                     for (j = 0; j < n; ++j) {
-                        SDL_GetRendererInfo(j, &info);
+                        SDL_GetRenderDriverInfo(j, &info);
                         if (SDL_strcasecmp(info.name, state->renderdriver) ==
                             0) {
                             m = j;
@@ -692,7 +692,7 @@ CommonInit(CommonState * state)
                     SDL_RendererInfo info;
 
                     fprintf(stderr, "Current renderer:\n");
-                    SDL_GetRendererInfo(-1, &info);
+                    SDL_GetRendererInfo(&info);
                     PrintRenderer(&info);
                 }
             }