Clarified the difference between render drivers and render contexts
authorSam Lantinga <slouken@libsdl.org>
Sun, 06 Aug 2006 00:09:04 +0000
changeset 19695d3724f64f2b
parent 1968 9f589a1f74a5
child 1970 db3ba6c0d0df
Clarified the difference between render drivers and render contexts
include/SDL_video.h
src/SDL_compat.c
src/video/SDL_video.c
src/video/cocoa/SDL_cocoamodes.m
test/common.c
     1.1 --- a/include/SDL_video.h	Sat Aug 05 22:41:33 2006 +0000
     1.2 +++ b/include/SDL_video.h	Sun Aug 06 00:09:04 2006 +0000
     1.3 @@ -166,7 +166,7 @@
     1.4  /**
     1.5   * \enum SDL_RendererFlags
     1.6   *
     1.7 - * \brief Flags used when initializing a render manager.
     1.8 + * \brief Flags used when creating a rendering context
     1.9   */
    1.10  typedef enum
    1.11  {
    1.12 @@ -182,7 +182,7 @@
    1.13  /**
    1.14   * \struct SDL_RendererInfo
    1.15   *
    1.16 - * \brief Information on the capabilities of a render manager.
    1.17 + * \brief Information on the capabilities of a render driver or context
    1.18   */
    1.19  typedef struct SDL_RendererInfo
    1.20  {
    1.21 @@ -827,34 +827,33 @@
    1.22  extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
    1.23  
    1.24  /**
    1.25 - * \fn int SDL_GetNumRenderers(void)
    1.26 + * \fn int SDL_GetNumRenderDrivers(void)
    1.27   *
    1.28 - * \brief Get the number of render managers on the current display.
    1.29 + * \brief Get the number of 2D rendering drivers available for the current display.
    1.30   *
    1.31 - * A render manager is a set of code that handles rendering and texture
    1.32 + * A render driver is a set of code that handles rendering and texture
    1.33   * management on a particular display.  Normally there is only one, but
    1.34   * some drivers may have several available with different capabilities.
    1.35   *
    1.36 - * \sa SDL_GetRendererInfo()
    1.37 + * \sa SDL_GetRenderDriverInfo()
    1.38   * \sa SDL_CreateRenderer()
    1.39   */
    1.40 -extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void);
    1.41 +extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
    1.42  
    1.43  /**
    1.44 - * \fn int SDL_GetRendererInfo(int index, SDL_RendererInfo *info)
    1.45 + * \fn int SDL_GetRenderDriverInfo(int index, SDL_RendererInfo *info)
    1.46   *
    1.47 - * \brief Get information about a specific render manager on the current
    1.48 - *        display.
    1.49 + * \brief Get information about a specific 2D rendering driver for the current display.
    1.50   *
    1.51 - * \param index The index to query information about, or -1 to query the currently renderer
    1.52 - * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the renderer
    1.53 + * \param index The index of the driver to query information about.
    1.54 + * \param info A pointer to an SDL_RendererInfo struct to be filled with information on the rendering driver.
    1.55   *
    1.56   * \return 0 on success, -1 if the index was out of range
    1.57   *
    1.58   * \sa SDL_CreateRenderer()
    1.59   */
    1.60 -extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index,
    1.61 -                                                SDL_RendererInfo * info);
    1.62 +extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
    1.63 +                                                    SDL_RendererInfo * info);
    1.64  
    1.65  /**
    1.66   * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
    1.67 @@ -862,13 +861,14 @@
    1.68   * \brief Create and make active a 2D rendering context for a window.
    1.69   *
    1.70   * \param windowID The window used for rendering
    1.71 - * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags.
    1.72 + * \param index The index of the rendering driver to initialize, or -1 to initialize the first one supporting the requested flags.
    1.73   * \param flags SDL_RendererFlags
    1.74   *
    1.75   * \return 0 on success, -1 if the flags were not supported, or -2 if
    1.76   *         there isn't enough memory to support the requested flags
    1.77   *
    1.78   * \sa SDL_SelectRenderer()
    1.79 + * \sa SDL_GetRendererInfo()
    1.80   * \sa SDL_DestroyRenderer()
    1.81   */
    1.82  extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
    1.83 @@ -885,6 +885,13 @@
    1.84  extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
    1.85  
    1.86  /**
    1.87 + * \fn int SDL_GetRendererInfo(SDL_RendererInfo *info)
    1.88 + *
    1.89 + * \brief Get information about the current rendering context.
    1.90 + */
    1.91 +extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_RendererInfo * info);
    1.92 +
    1.93 +/**
    1.94   * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
    1.95   *
    1.96   * \brief Create a texture for the current rendering context.
    1.97 @@ -894,7 +901,7 @@
    1.98   * \param w The width of the texture in pixels
    1.99   * \param h The height of the texture in pixels
   1.100   *
   1.101 - * \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.
   1.102 + * \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.
   1.103   *
   1.104   * \sa SDL_QueryTexture()
   1.105   * \sa SDL_DestroyTexture()
   1.106 @@ -912,7 +919,7 @@
   1.107   * \param access One of the enumerated values in SDL_TextureAccess
   1.108   * \param surface The surface containing pixel data used to fill the texture
   1.109   *
   1.110 - * \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.
   1.111 + * \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.
   1.112   *
   1.113   * \note The surface is not modified or freed by this function.
   1.114   *
   1.115 @@ -1061,7 +1068,7 @@
   1.116   * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
   1.117   * \param color An ARGB color value.
   1.118   *
   1.119 - * \return 0 on success, or -1 if there is no renderer current
   1.120 + * \return 0 on success, or -1 if there is no rendering context current
   1.121   */
   1.122  extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect,
   1.123                                             Uint32 color);
   1.124 @@ -1077,7 +1084,7 @@
   1.125   * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
   1.126   * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
   1.127   *
   1.128 - * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation.
   1.129 + * \return 0 on success, or -1 if there is no rendering context current, or the driver doesn't support the requested operation.
   1.130   *
   1.131   * \note You can check the video driver info to see what operations are supported.
   1.132   */
     2.1 --- a/src/SDL_compat.c	Sat Aug 05 22:41:33 2006 +0000
     2.2 +++ b/src/SDL_compat.c	Sun Aug 06 00:09:04 2006 +0000
     2.3 @@ -467,7 +467,7 @@
     2.4           SDL_RENDERER_SINGLEBUFFER | SDL_RENDERER_PRESENTDISCARD) < 0) {
     2.5          return NULL;
     2.6      }
     2.7 -    SDL_GetRendererInfo(-1, &SDL_VideoRendererInfo);
     2.8 +    SDL_GetRenderDriverInfo(-1, &SDL_VideoRendererInfo);
     2.9  
    2.10      /* Create a texture for the screen surface */
    2.11      SDL_VideoTexture =
     3.1 --- a/src/video/SDL_video.c	Sat Aug 05 22:41:33 2006 +0000
     3.2 +++ b/src/video/SDL_video.c	Sun Aug 06 00:09:04 2006 +0000
     3.3 @@ -1362,7 +1362,7 @@
     3.4  }
     3.5  
     3.6  int
     3.7 -SDL_GetNumRenderers(void)
     3.8 +SDL_GetNumRenderDrivers(void)
     3.9  {
    3.10      if (_this) {
    3.11          return SDL_CurrentDisplay.num_render_drivers;
    3.12 @@ -1371,27 +1371,19 @@
    3.13  }
    3.14  
    3.15  int
    3.16 -SDL_GetRendererInfo(int index, SDL_RendererInfo * info)
    3.17 +SDL_GetRenderDriverInfo(int index, SDL_RendererInfo * info)
    3.18  {
    3.19      if (!_this) {
    3.20          SDL_UninitializedVideo();
    3.21          return -1;
    3.22      }
    3.23  
    3.24 -    if (index >= SDL_GetNumRenderers()) {
    3.25 +    if (index < 0 || index >= SDL_GetNumRenderDrivers()) {
    3.26          SDL_SetError("index must be in the range of 0 - %d",
    3.27 -                     SDL_GetNumRenderers() - 1);
    3.28 +                     SDL_GetNumRenderDrivers() - 1);
    3.29          return -1;
    3.30      }
    3.31 -    if (index < 0) {
    3.32 -        if (!SDL_CurrentDisplay.current_renderer) {
    3.33 -            SDL_SetError("There is no current renderer");
    3.34 -            return -1;
    3.35 -        }
    3.36 -        *info = SDL_CurrentDisplay.current_renderer->info;
    3.37 -    } else {
    3.38 -        *info = SDL_CurrentDisplay.render_drivers[index].info;
    3.39 -    }
    3.40 +    *info = SDL_CurrentDisplay.render_drivers[index].info;
    3.41      return 0;
    3.42  }
    3.43  
    3.44 @@ -1406,7 +1398,7 @@
    3.45  
    3.46      if (index < 0) {
    3.47          const char *override = SDL_getenv("SDL_VIDEO_RENDERER");
    3.48 -        int n = SDL_GetNumRenderers();
    3.49 +        int n = SDL_GetNumRenderDrivers();
    3.50          for (index = 0; index < n; ++index) {
    3.51              SDL_RenderDriver *driver =
    3.52                  &SDL_CurrentDisplay.render_drivers[index];
    3.53 @@ -1427,9 +1419,9 @@
    3.54          }
    3.55      }
    3.56  
    3.57 -    if (index >= SDL_GetNumRenderers()) {
    3.58 +    if (index >= SDL_GetNumRenderDrivers()) {
    3.59          SDL_SetError("index must be -1 or in the range of 0 - %d",
    3.60 -                     SDL_GetNumRenderers() - 1);
    3.61 +                     SDL_GetNumRenderDrivers() - 1);
    3.62          return -1;
    3.63      }
    3.64  
    3.65 @@ -1464,6 +1456,22 @@
    3.66      return 0;
    3.67  }
    3.68  
    3.69 +int
    3.70 +SDL_GetRendererInfo(SDL_RendererInfo * info)
    3.71 +{
    3.72 +    if (!_this) {
    3.73 +        SDL_UninitializedVideo();
    3.74 +        return -1;
    3.75 +    }
    3.76 +
    3.77 +    if (!SDL_CurrentDisplay.current_renderer) {
    3.78 +        SDL_SetError("There is no current renderer");
    3.79 +        return -1;
    3.80 +    }
    3.81 +    *info = SDL_CurrentDisplay.current_renderer->info;
    3.82 +    return 0;
    3.83 +}
    3.84 +
    3.85  SDL_TextureID
    3.86  SDL_CreateTexture(Uint32 format, int access, int w, int h)
    3.87  {
     4.1 --- a/src/video/cocoa/SDL_cocoamodes.m	Sat Aug 05 22:41:33 2006 +0000
     4.2 +++ b/src/video/cocoa/SDL_cocoamodes.m	Sun Aug 06 00:09:04 2006 +0000
     4.3 @@ -94,16 +94,16 @@
     4.4      number = CFDictionaryGetValue(moderef, kCGDisplayRefreshRate);
     4.5      CFNumberGetValue(number, kCFNumberLongType, &refreshRate);
     4.6  
     4.7 -    mode->format = SDL_PixelFormat_Unknown;
     4.8 +    mode->format = SDL_PIXELFORMAT_UNKNOWN;
     4.9      switch (bpp) {
    4.10      case 8:
    4.11 -        mode->format = SDL_PixelFormat_Index8;
    4.12 +        mode->format = SDL_PIXELFORMAT_INDEX8;
    4.13          break;
    4.14      case 16:
    4.15 -        mode->format = SDL_PixelFormat_RGB555;
    4.16 +        mode->format = SDL_PIXELFORMAT_RGB555;
    4.17          break;
    4.18      case 32:
    4.19 -        mode->format = SDL_PixelFormat_RGB888;
    4.20 +        mode->format = SDL_PIXELFORMAT_RGB888;
    4.21          break;
    4.22      }
    4.23      mode->w = width;
     5.1 --- a/test/common.c	Sat Aug 05 22:41:33 2006 +0000
     5.2 +++ b/test/common.c	Sun Aug 06 00:09:04 2006 +0000
     5.3 @@ -603,13 +603,13 @@
     5.4          if (state->verbose & VERBOSE_RENDER) {
     5.5              SDL_RendererInfo info;
     5.6  
     5.7 -            n = SDL_GetNumRenderers();
     5.8 +            n = SDL_GetNumRenderDrivers();
     5.9              if (n == 0) {
    5.10                  fprintf(stderr, "No built-in render drivers\n");
    5.11              } else {
    5.12                  fprintf(stderr, "Built-in render drivers:\n");
    5.13                  for (i = 0; i < n; ++i) {
    5.14 -                    SDL_GetRendererInfo(i, &info);
    5.15 +                    SDL_GetRenderDriverInfo(i, &info);
    5.16                      PrintRenderer(&info);
    5.17                  }
    5.18              }
    5.19 @@ -666,9 +666,9 @@
    5.20                  m = -1;
    5.21                  if (state->renderdriver) {
    5.22                      SDL_RendererInfo info;
    5.23 -                    n = SDL_GetNumRenderers();
    5.24 +                    n = SDL_GetNumRenderDrivers();
    5.25                      for (j = 0; j < n; ++j) {
    5.26 -                        SDL_GetRendererInfo(j, &info);
    5.27 +                        SDL_GetRenderDriverInfo(j, &info);
    5.28                          if (SDL_strcasecmp(info.name, state->renderdriver) ==
    5.29                              0) {
    5.30                              m = j;
    5.31 @@ -692,7 +692,7 @@
    5.32                      SDL_RendererInfo info;
    5.33  
    5.34                      fprintf(stderr, "Current renderer:\n");
    5.35 -                    SDL_GetRendererInfo(-1, &info);
    5.36 +                    SDL_GetRendererInfo(&info);
    5.37                      PrintRenderer(&info);
    5.38                  }
    5.39              }