Jazz2::ContentResolver class

Manages loading of assets.

Process-wide singleton (see ContentResolver::Get) that locates and loads every kind of game asset — metadata, graphics, tile sets, levels, episodes, fonts, music and shaders — caching the results so repeated requests are cheap. It also owns the shared 256x256 palette texture and the palette pipeline: applying tileset and sprite palettes, building and reference-counting per-player recolor palettes from a packed fur color, and configuring the palette-aware sprite shaders. In headless mode it skips all GPU work.

Public types

class LoadingScope
Scope that marks a load, pairing BeginLoading() with EndLoading().
struct SpriteSheet
Sprite sheet of a graphics asset (.aura) as it's stored, see ReadSpriteSheet().

Public static functions

static auto Get() -> ContentResolver&
Returns static instance of main content resolver.
static auto ShiftHue(std::uint32_t color, float degrees) -> std::uint32_t
Rotates the hue of a packed 0xAABBGGRR color by degrees.
static auto HueShiftDegreesForGradient(std::int32_t gradientStart) -> float
Returns the hue rotation (degrees) for the gradient starting at gradientStart when FurHueShiftFlag is set.
static void ConfigurePaletteTextureChannels(Texture& texture)
Declares the channel order of a texture whose texels are palette entries.

Constructors, destructors, conversion operators

~ContentResolver()

Public functions

void Release()
Releases all cached assets.
auto GetWritablePath() const -> StringView
Returns the directory the content was found in, if it is writable, otherwise an empty view.
auto GetContentPath() const -> StringView
Returns path to "Content" directory.
auto GetUserContentPath() const -> StringView
Returns path to the user-accessible "Content" directory, or an empty view if there is none.
auto GetWritableContentPath(bool create) -> StringView
Returns path to the "Content" directory files can be saved into, or an empty view if there is none.
auto GetLevelPacksPath(bool create) -> String
Returns path to the directory of installed level packs, or an empty string if there is none.
auto GetLevelPacksCachePath() const -> String
Returns path to the converted level packs in the "Cache" directory.
auto FindContentFile(StringView path) const -> String
Returns full path to a file in the user "Content", "Content" or "Cache" directory.
auto GetCachePath() const -> StringView
Returns path to "Cache" directory.
auto GetSourcePath() const -> StringView
Returns path to "Source" directory.
auto IsHeadless() const -> bool
Returns true if the application is running in headless mode (i.e., without any display).
void SetHeadless(bool value)
Sets whether the application is running in headless mode.
auto IsContentPrebaked() const -> bool
Returns true if the "Content" directory was prepared ahead of time.
void OverridePaths(StringView contentPath, StringView sourcePath, StringView cachePath)
Overrides "Content", "Source" and "Cache" directories (used by the libretro core, which cannot rely on the working directory of the frontend process).
void RemountPaks()
Scans the user "Content", "Content" and "Cache" directories for .pak files and mounts them.
auto OpenContentFile(StringView path, std::int32_t bufferSize = 8192) -> std::unique_ptr<Stream>
Tries to find and open a file specified by the path.
auto OpenSourceFile(StringView path, std::int32_t bufferSize = 8192) -> std::unique_ptr<Stream>
Tries to open a file from the "Source" directory (case-insensitive).
void BeginLoading()
Marks beginning of the loading assets.
void EndLoading()
Marks end of the loading assets.
void OverridePathHandler(Function<String(StringView)>&& callback)
Overrides the default path handler.
void PreloadMetadataAsync(StringView path)
Preloads specified metadata and its linked assets to cache.
auto RequestMetadata(StringView path, bool forceIndexed = false) -> Metadata*
Loads specified metadata and its linked assets (cached).
void PinMetadata(Metadata* metadata, bool pinned)
Keeps a metadata loaded with everything it uses, even across loadings that don't request it.
auto AcquireWeaponImage(const WeaponImage& image) -> Metadata*
Makes an image of the weapons of a level available as metadata, until it's released again.
void ReleaseWeaponImage(StringView path)
Releases an image acquired by AcquireWeaponImage(), by the path of its metadata.
auto AcquireWeaponSound(const WeaponSound& sound) -> String
Makes a sound of the weapons of a level playable by its identifier while the level is loaded.
void ReleaseWeaponSound(StringView identifier)
Releases a sound acquired by AcquireWeaponSound(), by its identifier.
auto FindWeaponSound(StringView identifier) -> Resources::SoundResource*
Returns a sound of the weapons of a level acquired, by its identifier, nullptr if there's none.
void RetainLoadedResources()
Keeps everything loaded across the loadings that follow, until ReleaseLoadedResources().
void ReleaseLoadedResources()
Lets the resources go again after RetainLoadedResources(), they're released by the next loading that doesn't request them.
auto RequestGraphics(StringView path, std::uint16_t paletteOffset, bool keepIndexed = false) -> GenericGraphicResource*
Loads specified graphics asset (cached).
auto IsGraphicsCached(const GenericGraphicResource* graphics, StringView path, std::uint16_t paletteOffset, bool keepIndexed = false) const -> bool
Returns whether graphics RequestGraphics() gave are still loaded, EndLoading() frees them once nothing requested them.
auto FindGraphicsPath(const GenericGraphicResource* graphics) const -> String
Returns the path loaded graphics were requested by (see RequestGraphics()), or an empty string.
auto ResolveAnimation(Metadata& metadata, GraphicResource& animation) -> bool
Loads the graphics of a deferred animation entry and returns whether they are ready to be drawn.
void PreloadDeferredAnimations()
Reads deferred animations in ahead of their first use while the heap has room for them.
void BuildPlayerColorPalette(std::uint32_t furColor, PlayerType playerType, std::uint32_t* outPalette) const
Builds a 256-color palette for a player from a packed 4-byte fur color.
auto ApplyPlayerColorPalette(std::unique_ptr<Texture>& texture, std::uint32_t furColor, PlayerType playerType) -> Texture*
Builds/updates a standalone 256x1 palette texture for a player fur color and returns it.
auto GetPaletteTexture() -> Texture*
Returns the shared 256x256 palette texture, uploading any rows changed since the last call.
auto GetSpritePaletteRevision() const -> std::uint32_t
Returns a number that changes whenever the sprite palette (the first row of the palette texture) changes.
auto AcquirePaletteOffset(std::uint32_t furColor, PlayerType playerType) -> std::int32_t
Acquires a reference-counted palette offset for the given packed fur color.
auto AcquireShiftedPaletteOffset(std::uint8_t shift, bool premultiplied = false) -> std::int32_t
Acquires a reference-counted palette offset of the sprite palette shifted by shift entries.
auto AcquireSingleHuePaletteOffset(std::uint8_t gradientStart) -> std::int32_t
Acquires a reference-counted palette offset of the sprite palette in a single hue of it.
auto AcquireGemPaletteOffset(std::uint8_t gem) -> std::int32_t
Acquires a reference-counted palette offset of the sprite palette as a gem of the given color.
auto AcquireAlphaMapPaletteOffset(std::uint8_t color, bool premultiplied = false) -> std::int32_t
Acquires a reference-counted palette offset of a single color of the sprite palette, its opacity by the index.
void BuildLayerPalette(bool alphaMap, std::uint8_t param, std::uint32_t* outPalette) const
Fills 256 colors as the row of AcquireShiftedPaletteOffset() or, with alphaMap, of AcquireAlphaMapPaletteOffset() is, without taking a row.
auto AcquireDissolvePaletteOffset(std::uint8_t color, std::uint8_t density) -> std::int32_t
Acquires a reference-counted palette offset of a color of the sprite palette for indices below a density.
auto AcquireNeonGlowPaletteOffset(std::uint8_t channels) -> std::int32_t
Acquires a reference-counted palette offset of the brightness of the sprite palette in color channels.
auto AcquireColorKeyPaletteOffset(std::uint8_t index) -> std::int32_t
Acquires a palette offset of the sprite palette with one more transparent entry.
auto AcquireFixedPaletteOffset(const std::uint32_t* colors, bool premultiplied = false) -> std::int32_t
Acquires a palette offset of a row of its own colors.
auto GetGemColor(std::uint8_t gem, std::uint8_t index) const -> std::uint32_t
Returns entry index of the gradient of a gem as SPRITE::GEM of JJ2+ draws it.
void ReleasePaletteOffset(std::int32_t paletteOffset)
Releases one reference to a palette offset from AcquirePaletteOffset and the like.
auto ConfigureSpriteShader(RenderCommand& command, bool indexed) -> bool
Configures a manually-built render command for a (possibly indexed) sprite.
void BindSpritePalette(RenderCommand& command, const Texture& diffuse, bool indexed, std::uint16_t paletteOffset)
Binds the diffuse (and, when indexed, the palette) textures for a sprite render command.
auto RequestTileSet(StringView path, std::uint16_t captionTileId, bool applyPalette, const std::uint8_t* paletteRemapping = nullptr, const BitArray* usedTiles = nullptr, bool withDiffuse = true, const std::uint32_t* trueColorPalette = nullptr) -> std::unique_ptr<Tiles::TileSet>
Loads specified tile set and its palette.
auto RequestTileSet(Stream& s, StringView path, std::uint16_t captionTileId, bool applyPalette, const std::uint8_t* paletteRemapping = nullptr, const BitArray* usedTiles = nullptr, bool withDiffuse = true, const std::uint32_t* trueColorPalette = nullptr) -> std::unique_ptr<Tiles::TileSet>
Loads a tile set from a stream.
auto CreateBlankTileSet(std::uint16_t tileCount, bool indexed) -> std::unique_ptr<Tiles::TileSet>
Creates a tile set of transparent tiles without collision, palette-indexed if indexed, for images saved into them later.
auto OpenTileSetFile(StringView path) -> std::unique_ptr<Stream>
Opens the file of a tile set, found the same way as by RequestTileSet().
auto LevelExists(StringView levelName) -> bool
Returns true if specified level exists.
auto ResolveLevelName(StringView name) -> String
Returns the full name of a level that a server configuration or an admin command names.
auto TryLoadLevel(StringView path, const LevelLoadOptions& options, LevelDescriptor& descriptor) -> bool
Loads specified level into a level descriptor.
auto TryLoadLevel(Stream& s, StringView fullPath, const LevelLoadOptions& options, LevelDescriptor& descriptor) -> bool
Loads a level from a stream into a level descriptor.
auto TryGetNextLevelName(StringView path, String& nextLevel) -> bool
Reads only the name of the next level from a given level file, without loading the level.
void ApplyDefaultPalette()
Loads default (sprite) palette.
void SetSpritePalette(ArrayView<const std::uint32_t> palette)
Overrides the active sprite palette (row 0 of the shared palette).
void ApplyTileDiffuseOverride(Tiles::TileMap& tileMap, std::int32_t tileId, const std::uint8_t* indices)
Overrides the pixels of a tile of a tile map by palette indices of a level, 32 × 32 of them.
auto ApplyTileDiffuseOverrideRgba(Tiles::TileMap& tileMap, std::int32_t tileId, const std::uint8_t* rgba) -> bool
Overrides the pixels of a tile of a tile map by colors, 32 × 32 of them, 4 bytes RGBA each.
auto GetEpisode(StringView name, bool withImages = false) -> std::optional<Episode>
Returns specified episode by name.
auto GetEpisodeByPath(StringView path, bool withImages = false) -> std::optional<Episode>
Returns specified episode by full path.
auto GetMusic(StringView path) -> std::unique_ptr<AudioStreamPlayer>
Loads specified music.
auto GetFont(FontType fontType) -> UI::Font*
Returns specified font type.
auto GetShader(PrecompiledShader shader) -> Shader*
Returns specified precompiled shader.
void CompileShaders()
Precompiles all required shaders.
auto CompileLayerEffectShaders() -> bool
Compiles the shaders of the special tile layers, if they aren't compiled yet.
auto GetNoiseTexture() -> std::unique_ptr<Texture>
Returns a noise texture with random pixels.
auto ResolveSound(Resources::SoundResource& sound) -> bool
Loads the samples of sound if they are not loaded yet.
auto GetNativeSoundPath(StringView assetPath) const -> String
Returns the console's own copy of a sound sample (relative to Animations), or an empty string.
auto GetPalettes() const -> StaticArrayView<PaletteCount*ColorsPerPalette, const std::uint32_t>
Returns currently loaded set of palettes.
auto ReadSpriteSheet(StringView path, SpriteSheet& sheet, bool withPixels = true) -> bool
Reads a sprite sheet (.aura, relative to Animations) into memory without making a texture of it.

Constants

static std::uint32_t PixelSize constexpr
Pixel size in bytes.
static std::int32_t PaletteCount constexpr
Maximum number of palettes.
static std::int32_t ColorsPerPalette constexpr
Number of colors per palette.
static std::int32_t FirstDynamicPaletteRow constexpr
First shared-palette row available for dynamic per-player allocation.
static std::int32_t InvalidValue constexpr
Invalid value.

Player recolor palette sections

static std::int32_t FurSectionCount constexpr
Number of recolorable fur sections.
static std::int32_t FurSectionSize constexpr
Number of consecutive palette indices per fur section block.
static std::int32_t FurSectionMaxBlocks constexpr
Maximum number of destination blocks a single fur section can recolor.
static std::uint8_t FurHueShiftFlag constexpr
High bit of a fur section byte requesting its gradient be hue-shifted by HueShiftDegreesForGradient.

Function documentation

static std::uint32_t Jazz2::ContentResolver::ShiftHue(std::uint32_t color, float degrees)

Rotates the hue of a packed 0xAABBGGRR color by degrees.

Rotates in YIQ space, so the result keeps the original's perceived brightness (luma) and chroma - only the hue changes, and alpha is untouched. Used to derive the per-gradient hue-shifted fur variants.

static float Jazz2::ContentResolver::HueShiftDegreesForGradient(std::int32_t gradientStart)

Returns the hue rotation (degrees) for the gradient starting at gradientStart when FurHueShiftFlag is set.

Each selectable gradient gets its own angle, chosen so its hue-shifted twin lands where the base gradients are sparse (the sprite palette clusters into a warm wedge ~0-73° and a cool wedge ~207-335°, leaving green/cyan/indigo underrepresented). A single global angle would push ~2 of the cool gradients back onto hues that already exist; per-gradient angles spread all twins evenly. Returns 0 for the near-neutral gradients (and any unrecognized start), which barely change under rotation and so get no twin.

static void Jazz2::ContentResolver::ConfigurePaletteTextureChannels(Texture& texture)

Declares the channel order of a texture whose texels are palette entries.

A palette entry is a std::uint32_t VALUE with red in the lowest byte, and such an array is uploaded by reinterpreting it as bytes - which is R,G,B,A only on a little-endian host. Any texture filled that way has to say so, so that backends which SAMPLE it read the channels back correctly; see the definition for why the bytes are described rather than reordered. Public because the cinematics player builds its own palette the same way (UI::Cinematics).

StringView Jazz2::ContentResolver::GetWritablePath() const

Returns the directory the content was found in, if it is writable, otherwise an empty view.

Only the PlayStation 2 and the GameCube can answer anything but "no" here. Both run from a disc, where nothing can be written and settings have to go to a memory card, but both can equally be started from an SD card - in an MX4SIO adapter on the PlayStation 2, in an SD Gecko or an SD2SP2 adapter on the GameCube - and then the directory the game is reading from is also the best place on the console to write to. PreferencesCache prefers it over a memory card, which is what lets such a build save on a console with no memory card in it.

StringView Jazz2::ContentResolver::GetUserContentPath() const

Returns path to the user-accessible "Content" directory, or an empty view if there is none.

On the platforms where "Content" is a part of the read-only application package (Android, Apple, AppImage and installed Linux packages, UWP, Switch, Vita), custom content can be placed into another "Content" directory next to "Cache" instead (next to "Source" on iOS, because "Cache" isn't reachable there). It's searched before everything else, so it can also replace any shipped file. Only assets streamed from a multiplayer server take precedence over it. The view is empty if the directory didn't exist at startup or if it's the packaged one.

StringView Jazz2::ContentResolver::GetWritableContentPath(bool create)

Returns path to the "Content" directory files can be saved into, or an empty view if there is none.

It's the user "Content" directory where the platform has one (see GetUserContentPath()) — with create it's created if it doesn't exist yet and searched from then on — and the "Content" directory itself elsewhere if it's writable, as it is in a portable copy of the game. The level editor saves levels and tile sets there. Nothing can be saved on the web, a file is downloaded instead.

String Jazz2::ContentResolver::GetLevelPacksPath(bool create)

Returns path to the directory of installed level packs, or an empty string if there is none.

The original files of the packs are kept there, in "LevelPacks" of the directory returned by GetWritableContentPath(), so they survive a rebuild of the cache.

String Jazz2::ContentResolver::GetLevelPacksCachePath() const

Returns path to the converted level packs in the "Cache" directory.

Levels of a pack are named with a + prefix, e.g. +1234/battle1, and they're looked up only here, in Episodes/+1234/battle1.j2l. Tile sets and other files of the packs are searched here last.

String Jazz2::ContentResolver::FindContentFile(StringView path) const

Returns full path to a file in the user "Content", "Content" or "Cache" directory.

The directories are searched in this order, path is relative to them. Returns an empty string if the file wasn't found in any of them. Files in mounted .pak files aren't considered. Levels and episodes of level packs are found only in GetLevelPacksCachePath().

bool Jazz2::ContentResolver::IsContentPrebaked() const

Returns true if the "Content" directory was prepared ahead of time.

Such a tree is created by AssetPacker and already contains everything the first-run conversion would produce, so the game has nothing to convert, never looks for the original game files and leaves the "Cache" directory alone. It is recognized by the package the tool names Compatibility::AssetConverter::PrebakedPackage.

std::unique_ptr<Stream> Jazz2::ContentResolver::OpenSourceFile(StringView path, std::int32_t bufferSize = 8192)

Tries to open a file from the "Source" directory (case-insensitive).

Used for original/custom game files. The returned stream is invalid if the file wasn't found.

Metadata* Jazz2::ContentResolver::RequestMetadata(StringView path, bool forceIndexed = false)

Loads specified metadata and its linked assets (cached).

Parameters
path Relative path to the metadata asset
forceIndexed Load all linked graphics as indexed (palette not baked) so they can be recolored at draw time - used for the player so each player can have a custom color scheme

void Jazz2::ContentResolver::PinMetadata(Metadata* metadata, bool pinned)

Keeps a metadata loaded with everything it uses, even across loadings that don't request it.

Everything not requested while something is loaded is released at the end of it (see BeginLoading()). The level editor keeps the sprites of its previews this way while it loads a level to play it. Pins are counted, the metadata stays pinned until it was unpinned as many times as it was pinned.

Metadata* Jazz2::ContentResolver::AcquireWeaponImage(const WeaponImage& image)

Makes an image of the weapons of a level available as metadata, until it's released again.

Its path is WeaponsDescription::GetImageMetadataPath(), with a single animation of the default state. Two levels that have the same image share it, it's released when both released it (see PinMetadata()).

String Jazz2::ContentResolver::AcquireWeaponSound(const WeaponSound& sound)

Makes a sound of the weapons of a level playable by its identifier while the level is loaded.

Returns the identifier (see WeaponsDescription::GetSoundIdentifier()), any actor plays it as a sound of its own by it (see FindWeaponSound()). As images, two levels that have the same sound share it. A dedicated server and a build without audio only know the identifier, so it's still sent to the clients.

void Jazz2::ContentResolver::RetainLoadedResources()

Keeps everything loaded across the loadings that follow, until ReleaseLoadedResources().

Nothing is released at the end of a loading while any is held, also what was loaded since, see BeginLoading(). Calls are counted, each is paired with ReleaseLoadedResources(). The level editor keeps the level played this way while it loads the level it shows, or another one to play.

GenericGraphicResource* Jazz2::ContentResolver::RequestGraphics(StringView path, std::uint16_t paletteOffset, bool keepIndexed = false)

Loads specified graphics asset (cached).

Parameters
path Relative path to the graphics asset
paletteOffset Index of the first palette color used to bake the sprite (ignored when keepIndexed)
keepIndexed Keep raw palette indices in the texture (don't bake the palette) for shader recoloring

bool Jazz2::ContentResolver::IsGraphicsCached(const GenericGraphicResource* graphics, StringView path, std::uint16_t paletteOffset, bool keepIndexed = false) const

Returns whether graphics RequestGraphics() gave are still loaded, EndLoading() frees them once nothing requested them.

The graphics aren't touched, so it can be asked of graphics that may be gone already. The arguments are those of RequestGraphics() (the palette offset of graphics kept indexed doesn't matter).

String Jazz2::ContentResolver::FindGraphicsPath(const GenericGraphicResource* graphics) const

Returns the path loaded graphics were requested by (see RequestGraphics()), or an empty string.

The separators are those of the platform. Every loaded graphics is looked at, so it's for a caller that keeps what it found.

bool Jazz2::ContentResolver::ResolveAnimation(Metadata& metadata, GraphicResource& animation)

Loads the graphics of a deferred animation entry and returns whether they are ready to be drawn.

Called by Metadata::FindAnimation() the first time a deferred animation (see Deferred animations) is looked up — there is no reason to call it directly. An entry whose graphics cannot be loaded is marked so that the attempt is not repeated on the next lookup.

void Jazz2::ContentResolver::PreloadDeferredAnimations()

Reads deferred animations in ahead of their first use while the heap has room for them.

Called once a level has finished loading, from behind its loading screen. Only the platforms that defer animations do anything here; see the implementation for what gets read and when it stops.

void Jazz2::ContentResolver::BuildPlayerColorPalette(std::uint32_t furColor, PlayerType playerType, std::uint32_t* outPalette) const

Builds a 256-color palette for a player from a packed 4-byte fur color.

Each byte is one section: a gradient start index in the sprite palette (0 = keep the original colors). The destination blocks recolored by each section depend on playerType (see How a player's 4-byte fur color maps to recolored palette sections).

Texture* Jazz2::ContentResolver::ApplyPlayerColorPalette(std::unique_ptr<Texture>& texture, std::uint32_t furColor, PlayerType playerType)

Builds/updates a standalone 256x1 palette texture for a player fur color and returns it.

texture is created on first use. Used for off-screen previews (e.g., the profile menu); in-game recoloring uses AcquirePaletteOffset instead. The recolored blocks depend on playerType (see How a player's 4-byte fur color maps to recolored palette sections). Returns nullptr in headless mode.

Texture* Jazz2::ContentResolver::GetPaletteTexture()

Returns the shared 256x256 palette texture, uploading any rows changed since the last call.

Row 0 is the sprite palette, rows 1-2 the gems, rows FirstDynamicPaletteRow+ the dynamically allocated per-player palettes. Bound to texture unit 1 for palette shaders. Returns nullptr in headless mode. Indexed sprites that must keep their original colors sample row 0 (the default palette) via a palette offset of 0.

std::int32_t Jazz2::ContentResolver::AcquirePaletteOffset(std::uint32_t furColor, PlayerType playerType)

Acquires a reference-counted palette offset for the given packed fur color.

The offset is the flat offset into the shared palette texture, passed to ActorBase::ActorRenderer::SetPalette and the palette-aware shaders. Callers with the same fur color and recolor scheme (GetFurSchemeIndex, derived from playerType) share one palette (so e.g., many corpses of the same character cost a single row); the recolored palette is built on first use. Returns the offset, or -1 if none are free. Release it with ReleasePaletteOffset when the holder disconnects/despawns.

std::int32_t Jazz2::ContentResolver::AcquireShiftedPaletteOffset(std::uint8_t shift, bool premultiplied = false)

Acquires a reference-counted palette offset of the sprite palette shifted by shift entries.

Index i of the row is the color of index (i + shift) & 255 of the sprite palette, index 0 stays the transparent one, and a pixel moved onto index 0 gets its color fully opaque, as SPRITE::PALSHIFT of JJ2+ draws it (see Tiles::LayerRendererType::PaletteShift). The row is built again whenever the sprite palette changes. Callers with the same shift share one row. Returns 0 (the sprite palette itself) for a shift of 0 (unless premultiplied), otherwise the offset, or -1 if no row is free. Release it with ReleasePaletteOffset. With premultiplied the colors of the row are premultiplied by their alpha, as a layer that is screened or multiplied is drawn through (see Tiles::LayerBlend), a row of its own.

std::int32_t Jazz2::ContentResolver::AcquireSingleHuePaletteOffset(std::uint8_t gradientStart)

Acquires a reference-counted palette offset of the sprite palette in a single hue of it.

Index i of the row is the color of index gradientStart + (i & 7) of the sprite palette, the gradient of 8 entries from gradientStart in place of the one of each index, as SPRITE::SINGLEHUE of JJ2+ draws it. Index 0 stays the transparent one. The row is built again whenever the sprite palette changes. Callers with the same gradientStart share one row. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset.

std::int32_t Jazz2::ContentResolver::AcquireGemPaletteOffset(std::uint8_t gem)

Acquires a reference-counted palette offset of the sprite palette as a gem of the given color.

Index i of the row is entry i & 127 of the gradient of the gem (see GetGemColor()), as SPRITE::GEM of JJ2+ draws it - its translucency is up to the caller. Index 0 stays the transparent one. The row is built again whenever the sprite palette changes. Callers with the same gem share one row. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset.

std::int32_t Jazz2::ContentResolver::AcquireAlphaMapPaletteOffset(std::uint8_t color, bool premultiplied = false)

Acquires a reference-counted palette offset of a single color of the sprite palette, its opacity by the index.

Index i of the row is the color of index color of the sprite palette with the alpha of i, as SPRITE::ALPHAMAP of JJ2+ draws it. The row is built again whenever the sprite palette changes. Callers with the same color share one row. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset. With premultiplied the colors of the row are premultiplied by their alpha, as a layer that is screened or multiplied is drawn through (see Tiles::LayerBlend), a row of its own.

std::int32_t Jazz2::ContentResolver::AcquireDissolvePaletteOffset(std::uint8_t color, std::uint8_t density)

Acquires a reference-counted palette offset of a color of the sprite palette for indices below a density.

Index i of the row is the color of index color of the sprite palette if i is less than density, transparent otherwise, so a texture of noise drawn through it shows as many pixels as SPRITE::BLEND_DISSOLVE of JJ2+. The row is built again whenever the sprite palette changes. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset.

std::int32_t Jazz2::ContentResolver::AcquireNeonGlowPaletteOffset(std::uint8_t channels)

Acquires a reference-counted palette offset of the brightness of the sprite palette in color channels.

Index i of the row is a half of the brightness JJ2 has for index i of the sprite palette in the channels that channels picks (0 red, 1 green, 2 blue, 3 red and blue, 4 red and green, 5 green and blue, others all three), black in the others, so drawn additively it's SPRITE::NEONGLOW of JJ2+. The row is built again whenever the sprite palette changes. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset.

std::int32_t Jazz2::ContentResolver::AcquireColorKeyPaletteOffset(std::uint8_t index)

Acquires a palette offset of the sprite palette with one more transparent entry.

The entry index is transparent, as swinging vines of the original game are drawn (index 128 is their background). The row is built again whenever the sprite palette changes. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset.

std::int32_t Jazz2::ContentResolver::AcquireFixedPaletteOffset(const std::uint32_t* colors, bool premultiplied = false)

Acquires a palette offset of a row of its own colors.

The row is the 256 colors of colors (packed as 0xAABBGGRR) with index 0 transparent, and it stays so whatever happens to the sprite palette, e.g. an additional palette of a level (see Tiles::LayerRendererType::PaletteMapping). Each call takes a row of its own. Returns the offset, or -1 if no row is free. Release it with ReleasePaletteOffset. With premultiplied the colors of the row are premultiplied by their alpha, as a layer that is screened or multiplied is drawn through (see Tiles::LayerBlend).

std::uint32_t Jazz2::ContentResolver::GetGemColor(std::uint8_t gem, std::uint8_t index) const

Returns entry index of the gradient of a gem as SPRITE::GEM of JJ2+ draws it.

Gems 0 to 3 are the red, green, blue and purple gems of the game (the gradients the gems are drawn with), up to 12 are the other gradients JJ2+ shows for them, the others have none (returns a transparent color). Only the lower 7 bits of index are used. The color is packed as 0xAABBGGRR.

void Jazz2::ContentResolver::ReleasePaletteOffset(std::int32_t paletteOffset)

Releases one reference to a palette offset from AcquirePaletteOffset and the like.

Also of AcquireShiftedPaletteOffset, AcquireSingleHuePaletteOffset and AcquireGemPaletteOffset. The underlying palette is returned to the pool only when the last holder releases it.

bool Jazz2::ContentResolver::ConfigureSpriteShader(RenderCommand& command, bool indexed)

Configures a manually-built render command for a (possibly indexed) sprite.

Selects the PrecompiledShader::PaletteRemap shader when indexed (recolored at draw time via the shared palette), else the plain Sprite program. When the shader changes it also reserves uniform memory, sets triangle-strip draw params, and points the diffuse/palette samplers at units 0/1. Returns whether the shader changed (use it to gate one-time per-command setup). For game-world graphics drawn outside the standard ActorRenderer.

void Jazz2::ContentResolver::BindSpritePalette(RenderCommand& command, const Texture& diffuse, bool indexed, std::uint16_t paletteOffset)

Binds the diffuse (and, when indexed, the palette) textures for a sprite render command.

Binds diffuse to texture unit 0 and, when indexed, the shared palette texture to unit 1 plus the per-instance palette offset (resolved through the command's cached instance uniforms). Call at draw time, after the other instance uniforms.

std::unique_ptr<Tiles::TileSet> Jazz2::ContentResolver::RequestTileSet(StringView path, std::uint16_t captionTileId, bool applyPalette, const std::uint8_t* paletteRemapping = nullptr, const BitArray* usedTiles = nullptr, bool withDiffuse = true, const std::uint32_t* trueColorPalette = nullptr)

Loads specified tile set and its palette.

Parameters
path Relative path to the tile set
captionTileId Tile used to render the level-preview caption thumbnail
applyPalette Apply the tile set's palette to the live sprite palette
paletteRemapping Optional 256-entry table remapping each tile's palette indices
usedTiles Optional per-tile bits selecting which tiles go into the diffuse atlas
withDiffuse If false, only the collision masks are loaded and the tile set has no textures — for a caller that requests it again once it knows which tiles to pack (see Tiles::TileMap::PruneTilesetAtlas())
trueColorPalette Optional 256 colors the 8-bit tiles are drawn in as true color tiles, so they don't follow the live palette (as jjTilesFromTileset32() of JJ2+)

std::unique_ptr<Tiles::TileSet> Jazz2::ContentResolver::RequestTileSet(Stream& s, StringView path, std::uint16_t captionTileId, bool applyPalette, const std::uint8_t* paletteRemapping = nullptr, const BitArray* usedTiles = nullptr, bool withDiffuse = true, const std::uint32_t* trueColorPalette = nullptr)

Loads a tile set from a stream.

The same as the overload above, for a tile set that isn't a file in Tilesets/ — the tile set editor hands over the one it edits this way. The path is what the tile set is known as.

std::unique_ptr<Stream> Jazz2::ContentResolver::OpenTileSetFile(StringView path)

Opens the file of a tile set, found the same way as by RequestTileSet().

For a caller that needs what the file stores rather than a tile set made of it, see Formats::TileSetFile. Returns nullptr if there is no such tile set.

String Jazz2::ContentResolver::ResolveLevelName(StringView name)

Returns the full name of a level that a server configuration or an admin command names.

A name without an episode (battle1) is a level of no episode, a name ending with a slash (prince/) is the first level of that episode. If there's no such episode, the name is returned as it is, so it can be reported.

bool Jazz2::ContentResolver::TryLoadLevel(StringView path, const LevelLoadOptions& options, LevelDescriptor& descriptor)

Loads specified level into a level descriptor.

The level is looked up as Episodes/<path>.j2l in the user content, the content and the cache, in that order.

bool Jazz2::ContentResolver::TryLoadLevel(Stream& s, StringView fullPath, const LevelLoadOptions& options, LevelDescriptor& descriptor)

Loads a level from a stream into a level descriptor.

The fullPath is what the level is known as, the level script is looked up next to it.

void Jazz2::ContentResolver::SetSpritePalette(ArrayView<const std::uint32_t> palette)

Overrides the active sprite palette (row 0 of the shared palette).

Takes up to ColorsPerPalette packed colors (0xAABBGGRR) and refreshes everything derived from it (gem gradients and per-player recolor rows), so the change takes effect on the next frame. No visible effect in headless mode.

void Jazz2::ContentResolver::ApplyTileDiffuseOverride(Tiles::TileMap& tileMap, std::int32_t tileId, const std::uint8_t* indices)

Overrides the pixels of a tile of a tile map by palette indices of a level, 32 × 32 of them.

An indexed tile set keeps the indices, so the tile follows the palette as it changes, otherwise the colors of the current palette are baked in.

bool Jazz2::ContentResolver::ApplyTileDiffuseOverrideRgba(Tiles::TileMap& tileMap, std::int32_t tileId, const std::uint8_t* rgba)

Overrides the pixels of a tile of a tile map by colors, 32 × 32 of them, 4 bytes RGBA each.

Only a tile of a tile set that isn't indexed can take them, returns false otherwise.

bool Jazz2::ContentResolver::CompileLayerEffectShaders()

Compiles the shaders of the special tile layers, if they aren't compiled yet.

Called once a level that has an x-ray, a blur-behind or a reflection layer is loaded, so a game that never plays one never spends the startup time or the memory on them. Returns false if they couldn't be compiled, the layers are then drawn as on the backends that can't show the effects. The shader of the reflection layers isn't required, without it only they aren't drawn.

bool Jazz2::ContentResolver::ResolveSound(Resources::SoundResource& sound)

Loads the samples of sound if they are not loaded yet.

Sounds are described by the metadata but, on the platforms that defer them, their samples are only read when something first plays them and are given up again at the next load boundary. Returns whether the sound has any sample to play; one whose samples cannot be read is marked so the read is not retried on every play.

String Jazz2::ContentResolver::GetNativeSoundPath(StringView assetPath) const

Returns the console's own copy of a sound sample (relative to Animations), or an empty string.

The content prepared for the Nintendo 64 keeps every sound effect as a .wav64 file next to the pak instead of inside it, and the audio device streams it from the cartridge while it plays, so a sound costs no RAM at all (see nCine::N64AudioDevice). It is the only form the console plays: nothing is decoded there, so a sample without its .wav64 stays silent.

bool Jazz2::ContentResolver::ReadSpriteSheet(StringView path, SpriteSheet& sheet, bool withPixels = true)

Reads a sprite sheet (.aura, relative to Animations) into memory without making a texture of it.

For what needs the pixels themselves, the level scripts edit the sprites this way. Without withPixels only the header is read and SpriteSheet::Pixels stays empty. Returns false if there's no such sprite sheet or it can't be read.

Variable documentation

static std::int32_t Jazz2::ContentResolver::FirstDynamicPaletteRow constexpr

First shared-palette row available for dynamic per-player allocation.

Lower rows are reserved for the sprite palette (row 0) and the generated gem palettes (rows 1-2).

static std::int32_t Jazz2::ContentResolver::FurSectionCount constexpr

Number of recolorable fur sections.

How a player's 4-byte fur color maps to recolored palette sections

The fur color is 4 bytes, one per section (as in the original game). The low 7 bits of each byte are the starting palette index of an 8-color gradient in the sprite palette; those 8 colors are copied into the section's destination block(s) in the per-player palette (a byte of 0 keeps the original colors for that section). If FurHueShiftFlag is also set, the gradient's hue is rotated by HueShiftDegreesForGradient first (see ShiftHue), which roughly doubles the selectable color variants without extra gradients.

Every character's scheme uses the same section order — Primary Fur, Secondary Fur, Weapon, Misc — so a picked color recolors the analogous region on each one. The destination blocks differ per character (GetFurSchemeIndex) because their sprites are drawn with different palette ranges: Jazz uses the standard rabbit ranges (0x10/0x18/0x20/0x28); Spaz reorders them to his own fur layout; Lori uses entirely different ranges (hair, purple suit, dark-blue weapon, lips), with her eyes left at their original color. The per-character schemes are defined in the source file.

static std::int32_t Jazz2::ContentResolver::FurSectionMaxBlocks constexpr

Maximum number of destination blocks a single fur section can recolor.

Most sections map to one block, but a section may span several (e.g., Lori's hair occupies both the 0x28 highlight block and the 0x38 gold-ramp block, recolored together as one logical section).

static std::uint8_t Jazz2::ContentResolver::FurHueShiftFlag constexpr

High bit of a fur section byte requesting its gradient be hue-shifted by HueShiftDegreesForGradient.

The low 7 bits stay the gradient start index (gradient starts never exceed 0x58, so this bit is always free)