Canvas widget

When calling gui.draw(), all (visible) widgets are drawn at once. If you wish to manually render something inbetween TGUI widgets (e.g. to the background of a child window) then you can either create a custom widget or simply make use of one of the Canvas widgets. The canvas acts as a render target: you first render your contents to the canvas and then when TGUI draws its widgets, it will draw the contents of the canvas widget to the screen.

If the contents is static then the canvas can be rendered to only once, you don’t have to redraw it each frame. Note however that resizing the canvas widget will leave its contents in an undefined state, so you must redraw its contents if you resize the widget.

The canvas widget is specific to the backend renderer. Its header file is automatically included when including the backend.

CanvasSFML

The CanvasSFML widget is only available when using the SFML_GRAPHICS backend.

Creating the canvas is like creating any other widget. It’s size can be provided to the create function for convenience:

auto canvas = tgui::CanvasSFML::create({400, 300});
gui.add(canvas);

Before rendering, you should always clear the contents:

canvas->clear(tgui::Color::Black);

The canvas provides the same draw functions as sf::RenderTarget, so you can call draw to render SFML objects:

sf::Text text;
sf::Sprite sprite;
canvas->draw(text);
canvas->draw(sprite);

After rendering, you must always call the display() function to indicate that rendering has finished:

canvas->display();

CanvasSDL

The CanvasSDL widget is only available when using the SDL_RENDERER backend.

Creating the canvas is like creating any other widget. It’s size can be provided to the create function for convenience:

auto canvas = tgui::CanvasSDL::create({400, 300});
gui.add(canvas);

Before rendering, you must tell SDL that further commands should render to the canvas instead of the window:

SDL_SetRenderTarget(renderer, canvas->getTextureTarget());

Afterwards you can draw just like you would normally draw on the window:

SDL_Texture* imgTexture;
SDL_RenderClear(renderer);
SDL_RenderCopy(renderer, imgTexture, NULL, NULL);

After rendering, you must always tell SDL to stop rendering on the canvas:

SDL_SetRenderTarget(renderer, nullptr);

CanvasOpenGL3

The CanvasOpenGL3 widget is only available when using a backend that uses the OpenGL3 renderer (i.e. SFML_OPENGL3, SDL_OPENGL3, SDL_TTF_OPENGL3 or GLFW_OPENGL3 backends).

Creating the canvas is like creating any other widget. It’s size can be provided to the create function for convenience:

auto canvas = tgui::CanvasOpenGL3::create({400, 300});
gui.add(canvas);

Before rendering, you must tell OpenGL that further commands should render to the canvas instead of the window.

canvas->bindFramebuffer();

You may also want to call glViewport(0, 0, canvas->getSize().x, canvas->getSize().y); to scale rendering to the canvas size instead of the window size.

Afterwards you can draw just like you would normally draw on the window:

glClear(GL_COLOR_BUFFER_BIT);

After rendering, you must always tell OpenGL to stop rendering on the canvas:

glBindFramebuffer(GL_FRAMEBUFFER, 0);

CanvasGLES2

The CanvasGLES2 widget is only available when using a backend that uses the GLES2 renderer (i.e. SFML_GLES2, SDL_GLES2, SDL_TTF_GLES2 or GLFW_GLES2 backends).

Creating the canvas is like creating any other widget. It’s size can be provided to the create function for convenience:

auto canvas = tgui::CanvasGLES2::create({400, 300});
gui.add(canvas);

Before rendering, you must tell OpenGL ES that further commands should render to the canvas instead of the window.

canvas->bindFramebuffer();

You may also want to call glViewport(0, 0, canvas->getSize().x, canvas->getSize().y); to scale rendering to the canvas size instead of the window size.

Afterwards you can draw just like you would normally draw on the window:

glClear(GL_COLOR_BUFFER_BIT);

After rendering, you must always tell OpenGL ES to stop rendering on the canvas:

glBindFramebuffer(GL_FRAMEBUFFER, 0);