Put a picture in your game
This page puts a picture into the game from Get the starter project
and makes it follow the greeting around the window. It goes through every file that changes:
the picture itself, the manifest that lists it, the build file that copies it, a small class
that draws it, and the lines in HelloState that use that class. It takes about 15 minutes.
Before you start:
- Do Make a first change, so that you know the edit, build and run loop and have a copy of your game to go back to. Make a fresh copy now with that page’s step 1 line.
- Install the content tools, which puts
texconv.exeinC:\dev\tools.
Every command runs in the x64 Native Tools Command Prompt, in your project’s folder:
cd /d C:\dev\mygame-
Get a picture. This page uses a PNG file named
hero.pnginC:\dev\mygame. If you have no picture yet, this line draws one, an orange face 64 pixels across:Terminal window powershell -NoProfile -Command "Add-Type -AssemblyName System.Drawing; $b = New-Object Drawing.Bitmap 64,64; $g = [Drawing.Graphics]::FromImage($b); $g.SmoothingMode = 'AntiAlias'; $g.FillEllipse([Drawing.Brushes]::Orange, 2, 2, 60, 60); $g.FillEllipse([Drawing.Brushes]::Black, 18, 20, 8, 12); $g.FillEllipse([Drawing.Brushes]::Black, 38, 20, 8, 12); $b.Save('hero.png'); $g.Dispose(); $b.Dispose()"It is one line. It prints nothing and takes about a second. To use your own picture instead, copy it into the project’s folder with the name
hero.png, for example from your Pictures folder:Terminal window copy /y "%USERPROFILE%\Pictures\my picture.png" hero.pngChange
my picture.pngto your file’s name before you press Enter. It prints1 file(s) copied./yreplaces ahero.pngthat is already there, such as the face from the line above, without asking; without it,copyasksOverwrite hero.png? (Yes/No/All):, and typing y and Enter does the same. If it printsThe system cannot find the file specified., the picture is not where the line looked. On a computer that backs up to OneDrive, the Pictures folder is%USERPROFILE%\OneDrive\Pictures. Or, in File Explorer, right-click the picture, choose Copy as path, and paste that in place of the first quoted path, quotation marks included.Paint can make one too: draw, then save it as
hero.pnginC:\dev\mygame, choosing PNG as the type. Keep it small to start with, a few hundred pixels across at most, because it is drawn at its own size in a window 1280 pixels wide.A JPG, such as a photo from a phone, works too. Step 2’s
texconvline reads a JPG as it is, withhero.jpgin place ofhero.png; the Or keep it a PNG box under step 2 needs a PNG. Paint turns any picture into one: open it, choose File > Save as > PNG picture, and save it ashero.pnginC:\dev\mygame. A picture that is too big shrinks the same way: in Paint, press Ctrl+W, choose Pixels, type the width you want with Maintain aspect ratio ticked, click OK, and save. -
Convert it to a texture. Make the folder the game’s pictures live in, then convert:
Terminal window mkdir game\content\texturesC:\dev\tools\texconv.exe -f R8G8B8A8_UNORM -m 1 -pmalpha --ignore-srgb -y -o game\content\textures hero.pngOutput Microsoft (R) DirectX Texture Converter [DirectXTex] Version 2026.5.8.1Copyright (C) Microsoft Corp.reading hero.png (64x64 B8G8R8A8_UNORM 2D) as (64x64 R8G8B8A8_UNORM 2D a:PM)writing game\content\textures\hero.ddsThe two numbers after
reading hero.png (are its width and height in pixels,64x64here. The game reads these dimensions from the loaded texture in step 5.This wrote
game\content\textures\hero.dds. What the options do:Option Why it is there -f R8G8B8A8_UNORMStores 8 bits each of red, green, blue and transparency, a format the engine reads. Without it the engine refuses the file. -m 1One copy of the picture at full size, rather than extra smaller copies the starter game does not use. -pmalphaPrepares the transparent edges the way the engine blends them. Without it, soft edges show a light fringe. --ignore-srgbKeeps the colours as they are in the PNG. Without it, colours between full and none come out darker. -yReplaces hero.ddsif it is already there, so you can run the line again after changing the picture.-o game\content\texturesThe folder to write to. It must already exist, which is what the mkdirline is for.mkdirsaysA subdirectory or file game\content\textures already exists.if you run it again, which is harmless. -
List it in the manifest. The manifest lists the pictures, fonts and sounds the engine loads for the game when it starts. Open it:
Terminal window notepad game\content\manifest.jsonPress Ctrl+A to select everything in it, then paste this in its place, save and close Notepad. If you have already done Fonts and text in your game, take the second tab’s version, which keeps that page’s two extra fonts. If you have done Play a sound in your game, preserve its
wavegroup. The XWB bank route needs itssound_bankgroup instead. Neither version below includes these groups; add yours back or the bank lookup fails at startup.game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16"]},{"kind": "texture","directory": "./textures/","names": ["hero"]}]}game\content\manifest.json {"assets": [{"kind": "font","directory": "./fonts/","names": ["jetbrains_mono_bold_16","jetbrains_mono_bold_32","menu_bold_16"]},{"kind": "texture","directory": "./textures/","names": ["hero"]}]}The first group is the font the starter already had. The second is new: a group of kind
texture, read from thetexturesfolder, holding one picture calledhero. The name is the file’s name without.dds. To add a second picture later, add its name to that list, with a comma between names:"hero", "tree". -
Copy the textures folder beside the game. The game reads its content from the folder its
.exeis in, and the build copies it there. The starter’s build copies only the manifest and the fonts, so it needs a block fortextures, and two more lines go in for later. The three changes below are in the order they come in the file, from the top. Open the build file:Terminal window notepad game\CMakeLists.txtFirst, search with Ctrl+F for
jetbrains_mono_bold_16.spritefont, near the top in the part for the browser build, and add a line after it, so the two read:"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts/jetbrains_mono_bold_16.spritefont""${CMAKE_CURRENT_SOURCE_DIR}/content/textures/hero.dds"That makes the browser build package the page again when
hero.ddschanges. It does not change the Windows game you build on this page.Next, search for
content/fonts"(with the quotation mark). You are in the block that copies the fonts:add_custom_command(TARGET game_content POST_BUILDCOMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different"${CMAKE_CURRENT_SOURCE_DIR}/content/fonts""$<TARGET_FILE_DIR:MyGame>/fonts"VERBATIM)Click at the end of its last line,
), press Enter, and paste the same block fortexturesbelow it:add_custom_command(TARGET game_content POST_BUILDCOMMAND "${CMAKE_COMMAND}" -E copy_directory_if_different"${CMAKE_CURRENT_SOURCE_DIR}/content/textures""$<TARGET_FILE_DIR:MyGame>/textures"VERBATIM)Last, search for
install(DIRECTORY content/fontsand add a line after it, so the two read:install(DIRECTORY content/fonts DESTINATION .)install(DIRECTORY content/textures DESTINATION .)That puts the pictures in a Windows release. Save and close Notepad.
-
Make the class that draws a picture. Every object in the starter’s scene is a class with three jobs:
updatemoves it on each step of the game, 60 times a second,drawdraws it, andboundssays where it is. This one draws a whole texture at its own size. First make the empty file, then open it:Terminal window if not exist game\states\picture.h type nul > game\states\picture.hnotepad game\states\picture.hThe first line makes an empty file and prints nothing; it leaves the file alone if it is already there. Notepad opens the empty file. Paste all of this into it, then save and close Notepad:
game\states\picture.h #pragma once#include "engine/core/game_object.h"#include "engine/math/rectanglef.h"#include "engine/math/rectanglei.h"#include "engine/math/vector2f.h"#include "engine/math/vector2i.h"#include "engine/render/colour.h"#include "engine/render/render_resources.h"#include "engine/render/renderer.h"#include <string>// A picture from the manifest, drawn whole, at its own size, with its// top-left corner at a position.{public:Picture(const std::string& texture_name,texture_(resources.resolve_texture(texture_name)),size_(resources.texture_size(this->texture_)), position_(position){}void set_position(const labrador::Vector2F& position){this->position_ = position;}void update(float /*dt*/) override{}{draw_list.draw_sprite(this->texture_,}{return labrador::RectangleF(this->position_.x, this->position_.y,static_cast<float>(this->size_.x),static_cast<float>(this->size_.y));}private:labrador::TextureHandle texture_;labrador::Vector2F position_;};The whole class is in this one
.hfile, sogame\CMakeLists.txtdoes not need to list it. The constructor looks the picture’s name up once, when the game starts, and keeps the answer, a texture handle.texture_sizereads its width and height in texels; the class keeps those too, so changing the picture’s dimensions needs no C++ edit.drawpassesdraw_spritethe part of the texture to draw (all of it, from its top-left corner0, 0), where on screen to draw it (bounds()), a colour to tint it with (white leaves it as it is), and no rotation, origin, flip or layer. -
Put a picture in the scene. Open the header of the state that runs the starter’s screen:
Terminal window notepad game\states\hello_state.hSearch for
game/rules/motion.hand add a line after it, so the two read:#include "game/rules/motion.h"#include "game/states/picture.h"Then search for
hint_ = nullptr;and add a line after it, so the two read:Picture* picture_ = nullptr;picture_is whereHelloStatekeeps the picture, so that it can move it later. Save and close Notepad, then open the state’s code:Terminal window notepad game\states\hello_state.cppSearch for
this->hint_ = this->scene_->add(. This is the line, ininit(), that adds the controls hint at the bottom of the window:samples/minimal/states/hello_state.cpp L"Left stick, arrows or WASD move it. B or Escape asks to quit. Touch shows a marker.", font_name,samples/minimal/states/hello_state.cpp, lines 90–93 at
f525bc6Click at the start of that line and paste these lines above it, with an empty line after them:
this->picture_ = this->scene_->add(std::make_unique<Picture>("hero"is the name in the manifest. Its dimensions come from the loaded texture.Vector2F(100.0f, 100.0f)is where its top-left corner starts, 100 pixels from the window’s left edge and 100 down from its top. -
Make it follow the greeting. In the same file, search for
this->greeting_->set_position(. This line, inupdate(), moves the greeting on every frame:samples/minimal/states/hello_state.cpp this->greeting_->set_position(greeting_position(this->motion_));Click at the end of that line, after the
;, press Enter, and paste these lines:this->picture_->set_position(greeting_position(this->motion_) +They put the picture 80 pixels left of the greeting and 24 pixels higher, so that the 64-pixel face sits beside the text and moves with it. For a wider picture, use its width plus 16 in place of the 80, such as
-216.0ffor one 200 pixels wide; otherwise it covers the greeting. Save and close Notepad. -
Build, test and run. Quit the game if it is open, then run the line from Make a first change’s step 5:
Terminal window cmake --build --preset x64-debug && ctest --preset x64-debug && out\build\x64-debug\game\MyGame.exeThe build first runs CMake again, because
game\CMakeLists.txtchanged. That prints[0/1] Re-running CMake...and about 30 lines from vcpkg and CMake, including a list of packages and package-lookup lines; they are expected, not errors. Then it compileshello_state.cppandmain.cpp, which include the files you changed. On a fast desktop the whole build took 14 seconds. It ends like this:Output -- Build files have been written to: C:/dev/mygame/out/build/x64-debug[1/6] Running utility command for game_content[2/6] Checking that no engine file includes a game header[3/6] Building CXX object game\CMakeFiles\MyGame.dir\states\hello_state.cpp.obj[4/6] Building CXX object game\CMakeFiles\MyGame.dir\main.cpp.obj[5/6] Linking CXX executable game\MyGame.exeTest project C:/dev/mygame/out/build/x64-debugStart 1: MyGameTests1/2 Test #1: MyGameTests ...................... Passed 0.02 secStart 2: MyGameSmokeTests2/2 Test #2: MyGameSmokeTests ................. Passed 0.83 sec100% tests passed, 0 tests failed out of 2Then the game opens.
The orange face, or your picture, is to the left of the greeting and moves with it when you press the arrow keys or WASD. Its corners are transparent: the black behind it shows through.
Changing the picture
Section titled “Changing the picture”To change the picture, change hero.png and run the texconv line from step 2 again, then the
build line from step 8. -y replaces the old hero.dds, and the build copies the new one beside
the game. If the new picture is a different size, change the 64, 64 in step 6 to its numbers.
To change from a .dds to a PNG or back, delete the old file both in game\content\textures and
beside the game, as the Or keep it a PNG box under step 2 shows: the build never removes the
old copy.
To leave the picture where it is instead of following the greeting, delete the two lines you
added in step 7. It then stays at the position in step 6. The window is 1280 pixels wide and
720 high, with 0, 0 at its top-left corner and the second number growing downwards.
To draw a second picture, convert it the same way with its own name, add the name to the
manifest’s texture group, and add a second Picture in init() with that name. To keep it in
a variable as well, add a second Picture* line in hello_state.h with another name, such as
tree_.
How errors show
Section titled “How errors show”A mistake in this page’s files shows in one of three places:
-
The build stops with an
errorline: a slip in the C++ code. Read a build error shows how to find the line that matters. If the error says'Picture': undeclared identifier, the#include "game/states/picture.h"line is missing fromhello_state.h. If it saysCannot open include file: 'game/states/picture.h', the file is not ingame\statesunder that name: check withdir game\states. -
The start-up test fails. The build worked, but the game stopped while loading. The
ctestoutput shows***FailedforMyGameSmokeTestsand, under it, a line startingstartup failure:that says why, and the game does not start:Output 2/2 Test #2: MyGameSmokeTests .................***Failed 0.24 secstartup failure: Texture 'heroo' was never loaded.50% tests passed, 1 tests failed out of 2Started on its own, the game shows the same reason in a box titled
Sample - startup failure, whatever your game is called, and closes when you click OK. -
texconvprintsFAILEDorERROR, and no newhero.ddsis written. Awritingline can come before theERRORline; theERRORstill means nothing was written.
Each message is below.
If something fails
Section titled “If something fails”The colours are darker than in the PNG. The texconv line was run without
--ignore-srgb. Without it, texconv treats a PNG’s colours as needing correction and darkens
the ones between full and none: an orange of red 255, green 165 became green 96. Run the line
from step 2 again and build.
The picture has a light fringe round its edges, or a box round it. The texconv line was
run without -pmalpha; see Colours and blending.
Only part of the picture shows, or its edges are stretched into stripes. The width and
height in step 6 do not match the picture’s. Numbers too small draw only its top-left part.
Numbers too large repeat its last column and row to fill the extra space, which shows as stripes
unless those edges are transparent. Use the numbers texconv printed in step 2.
Troubleshooting lists these messages too, with the others the engine can give about content.
In the browser build
Section titled “In the browser build”The browser build packs the whole game\content folder into the page when it links, so the
picture needs no copy line there. The line you added in step 4 after the .spritefont line makes
the page link again when hero.dds changes; without it, the page keeps the old picture until
something else changes. Each new content file the game loads needs a line like it.
Where to go next
Section titled “Where to go next”- Animate a sprite sheet draws several pictures from one file, and plays them one after another.
- Fonts and text in your game makes a bigger font for a title and reads text from a file.
- Sprites and text explains the files, formats and drawing in more depth.
What was checked
Section titled “What was checked”On 2026-10-30, in a starter project made from a starter ZIP of this tree at C:\dev\g5\mygame,
with Visual Studio 2026’s compiler 19.51 and the may2026 texconv, every step above ran as
shown, with C:\dev\g5\mygame in the quoted output changed to C:\dev\mygame, and the game drew the face beside the greeting, following it. Its pixels on screen had
the PNG’s colour, red 255 and green 165; the same picture converted without --ignore-srgb drew
green 96. Each message under If something fails was made on purpose: a
missing PNG, a misspelt output folder, no -y, no -f, a misspelt name in the manifest and in
the code, a misspelt folder and kind, a missing comma, and the copy block removed with the build
folder’s textures deleted. A copy of hero.png named hero.dds, and textures converted to
B8G8R8X8_UNORM, BC4_UNORM with -dx9 and B5G6R5_UNORM, gave the other messages the DX10
entry names. The Sample - startup failure box was seen with the misspelt name in
the code. The wasm-debug build compiled the page with these files, loaded it in Chrome without
errors, and linked it again after hero.dds changed. A second run of the same steps in a fresh
starter, by an agent making each edit exactly as the steps word it rather than in Notepad,
matched the output and the picture’s colour. A texture with seven levels from texconv
without -m 1, and a BC3_UNORM texture, also loaded. With 32, 32 in place of 64, 64 the
game drew the face’s top-left quarter; with 128, 128 it drew the face at its own size in the
corner of a larger, otherwise transparent rectangle, the face’s edges being transparent. The
x64-release build installed with cmake --install had textures in its folder, and the
installed game started and drew. The note in step 3 about Play a sound in your game was checked
in that page’s run: the starter’s manifest with that page’s sound code in place stopped the game with
SoundBank 'tones' was never loaded., and that page’s second manifest tab put the group back;
followed on this page’s manifest, the same tab gave valid JSON.
The Or keep it a PNG note under step 2 and the two-path message for a missing picture were
added on 4 November 2026, when the engine began reading PNG textures, and have not been followed
in a starter. The engine’s tests load a .png through the same path, refuse a texture with both
files and with neither, and check the colours a PNG decodes to.
The lines for deleting the old copy beside the game, the JPG and Paint notes in step 1 and
copy /y were added on 13 November 2026 after a review’s run in a v0.3.0 starter, where the
build folder kept hero.dds after the one in game\content\textures was deleted, and texconv
with this page’s options read a JPG photo. A .dds made from a JPG has not been loaded in the
game, and these notes have not been followed in a starter.
Documentation for Labrador v0.4.0. Built from Labrador f525bc6 of 2026-11-17.