Assets

Functions for loading, caching, and managing textures, fonts, and audio.

Header: #include <asw/modules/assets.h>
Namespace: asw::assets

Paths

get_path

std::string get_path(const std::string& filename);

Get the full path to an asset. Adds the base path of the application (the directory of the executable, or Contents/Resources/ in a macOS app bundle) before filename. If the base path is not available, returns filename unchanged.

All load_* functions use this function, so asset filenames are relative to the application base path, not to the working directory.

get_save_path

std::string get_save_path(const std::string& org, const std::string& app);

Get a writable folder for save files and settings, unique to the organization and application. The folder is created if it does not exist. The path ends in a path separator. Returns an empty string if the path cannot be found.

In web builds, files in this folder are lost when the page reloads. Use read_save and write_save for data that must stay.

read_save / write_save

std::string read_save(const std::string& org, const std::string& app, const std::string& name);
bool write_save(const std::string& org, const std::string& app, const std::string& name,
                const std::string& data);

Read and write save data, e.g. progress or settings as JSON. write_save replaces the data that was saved with the same name, and returns true if it was saved. read_save returns an empty string if nothing is saved.

Desktop builds keep the data in a file in get_save_path(org, app). Web builds keep it in the browser's localStorage, so it stays after the page reloads.

int runs = std::atoi(asw::assets::read_save("adsgames", "my_game", "runs.txt").c_str()) + 1;
asw::assets::write_save("adsgames", "my_game", "runs.txt", std::to_string(runs));

Textures

load_texture

asw::Texture load_texture(const std::string& filename);
asw::Texture load_texture(const std::string& filename, const std::string& key);

Load a texture from a file. Supported formats: PNG, ICO, CUR, BMP, GIF, JPG, LBM, PCX, PNM, TIF, XCF, XPM, XV, and WEBP. The second overload caches the result under key for later retrieval.

WARNING

Aborts the program if the file is not found.

get_texture

asw::Texture get_texture(const std::string& key);

Get a previously cached texture by key.

unload_texture

void unload_texture(const std::string& key);

Remove a cached texture.

create_texture

asw::Texture create_texture(int w, int h);

Create a blank texture with the given dimensions. Useful for render targets.

create_radial_gradient

asw::Texture create_radial_gradient(int size, asw::Color inner, asw::Color outer,
                                    asw::Falloff falloff = asw::Falloff::Smooth);

Create a square texture with a radial gradient. The color changes from inner at the center to outer at the edge and in the corners. The texture has linear scaling and a blend mode set. Useful for lights.

Parameter	Type	Description
size	int	The width and height of the texture
inner	asw::Color	The color at the center
outer	asw::Color	The color at the edge and in the corners
falloff	asw::Falloff	How the color changes from the center to the edge (default: Smooth). See Falloff

Fonts

load_font

asw::Font load_font(const std::string& filename,
                    float size,
                    asw::FontStyle style = asw::FontStyle::Smooth);
asw::Font load_font(const std::string& filename,
                    float size,
                    const std::string& key,
                    asw::FontStyle style = asw::FontStyle::Smooth);

Load a TTF font at the given size. The second overload caches the result under key. Use asw::FontStyle::Pixel for pixel art fonts, and asw::FontStyle::Smooth for regular fonts. See FontStyle.

WARNING

Aborts the program if the file is not found.

get_font

asw::Font get_font(const std::string& key);

Get a previously cached font by key.

unload_font

void unload_font(const std::string& key);

Remove a cached font.

Samples

load_sample

asw::Sample load_sample(const std::string& filename);
asw::Sample load_sample(const std::string& filename, const std::string& key);

Load a sound effect from a file. Supported formats: WAV, AIFF, RIFF, OGG, and VOC. The second overload caches the result under key.

WARNING

Aborts the program if the file is not found.

get_sample

asw::Sample get_sample(const std::string& key);

Get a previously cached sample by key.

unload_sample

void unload_sample(const std::string& key);

Remove a cached sample.

Music

load_music

asw::Music load_music(const std::string& filename);
asw::Music load_music(const std::string& filename, const std::string& key);

Load a music file. Supported formats: WAV, AIFF, RIFF, OGG, and VOC. The second overload caches the result under key.

WARNING

Aborts the program if the file is not found.

get_music

asw::Music get_music(const std::string& key);

Get previously cached music by key.

unload_music

void unload_music(const std::string& key);

Remove cached music.

Global

clear_all

void clear_all();

Clear all cached assets (textures, fonts, samples, and music).

Example

// Load without caching
auto texture = asw::assets::load_texture("sprites/player.png");

// Load with caching
asw::assets::load_texture("sprites/player.png", "player");
asw::assets::load_font("fonts/arial.ttf", 24.0f, "main_font");
asw::assets::load_font("fonts/pixel.ttf", 8.0f, "pixel_font", asw::FontStyle::Pixel);
asw::assets::load_sample("sfx/jump.wav", "jump");
asw::assets::load_music("music/theme.ogg", "bgm");

// Retrieve cached assets anywhere
auto player = asw::assets::get_texture("player");
auto font = asw::assets::get_font("main_font");

// Unload individual assets
asw::assets::unload_texture("player");

// Or clear everything
asw::assets::clear_all();

// Generated textures
auto light = asw::assets::create_radial_gradient(128, asw::Color(255, 220, 150, 255),
                                                 asw::Color(255, 220, 150, 0));

// Save files
std::string save_file = asw::assets::get_save_path("A.D.S. Games", "My Game") + "save.dat";