This is part 2 in a series on using SDL. See part 1 if you missed it. This post introduces more useful functions, structures, and constants in the SDL 2.0 API. It covers basic details such as return values and parameters of functions and names and data types of members of structs. For more detailed info, visit the links in the references.

Rendering

Call the SDL_CreateRenderer() function to create a renderer in which you can render objects such as rectangles in a window.^[1] The window should have already been initialized. See part 1 to review how to create an SDL_Window instance.

SDL_Renderer *SDL_CreateRenderer(SDL_Window *window,
int index, Uint32 flags);

Returns: if successful, a valid rendering context; on error, NULL

window is an SDL_Window instance where the renderer will be displayed.
index is the index of the rendering driver to initialize, or -1 to initialize the first one supporting the requested flags.
flags is 0, or one or more SDL_RendererFlags OR’d together. Possible values for flags:

• SDL_RENDERER_SOFTWARE: the renderer is a software fallback
• SDL_RENDERER_ACCELERATED: the renderer uses hardware acceleration
• SDL_RENDERER_PRESENTVSYNC: present is synchronized with the refresh rate
• SDL_RENDERER_TARGETTEXTURE: the renderer supports rendering to texture

You will likely want to render to a texture, which is created with SDL_CreateTexture().^[2]

SDL_Texture *SDL_CreateTexture(SDL_Renderer *renderer,
                                Uint32 format,
                                int access, int w,
                                int h);

Returns: a pointer to the created texture or NULL if no rendering context was active, the format was unsupported, or the width or height were out of range

• renderer is the rendering context.
• format is one of the enumerated values in SDL_PixelFormatEnum.
• access is one of the enumerated values in SDL_TextureAccess, which are
  • SDL_TEXTUREACCESS_STATIC: changes rarely, not lockable
  • SDL_TEXTUREACCESS_STREAMING: changes frequently, lockable
  • SDL_TEXTUREACCESS_TARGET: can be used as a render target
• w is the width of the texture in pixels.
• h is the height of the texture in pixels.

Use SDL_SetRenderTarget() is set a texture as the target of a renderer.^[3]

int SDL_SetRenderTarget(SDL_Renderer *renderer,
                        SDL_Texture *texture);

Returns: 0 on success or a negative error code on failure

renderer is the rendering context.
texture is the targeted texture, which must be created with the SDL_TEXTUREACCESS_TARGET flag, or NULL to render to the window instead of a texture.

To set the color used when rendering, use SDL_SetRenderDrawColor().^[4]

int SDL_SetRenderDrawColor(SDL_Renderer *renderer,
                   Uint8 r, Uint8 g, Uint8 b,
                   Uint8 a);

Returns: 0 on success or a negative error code on failure

renderer is the rendering context.
r, g, and b are the red, green, and blues value used to draw on the rendering target, respectively. These should be a value between 0 and 255, inclusive.
a is the alpha value (opacity) used to draw on the rendering target. This should be a value between 0 and 255, inclusive. Use SDL_ALPHA_OPAQUE or 255 to specify opaque. If you want to have a transparent object, use SDL_SetRenderDrawBlendMode().

Use SDL_RenderClear()^[5] to color the entire rendering target with the color previously set with SDL_SetRenderDrawColor().

int SDL_RenderClear(SDL_Renderer *renderer);

Returns: 0 on success or a negative error code on failure

renderer is the rendering context.

Use SDL_RenderFillRect() to render a filled rectangle with no outline.^[6]

int SDL_RenderFillRect(SDL_Renderer *renderer,
                       const SDL_Rect *rect);

Returns: 0 on success or a negative error code on failure

renderer is the rendering context.
rect is the SDL_Rect structure representing the rectangle to fill, or NULL for the entire rendering target.

[7]
typedef struct SDL_Rect
{
    int x, y;
    int w, h;
} SDL_Rect;

x and y are the x and y values of the rectangle’s upper left corner.
w and h are the width and height of the rectangle, respectively.

Use SDL_RenderDrawRect() to draw the outline of a rectangle.^[8] Its arguments are identical to the arguments for SDL_RenderFillRect().

int SDL_RenderDrawRect(SDL_Renderer *renderer,
                       const SDL_Rect *rect);

Returns: 0 on success or a negative error code on failure

To destroy a renderer for a window and free associated textures, use SDL_DestroyRenderer().^[9]

void SDL_DestroyRenderer(SDL_Renderer *renderer);

renderer is the rendering context to destroy.

References

1. https://wiki.libsdl.org/SDL_CreateRenderer
2. https://wiki.libsdl.org/SDL_CreateTexture
3. https://wiki.libsdl.org/SDL_SetRenderTarget
4. https://wiki.libsdl.org/SDL_SetRenderDrawColor
5. https://wiki.libsdl.org/SDL_RenderClear
6. https://wiki.libsdl.org/SDL_RenderFillRect
7. https://wiki.libsdl.org/SDL_Rect
8. https://wiki.libsdl.org/SDL_RenderDrawRect
9. https://wiki.libsdl.org/SDL_DestroyRenderer