render: Added SDL_RenderFlush().

1 files changed, 25 insertions, 0 deletions

diff --git a/include/SDL_render.h b/include/SDL_render.h
index d33619297..850e908ec 100644
--- a/include/SDL_render.h
+++ b/include/SDL_render.h
@@ -876,6 +876,31 @@ extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture);
  */
 extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
 
+/**
+ *  \brief Force the rendering context to flush any pending commands to the
+ *         underlying rendering API.
+ *
+ *  You do not need to (and in fact, shouldn't) call this function unless
+ *  you are planning to call into OpenGL/Direct3D/Metal/whatever directly
+ *  in addition to using an SDL_Renderer.
+ *
+ *  This is for a very-specific case: if you are using SDL's render API,
+ *  you asked for a specific renderer backend (OpenGL, Direct3D, etc),
+ *  you set SDL_HINT_RENDER_BATCHING to "1", and you plan to make
+ *  OpenGL/D3D/whatever calls in addition to SDL render API calls. If all of
+ *  this applies, you should call SDL_RenderFlush() between calls to SDL's
+ *  render API and the low-level API you're using in cooperation.
+ *
+ *  In all other cases, you can ignore this function. This is only here to
+ *  get maximum performance out of a specific situation. In all other cases,
+ *  SDL will do the right thing, perhaps at a performance loss.
+ *
+ *  This function is first available in SDL 2.0.10, and is not needed in
+ *  2.0.9 and earlier, as earlier versions did not queue rendering commands
+ *  at all, instead flushing them to the OS immediately.
+ */
+extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer);
+
 
 /**
  *  \brief Bind the texture to the current OpenGL/ES/ES2 context for use with