coastline 0.0.4
Loading...
Searching...
No Matches
coastline Namespace Reference

Classes

struct  AssetFileAlias
 A logical file backed by a physical file in the same pack or the default pack. More...
struct  AssetStorageSavings
 The number and total byte size of files removed from freshly converted generated packs. More...
class  GameConfig
 The settings of BossRally.ini. More...
class  ConfigSaver
 Writes copies of the configuration on a thread, away from the frames. More...
class  ConsoleSegment
 The main segment of a release, as the console loads it. More...
struct  ConsoleString
 A message of the Nintendo 64 releases. More...
struct  SaveFolderString
 A message of the menus in English that the game words differently from the console. More...
struct  ControllerState
 The state of one controller port, as libultra reports a pad. More...
struct  PakNote
 A note of a Controller Pak. More...
class  ControllerPak
 The notes of a Controller Pak, stored in a directory, with the settings note in another. More...
struct  ControlPreset
 A set of bindings of every action, in the syntax of the Controls section. More...
struct  ControlSource
 A button or the half of an axis of a gamepad that drives an action. More...
class  ControlBindings
 Configured action sources, player devices, and stick dead zone for an input owner. More...
struct  DecalTexture
 The byte offsets and dimensions of an indexed model texture or numbered paint layer. More...
class  DecalCar
 Editable console body materials or numbered image layers for an imported car. More...
struct  DecodedDisc
 A decoded disc image whose temporary files remain available through shared storage. More...
class  DiscordPresence
 Optional Discord Rich Presence through the local desktop client's IPC endpoint. More...
class  DiscTrackReader
 Read bounded sectors across the ordered parts of a disc track. More...
struct  EngineTexture
 A texture of the race engine, as 8-bit RGBA texels. More...
class  EngineTextures
 Decoded textures for one active race engine. More...
struct  BrowserEntry
 An entry of a listing of the file browser. More...
struct  WizardImport
 The files an import of the wizard reads. More...
struct  WizardServices
 The routines the wizard calls to check and import its files. More...
struct  WizardSearchResult
 The images found during a directory search, indexed by detected release. More...
struct  WizardEvent
 An event of the keyboard or the mouse. More...
struct  WizardControl
 A control positioned on the grid. More...
class  SetupWizard
 Manage setup screens, their controls and focus, the file browser, and the import. More...
class  TextFont
 The texture of the 256 glyphs of the font and of the mouse pointer. More...
struct  TextCell
 A cell of the grid. More...
class  TextGrid
 The cells of the screen and the place of the text cursor. More...
struct  SetupRun
 How a run of the setup wizard ended. More...
class  FlacTrack
 Decode imported FLAC tracks into stereo PCM without discarding block remainders. More...
class  FreeCamera
 A movable camera relative to the normal eye space of menus and logos. More...
struct  StageVertex
 A vertex of a shaded triangle of a stage: its place and its colour. More...
struct  ScreenFade
 The fade of the screen: a wipe whose level goes to its target at a rate, and the edges of the picture it shows, in pixels of the 320 by 240 screen. More...
class  GameModeSession
 Optional Linux GameMode registration for the lifetime of an interactive game process. More...
class  GameSettings
 Persistent game choices for the options menu. More...
struct  GltfDocument
 A glTF or GLB document with buffers joined and buffer-view offsets adjusted. More...
struct  DisplayOptions
 The options of the window and the GPU device. More...
class  GpuWindow
 The window of the game and the GPU device that draws into it. More...
struct  IconEntry
 One image of an icon file. More...
struct  IconPixels
 An image of an icon as 8-bit RGBA texels. More...
struct  IconSize
 The size of an image of the icon of the game, from the name of its PNG file. More...
struct  UsaMusicModule
 A music module of the USA cartridge and its name in a music pack. More...
struct  DiscTrackExtent
 A contiguous part of a disc track, excluding its pregap. More...
struct  CueTrack
 One disc track with stored sector sizes and logical track boundaries. More...
struct  PlayerDevices
 The devices that drive one player. More...
class  InputBindings
 Open every gamepad in the order it connects, and drive the first two ports with the devices the Player1 and Player2 keys of the Controls section choose. More...
struct  IntroButtons
 The buttons of the first controller that act on the splash screens. More...
class  Intro
 The regional splash screens, drawn with converted models or the Japanese title image. More...
class  IntroSequence
 An ordered asset-pack sequence of images, movies, and static models. More...
class  GameLog
 Forward SDL messages to a file and the previous callback until destruction. More...
struct  MenuProfile
 The parts of the profile of a player of the console the menus read, as InitPlayerProfileDefaults() of the console sets them. More...
struct  MenuOptions
 The settings of the options menu, as OptionSettings of the console. More...
struct  MenuSeason
 A season of the championship, as g_SeasonTable of the console records it. More...
struct  MenuCar
 A car the players can choose, as g_aCarModels of the console records it. More...
struct  StageMesh
 The shaded triangles of a display list of the stage of the cars. More...
struct  CarSelectPlayer
 The choices of a player on the car select screen, the per-player state of the console. More...
class  Menus
 The menus, drawn with the import of a release. More...
struct  MenuButtons
 The presses of a controller that act on a menu, each true on the frame it starts. More...
struct  MenuItem
 An item of a menu screen. More...
struct  MenuSetup
 What a frame of a screen shows, the arguments of ProcessScreenState(). More...
struct  MenuTitleImage
 A picture over the title of a screen, and its rectangle on the 320 by 240 screen. More...
class  MenuScreen
 The state and the assets of the menu screens, read once from the import of a release. More...
struct  TextStyle
 How a string of the menus is drawn. More...
class  MenuText
 The two fonts of the menus, their gradients, and the layout of their glyphs. More...
class  MipsCpu
 The VR4300 processor and the RDRAM it runs from. More...
class  N64MixerContext
 Mixer channels, XM storage, and synchronisation for one SDL audio session. More...
class  N64Audio
 The XM player and sample mixers of the Nintendo 64 release, streamed as native stereo PCM. More...
class  N64MixerLock
 A lock of the mixers and the music player of the console against the audio thread that mixes them, for the life of the object. More...
struct  N64DemoFrame
 The first vehicle of the demo after a step of its race. More...
struct  N64Demo
 The recorded demo. More...
struct  GltfImage
 A texture of a glTF document, as the RDP samples it. More...
struct  GltfModel
 A glTF document, the bytes of its one buffer, and its images. More...
struct  PaintShopInput
 The input of the player of the paint shop for a frame. More...
struct  PaintRect
 A rectangle of the 640 by 480 screen, ScreenRect of the console. More...
struct  PaintSprite
 A picture of the paint shop, Sprite of the console. More...
struct  PaintSwatch
 A colour of the palette of the decals and its swatch, PaletteSwatch of the console. More...
struct  PaintGlyph
 A key of the keyboard of the text tool and its glyph, DecalGlyph of the console. More...
struct  PaintVector
 A direction of the console. More...
class  PaintShop
 The paint shop of the console. More...
struct  GamePaths
 The directories the game reads and writes, each ending in the application directory. More...
class  FrameTimings
 One-second timing averages and worst values since collection began. More...
class  PerformanceStats
 Frame timings and system statistics, with memory and GPU sampling on a separate thread. More...
class  Ptr32Memory
 Writable memory within signed 32-bit offsets of g_abPtr32Anchor for converted asset pointers. More...
class  ConsoleCredits
 Captions and scrolling credits for one attract-demo controller. More...
class  AttractDemo
 Attract-demo rotation for one front end. More...
class  RaceInputContext
 Input history and haptic resources for one active input configuration. More...
class  RaceMusicContext
 Race music resources for one active audio session, destroyed before its shared menu player. More...
class  FrontEndMusic
 Front-end music with independent CD resources and the shared native XM player. More...
struct  RacePlayerSetup
 The car and the setup of a player. More...
struct  RaceSetup
 What a race is, in the terms of the race engine. More...
struct  RacePlayerResult
 How a player finished a race. More...
struct  RaceResults
 The results of a race, as the race engine records them. More...
class  RaceSession
 Race progress and results for one front end. More...
struct  RaceCar
 The car of a vehicle of a race. More...
class  RaceView
 The models of the track and the cars of a race, and their drawing from the state of the race. More...
struct  ScriptPress
 A press of the buttons of a controller from a frame for a number of frames. More...
struct  ScriptMouse
 The mouse at a place of the 320 by 240 screen from a frame for a number of frames. More...
struct  ScriptKey
 A key of the keyboard down from a frame for a number of frames. More...
struct  ScriptTyping
 A text typed at a frame, or a key of <backspace> or <enter>. More...
struct  Script
 The input and the captures of a script of run-script. More...
struct  ScriptError
 A line of a script that cannot be read. More...
class  EngineRuntime
 Front-end choices and race buffers for one active engine runtime. More...
class  SaveFile
 An exclusive lock shared by cooperating save writers, released on destruction or process exit. More...
struct  Lighting
 The lights of a model, an ambient colour and a directional colour from a direction in the space the model is placed in. More...
struct  MorphPose
 The pose of the vertices of an animated model: two keys and the share of the second. More...
struct  VertexAnimationInfo
 A vertex animation of a model, as the game plays it. More...
struct  Reflection
 The reflection of the sky on a car: the image the parts whose texture coordinates come from their normals sample, the axes those coordinates follow, and the column of the image the window starts at, as the tile of the reflection of the race takes it. More...
struct  Highlight
 The specular highlight of a car, as the PC release generates its coordinates for the tile of gDPSetHilite1Tile(): a quarter of the dot of the normal with each axis across the texture, from the offset of the tile, added to the colour drawn where the depth is equal. More...
struct  Fog
 The fog of the PC release: each vertex shows the share of its colour of the range by the reciprocal of its w, a share below 8 of 255 none, and the rest is the colour of the fog. More...
struct  CarShadow
 The shadow of a car on the track, as RenderTrackInstance() lays its texture on the ground under the car: 1024 across the texture, centred under the car, along and across its heading. More...
struct  ImageDamage
 The damage of an image of a car, as LoadCarPaintTextures() damages the image of a paint set. More...
struct  ModelOptions
 What of a glTF document a RenderModel takes, and how. More...
class  RenderDocument
 A glTF document of the import on the GPU, read and decoded once for every RenderModel of its parts: its vertices, its animations, and the images no paint colours. More...
class  RenderModel
 A converted model on the GPU: its meshes, its parts, and its animations. More...
class  VertexDisplacement
 How far each vertex of a model is moved on the GPU, such as by the dents of a car. More...
class  RenderTexture
 A texture of the renderer for flat pictures and text. More...
struct  FlatVertex
 A corner of a flat quad: its place in the space of the flat draws, its texels, and its colour. More...
class  RenderQuadBuffer
 Persistent quad slots, updated independently and drawn in a caller-specified order. More...
struct  FlatMaterial
 How a run of flat quads is coloured: the textures and the colour combiner of the RDP. More...
class  SceneRenderer
 The renderer of a frame. More...
class  SoundEffects
 Converted sound selection and per-sample level matching for one game session. More...
class  GameText
 Read the strings of a language and of en-us, each a JSON object of strings by key, from strings/LANGUAGE.json and strings/en-us.json under assets, for the race and the menus. More...
struct  ExtraMenuTrack
 Additional tracks after the console tracks, before menu actions. More...
class  EngineModels
 Model relocation, texture lookup, converted vertices, and dents for one race engine. More...
class  VideoPlayer
 A decoded video and its audio, with bounded frame buffering. More...

Typedefs

using WizardProgress = std::function<bool(const std::string &step, double fraction)>
 Reports the step of an import and its share done from 0 to 1, and returns false to cancel.
using WizardSearchProgress
 Report search progress and return false to cancel.
using ImportProgress = std::function<bool(const std::string &step, double fraction)>
 Reports import progress with a description and a fraction from 0 to 1.
using ImportJob = std::function<std::optional<std::string>(const ImportProgress &)>
 Independent import work in a private destination directory.
using StringTable = std::map<std::string, std::string, std::less<>>
 Strings by key, in UTF-8.
using NoteEquipmentCounts = std::array<std::size_t, 5>
 Counts of handling, transmission, tyre, suspension, and controller-layout choices, in order.
using EnvironmentReader = std::function<std::optional<std::string>(const char *name)>
 Reads an environment variable, or nothing when it is unset or empty.
using SavePayloadValidator = std::function<bool(std::span<const std::uint8_t>)>
 Validate format-specific fields of an internal save's payload under its exclusive process lock.
using Matrix4 = std::array<float, 16>
 A 4 by 4 matrix, column by column.
using CarDamage = std::array<int, CAR_DAMAGE_SIDES>
 The levels of damage of the sides of a car, each from 0 for none to CAR_DAMAGE_LEVELS.

Enumerations

enum  ControllerButton : std::uint16_t {
  BUTTON_C_RIGHT = 0x0001 , BUTTON_C_LEFT = 0x0002 , BUTTON_C_DOWN = 0x0004 , BUTTON_C_UP = 0x0008 ,
  BUTTON_R = 0x0010 , BUTTON_L = 0x0020 , BUTTON_D_RIGHT = 0x0100 , BUTTON_D_LEFT = 0x0200 ,
  BUTTON_D_DOWN = 0x0400 , BUTTON_D_UP = 0x0800 , BUTTON_START = 0x1000 , BUTTON_Z = 0x2000 ,
  BUTTON_B = 0x4000 , BUTTON_A = 0x8000
}
 The buttons of a Nintendo 64 controller, with the bits libultra reports. More...
enum class  PakRelease { Usa , Eur , Jpn }
 The release of the cartridge whose game code and company code the notes of an image take. More...
enum  ControlAction : std::size_t {
  CONTROL_STEER_LEFT , CONTROL_STEER_RIGHT , CONTROL_ACCELERATE , CONTROL_BRAKE ,
  CONTROL_REVERSE , CONTROL_GEAR_UP , CONTROL_GEAR_DOWN , CONTROL_COCKPIT_CAMERA ,
  CONTROL_BUMPER_CAMERA , CONTROL_CHASE_CAMERA , CONTROL_PAUSE_MENU_UP , CONTROL_PAUSE_MENU_DOWN ,
  CONTROL_PAUSE_MENU_SELECT , CONTROL_PAUSE , CONTROL_START_OR_RESPAWN , CONTROL_MENU_A ,
  CONTROL_MENU_B , CONTROL_MENU_Z , CONTROL_MENU_START , CONTROL_MENU_L ,
  CONTROL_MENU_R , CONTROL_MENU_C_UP , CONTROL_MENU_C_DOWN , CONTROL_MENU_C_LEFT ,
  CONTROL_MENU_C_RIGHT , CONTROL_MENU_D_UP , CONTROL_MENU_D_DOWN , CONTROL_MENU_D_LEFT ,
  CONTROL_MENU_D_RIGHT , CONTROL_MENU_STICK_LEFT , CONTROL_MENU_STICK_RIGHT , CONTROL_MENU_STICK_UP ,
  CONTROL_MENU_STICK_DOWN , CONTROL_ACTION_COUNT
}
 The actions of a gamepad the Controls section of BossRally.ini binds, in the order of keys. More...
enum class  WizardCartridge { Usa , Eur , Jpn }
 A supported ROM release. More...
enum class  WizardKey {
  Tab , Enter , Space , Escape ,
  Up , Down , Left , Right ,
  PageUp , PageDown , Home , End ,
  Backspace , Delete , SelectAll , DeleteWord ,
  DeleteNextWord , WordLeft , WordRight
}
 A key of the keyboard the wizard reads. More...
enum class  WizardScreen {
  Reimport , SourceSelection , Files , SearchDirectory ,
  Search , Import , Done
}
 A screen of the wizard, in order. More...
enum class  WizardEnd { Running , Quit , Finished }
 How the wizard ended. More...
enum class  WizardControlId {
  DiscText , DiscBrowse , DiscClear , Rom1Text ,
  Rom2Text , Rom3Text , Rom1Browse , Rom2Browse ,
  Rom3Browse , Rom1Clear , Rom2Clear , Rom3Clear ,
  SearchAssets , SpecifyPaths , Portable , SearchText ,
  SearchBrowse , SearchClear , StartSearch , RetrySearch ,
  UseFound , Back , Next , Quit ,
  Cancel , Finish , BrowserList , BrowserFilter ,
  BrowserOk , BrowserUseDirectory , BrowserCancel , MessageOk ,
  MessageYes , MessageNo
}
 A control of a screen or a dialog of the wizard. More...
enum class  CgaColor : std::uint8_t {
  Black , Blue , Green , Cyan ,
  Red , Magenta , Brown , LightGray ,
  DarkGray , LightBlue , LightGreen , LightCyan ,
  LightRed , LightMagenta , Yellow , White
}
 The 16 colours of CGA, by their number. More...
enum class  ScaleFilter { Linear , Nearest , EdgeAdaptive }
 How the frame is scaled to the window. More...
enum class  TextureFilter { N64 , Modern , Nearest }
 How the textures the game filters are filtered. More...
enum class  PostAntialias { None , Fxaa }
 The anti-aliasing of the finished frame, before it is scaled to the window. More...
enum class  ScreenShader {
  None , ConsumerCrt , Pvm , ApertureGrille ,
  PcCrt
}
 Display simulation applied after the internal frame is scaled to the window. More...
enum class  HdrOutput { Auto , On , Off }
 Whether HDR output follows the window, is requested, or is disabled. More...
enum class  RomRelease { Usa , Jpn , Eur , Asia }
 A Nintendo 64 release the game reads models, textures, and music from. More...
enum class  ImportSource {
  Disc , Usa , Jpn , Eur ,
  Asia
}
 A source of the data of the default pack. More...
enum class  IntroEnd { Running , MainMenu , AttractDemo }
 Where the splash screens go once they fade out. More...
enum class  MenusEnd {
  Running , Quit , Splash , AttractDemo ,
  Race , Credits , ApplySettings , Reinitialize
}
 Where the menus go next. More...
enum class  GameMode { Championship , Arcade , TimeAttack , Practice }
 The modes of the game, as g_dwGameMode of the console. More...
enum class  MenuResult {
  None , Chosen , Cancelled , Up ,
  Down
}
 What a frame of a menu screen ends with, the results of ProcessScreenState(). More...
enum  MipsRegister : int {
  MIPS_ZERO = 0 , MIPS_V0 = 2 , MIPS_V1 = 3 , MIPS_A0 = 4 ,
  MIPS_A1 = 5 , MIPS_A2 = 6 , MIPS_A3 = 7 , MIPS_SP = 29 ,
  MIPS_RA = 31
}
 The numbers of the general registers the calling convention gives a role. More...
enum class  N64DemoRelease { Usa , Jpn , Eur }
 A release of the cartridge whose demo is recorded. More...
enum  PaintTool : u8 {
  PAINT_TOOL_BRUSH_SIZE , PAINT_TOOL_BRUSH , PAINT_TOOL_FILL , PAINT_TOOL_LINE ,
  PAINT_TOOL_TEXT , PAINT_TOOL_RECTANGLE , PAINT_TOOL_OVAL , PAINT_TOOL_MIRROR ,
  PAINT_TOOL_CLEAR , PAINT_TOOL_LOAD , PAINT_TOOL_SAVE , PAINT_TOOL_UNDO ,
  PAINT_TOOL_EXIT , PAINT_TOOLS
}
 The tools of the paint shop, each a button, as the console numbers them. More...
enum class  RaceMusicSource { Modules , CdAudio }
 Where the music of a race comes from. More...
enum class  RaceEnd {
  Running , Results , Menu , SeasonMenu ,
  Credits
}
 How a race ends. More...
enum class  ScriptMouseButton { None , Left , Right }
 The button of the mouse a move holds down. More...

Functions

std::optional< std::string > ImportAssetImages (const std::filesystem::path &data, const std::filesystem::path &disc, std::span< const std::filesystem::path > roms, const ImportProgress &progress={}, std::vector< std::filesystem::path > *sources=nullptr)
 Import a disc and every supplied ROM as one batch.
std::optional< std::string > WriteImportDependencies (const std::filesystem::path &file, const std::filesystem::path &target, std::span< const std::filesystem::path > sources)
 Write a GCC-style dependency file atomically for a completed asset import.
std::optional< std::string > CurateAssetPacks (const std::filesystem::path &defaults)
 Put the images of the cartridges that show the branding the PC release removed (Nintendo, Top Gear, and Kemco) in place of their PC images in the default pack, and move the PC images to the pack boss beside it.
nlohmann::json PackSettings (const std::filesystem::path &data, std::string_view pack, const std::filesystem::path &fallback={})
 Read default settings from pack.json and replace matching keys with selected pack settings.
std::expected< AssetStorageSavings, std::string > DeduplicateAssetFiles (const std::filesystem::path &defaults)
 Replace byte-identical generated files with aliases.
std::optional< std::string > FinalizeGeneratedAssetPacks (const std::filesystem::path &defaults)
 Remove empty subdirectories and write permissions from generated packs, excluding mod packs.
void RemoveAssetTree (const std::filesystem::path &path, std::error_code &error)
 Delete a tree after restoring directory owner-write permissions, without following symlinks.
std::expected< std::vector< AssetFileAlias >, std::string > ReadAssetFileAliases (const std::filesystem::path &pack, const std::filesystem::path &defaults)
 Read and validate an alias table, including its physical targets.
std::optional< float > ParseAspectRatio (std::string_view text)
 Read a finite, positive aspect ratio or an automatic-sizing setting.
std::array< int, 2 > ExpandInternalResolution (int width, int height, float aspect)
 Expand a resolution to an aspect ratio, with minimum dimensions of 320x240.
std::array< int, 2 > ScaleFrameResolution (int width, int height, float scale, float aspect)
 Scale window dimensions and fit an aspect ratio before bounded integer conversion.
std::optional< std::string > ExportPakImage (const ControllerPak &pak, const std::filesystem::path &file, PakRelease release=PakRelease::Usa)
 Write the notes of a pak as the image of a formatted Controller Pak, with the game code and the company code of a release on each note.
std::optional< std::string > ImportPakImage (const ControllerPak &pak, const std::filesystem::path &file)
 Copy the notes of any release of the game from the image of a Controller Pak, or from the first pak of an image of four, to a pak.
constexpr ControlPreset RaceControlPreset (std::string_view name, const std::array< std::string_view, RACE_CONTROL_ACTIONS > &race)
void LoadControls (const GameConfig &config)
 Read the Controls section of config: the preset of the Preset key, the default for an absent or unknown preset, with each action key present replacing the binding of the preset, the device of each player, and the dead zone of the axes.
std::string_view PlayerDevice (std::size_t player)
bool IsControlAnalog (ControlAction action)
int ReadControl (SDL_Gamepad *gamepad, ControlAction action)
int TexelOffset (int x, int y, int width)
 The byte of a texel of a 4-bit texture as the console loads it in one block, the 64-bit words of each odd row swapped.
std::expected< DecodedDisc, std::string > CreateDecodedDisc (bool raw, std::uint64_t bytes)
 Create private temporary storage for an ISO or raw-sector image.
constexpr bool IsDiscImageExtension (std::string_view extension)
 Check a lower-case filename extension, including its initial dot.
std::expected< std::vector< CueTrack >, std::string > ReadDiscTracks (const std::filesystem::path &disc, const ImportProgress &progress={}, std::vector< std::filesystem::path > *sources=nullptr)
 Resolve tracks from CUE, ISO, BIN, numbered track files, CloneCD, DiscJuggler CDI, Nero NRG, Alcohol MDS, BlindWrite 4/5/6, Pinnacle PDI, or an unencrypted ISZ image.
std::optional< std::string > DownloadFile (const std::string &url, const std::filesystem::path &output, const ImportProgress &progress={})
 Download an HTTPS URL to a file with the HTTP client of the operating system, following redirects.
unsigned CreateEngineTexture (const unsigned char *image, const unsigned char *palette, int width, int height, int lineBytes)
 Create a texture from an 8-bit colour-indexed image of the console, as the hook g_pfnCreateTextureFromN64Image() of the PC release creates one.
int DecodeEngineTexture (void *destination, const unsigned char *image, const unsigned char *palette, int width, int height, int lineBytes)
 Decode an 8-bit colour-indexed image of the console to its colours, each a big-endian RGBA5551 half, as the hook g_pfnDecodeN64TextureToPixelBuffer() of the PC release decodes one.
void LoadEngineTexture (unsigned entry, const unsigned char *colors)
 Load the decoded colours of an image into a texture, as a command 0xdd of a display list loads them.
const EngineTexture * FindEngineTexture (unsigned entry)
void ClearEngineTextures ()
 Drop every texture, as the renderer of the PC release shuts its textures down.
std::optional< std::vector< BrowserEntry > > ListBrowserDirectory (const std::filesystem::path &directory, std::span< const std::string_view > extensions, bool directoriesOnly=false)
 List a directory for the file browser: .. first, or on Windows the drives at the root of a drive, then the directories, then the files with one of extensions.
std::filesystem::path ResolveUserPath (std::string_view text, const std::filesystem::path &home)
 Expand an initial home-directory shorthand and use native separators after expansion.
std::filesystem::path PathFromUtf8 (std::string_view text)
std::string LowercaseExtension (const std::filesystem::path &path)
std::optional< WizardCartridge > BaseCartridge (const std::array< bool, WIZARD_CARTRIDGES > &checked)
 Choose the base release for the default pack.
WizardSearchResult SearchWizardDirectory (const std::filesystem::path &directory, const WizardServices &services, const WizardSearchProgress &progress)
 Search recursively, including hidden directories, for validated disc and ROM images.
char AcceleratorOf (const std::string &label)
Matrix4 TextGridProjection (float aspect)
std::array< int, 2 > GridPointInWindow (float windowWidth, float windowHeight, float frameAspect, float x, float y)
 The place of the mouse on the grid, with the frame fitted to the window and the grid to the frame as TextGridProjection() fits it.
std::uint8_t Cp437FromCodepoint (char32_t codepoint)
std::u32string DecodeUtf8 (std::string_view text)
std::string EncodeUtf8 (std::u32string_view text)
SetupRun RunSetupWizard (GpuWindow &window, GamePaths &paths, GameConfig &config, const Script &script, std::span< const SDL_Scancode > scriptKeys, const std::filesystem::path &captures, bool fixedTime, const std::string &reimportReason={}, const std::filesystem::path &portableDirectory={})
 Show the setup wizard until the user finishes or quits it.
constexpr std::uint32_t SfxVolume (std::uint32_t right, std::uint32_t left)
constexpr std::array< std::uint32_t, 2 > CombineLerp (std::uint32_t a0, std::uint32_t b0, std::uint32_t c0, std::uint32_t d0, std::uint32_t alphaA0, std::uint32_t alphaB0, std::uint32_t alphaC0, std::uint32_t alphaD0, std::uint32_t a1, std::uint32_t b1, std::uint32_t c1, std::uint32_t d1, std::uint32_t alphaA1, std::uint32_t alphaB1, std::uint32_t alphaC1, std::uint32_t alphaD1)
 The two words of gDPSetCombineLERP(), from the colour and alpha inputs of each cycle.
Matrix4 Translation (float x, float y, float z)
Matrix4 Scale (float s)
Matrix4 RotationX (float angle)
Matrix4 RotationZ (float angle)
std::array< float, 2 > ScreenExtent (float aspect)
 The part of the frame the 4:3 screen of the menus covers, centred: the whole height of a frame wider than 4:3 and the whole width of a narrower one.
Matrix4 MenuProjection (float aspect, float nearPlane, float farPlane, const std::optional< Matrix4 > &camera=std::nullopt)
 The camera of the menus, which looks at the middle of the 320 by 240 screen from 290 in front of it with a field of 45 degrees, onto the 4:3 screen centred in the frame, to a depth from 0 to 1.
Matrix4 FlatProjection (float aspect)
Matrix4 ScreenModelAt (float x, float y, float z, float angle, float scale)
 DrawModelAt() of the console: a model turned about its own axis, scaled, stood up, and placed.
Matrix4 StageCamera (float aspect, const std::array< float, 3 > &eye, int x, int y, int width, int height, const std::optional< Matrix4 > &camera=std::nullopt)
 SetupCameraMatrix() of the console for the trackside camera of a stage of the menus.
Matrix4 StageFrameAt (float x, float y, float angle)
 The frame of a car on a stage of the menus in the space of the console, facing an angle about z, 0.254 above the stage.
Matrix4 StageCarAt (float x, float y, float angle)
 The place of a car on a stage of the menus, facing an angle about z, 0.254 above the stage.
Reflection StageReflection (const RenderTexture *texture, const std::array< float, 3 > &eye)
 The reflection of the sky on a car as RenderVehicleModel() sets it up for the trackside camera of the menus looking at the origin from an eye: the axes of guLookAtReflectF() from the heading of the camera, and the window of the tile turning with the heading.
void AddTriangle (std::vector< FlatVertex > &quads, const StageVertex &a, const StageVertex &b, const StageVertex &c)
 Add a shaded triangle to flat quads, as a quad whose last corner repeats its third.
SDL_Rect FrameRect (Uint32 frameWidth, Uint32 frameHeight, int x, int y, int width, int height)
Lighting ReadLighting (const nlohmann::json &light)
std::optional< std::vector< s8 > > ReadSound (const std::filesystem::path &path)
s16 PlaySoundEffect (std::vector< s8 > &sample, std::uint32_t volume)
 Play a sound on a free sound effect channel.
bool ApplyGraphicsPreset (GameConfig &config, std::string_view preset)
 Apply a graphics preset without changing language or region.
bool SpeedInMph (const GameConfig &config, std::string_view region, std::string_view country)
 Resolve speed units without recording an automatic choice as a user preference.
int SoundEffectsVolume (const GameConfig &config, bool n64)
 Resolve SFX volume from a manual preference or the selected sample source.
std::optional< nlohmann::ordered_json > GhostToJson (std::span< const std::uint8_t > bytes)
 Describe a ghost recording of the PC release (RGho) as JSON: the recording, the settings, the name of its slot, and each frame with every bit in a named field.
std::optional< std::vector< std::uint8_t > > GhostFromJson (const nlohmann::ordered_json &json)
 Build the file of a ghost recording from its JSON, the inverse of GhostToJson().
std::string FormatGhostJson (const nlohmann::ordered_json &json)
 Write the JSON of a recording with each frame on one line.
std::optional< std::vector< u8 > > PackGhostNote (std::span< const u8 > recording)
 Compress a recording into the note of a ghost car, as SaveSaveLoadNote() of the console does: each of the two channels of the recording (the steering and the actions) with run lengths, and the length of each channel first in the byte order of the console.
std::optional< std::vector< u8 > > UnpackGhostNote (std::span< const u8 > note)
 Expand the note of a ghost car into its recording.
std::vector< u8 > PackGhostFrames (std::span< const u8 > recording, std::span< const u8 > frames)
 Store the frames of the race engine with the recording of the console they were recorded with.
std::optional< std::vector< u8 > > GhostFramesFor (std::span< const u8 > file, std::span< const u8 > recording)
 Read the frames of the race engine of a recording of the console from the file of PackGhostFrames().
bool SaveGhostFrames (const std::filesystem::path &path, std::span< const u8 > recording, std::span< const u8 > frames)
 Atomically write the payload of PackGhostFrames() with a verified integrity header.
std::optional< std::vector< u8 > > LoadGhostFrames (const std::filesystem::path &path, std::span< const u8 > recording)
 Read the frames of a recording from the file of SaveGhostFrames().
std::expected< GltfDocument, std::string > ReadGltfDocument (const std::filesystem::path &path)
 Read a model or image-override document.
SDL_GPUTexture * CreateGpuTexture (SDL_GPUDevice *device, const SDL_GPUTextureCreateInfo *info)
 SDL_CreateGPUTexture(), recording bytes of every level and sample in GpuWindow::GpuMemoryBytes().
SDL_GPUBuffer * CreateGpuBuffer (SDL_GPUDevice *device, const SDL_GPUBufferCreateInfo *info)
 SDL_CreateGPUBuffer(), recording its size in GpuWindow::GpuMemoryBytes().
SDL_GPUTransferBuffer * CreateGpuTransferBuffer (SDL_GPUDevice *device, const SDL_GPUTransferBufferCreateInfo *info)
 SDL_CreateGPUTransferBuffer(), recording its size in GpuWindow::GpuMemoryBytes().
void ReleaseGpuTexture (SDL_GPUDevice *device, SDL_GPUTexture *texture)
 SDL_ReleaseGPUTexture(), subtracting its bytes from GpuWindow::GpuMemoryBytes().
void ReleaseGpuBuffer (SDL_GPUDevice *device, SDL_GPUBuffer *buffer)
 SDL_ReleaseGPUBuffer(), subtracting its bytes from GpuWindow::GpuMemoryBytes().
void ReleaseGpuTransferBuffer (SDL_GPUDevice *device, SDL_GPUTransferBuffer *buffer)
 SDL_ReleaseGPUTransferBuffer(), subtracting its bytes from GpuWindow::GpuMemoryBytes().
std::optional< IconSize > ParseIconName (std::string_view name)
 Read the size of an image of the icon from the name the import gives its PNG file.
std::string IconName (const IconSize &size)
 Give the name of the PNG file of an image of the icon.
std::vector< IconEntry > ListIconImages (std::span< const std::uint8_t > icon)
 List the images of an icon file.
std::optional< IconPixels > DecodeIconBitmap (std::span< const std::uint8_t > image)
 Decode an icon image that is a device-independent bitmap: the colours, then the AND mask that makes a pixel transparent.
bool NormalizeRomByteOrder (std::span< std::uint8_t > image)
 Convert a cartridge image in any of the three byte orders (z64, v64, n64) to big-endian.
std::expected< RomRelease, std::string > IdentifyRom (std::span< const std::uint8_t > image)
 Identify a big-endian cartridge image by its SHA-1.
std::expected< RomRelease, std::string > IdentifyRomFile (const std::filesystem::path &image)
 Identify a cartridge image file in any of the three byte orders by its SHA-1.
std::expected< RomRelease, std::string > ImportRom (const std::filesystem::path &image, const std::filesystem::path &dataDirectory, const ImportProgress &progress={})
 Check a cartridge image and extract its main segment and its assets, inflated, to n64/usa, n64/jpn, n64/eur, or n64/asia under dataDirectory.
std::expected< std::vector< CueTrack >, std::string > ParseCueSheet (const std::filesystem::path &cue)
 Parse a CUE sheet.
std::expected< std::size_t, std::string > ImportDisc (const std::filesystem::path &disc, const std::filesystem::path &dataDirectory, const ImportProgress &progress, std::vector< std::filesystem::path > *sources=nullptr)
 Copy the files of the Boss Rally disc the game opens to dataDirectory, and its CD audio tracks as music/trackNN.flac.
std::optional< std::string > CheckDisc (const std::filesystem::path &disc)
 Check that a disc image or directory provides Boss Rally files without copying them.
std::optional< std::string > RunImportJobs (std::span< const ImportJob > jobs, const ImportProgress &progress={})
 Run independent jobs with at most four workers, limited by available CPU concurrency.
bool RecordImport (const std::filesystem::path &defaults, ImportSource source)
 Record in import.ini of the default pack that source was imported with the current version of its conversion.
std::vector< ImportSource > StaleImports (const std::filesystem::path &defaults)
 The sources of the default pack imported with a conversion version different from the current one.
bool DefaultPackUsable (const std::filesystem::path &defaults)
 Check whether import.ini records the disc and at least one cartridge at current conversion versions, the regional layout is current, and every recorded file exists at its imported size.
bool RecordImportFiles (const std::filesystem::path &defaults)
 Atomically record the relative path and size of every generated file after a successful import.
std::string ReimportMessage (std::span< const ImportSource > sources)
bool SaveIndexed4Png (const std::filesystem::path &path, std::span< const std::uint8_t > texels, std::span< const std::uint8_t, 32 > palette, int width, int height)
 Write a 4-bit colour-indexed image of the console as an indexed PNG image.
bool LoadIndexed4Png (const std::filesystem::path &path, std::span< std::uint8_t > texels, std::span< std::uint8_t, 32 > palette)
 Read an indexed PNG image as the 4-bit texels and the RGBA5551 palette of the console.
bool LoadIndexed4Png (std::span< const std::uint8_t > bytes, std::span< std::uint8_t > texels, std::span< std::uint8_t, 32 > palette)
 Read an encoded indexed PNG with the same requirements as the file overload.
bool SaveRgba8Png (const std::filesystem::path &path, std::span< const std::uint8_t > rgba, int width, int height)
 Write 8-bit RGBA texels as a PNG image, and read it back to check it.
std::optional< std::vector< std::uint8_t > > EncodeIndexed4Png (std::span< const std::uint8_t > texels, std::span< const std::uint8_t, 32 > palette, int width, int height)
 Encode a 4-bit colour-indexed image of the console as an indexed PNG image in memory.
std::optional< std::vector< std::uint8_t > > EncodeRgba8Png (std::span< const std::uint8_t > rgba, int width, int height)
 Encode 8-bit RGBA texels as a PNG image in memory.
PlayerDevices AssignedDevices (std::size_t player, std::size_t players)
 Resolve the Player1 and Player2 keys of the Controls section against the open gamepads.
ControllerState ReadRacePad (const PlayerDevices &devices)
 Read the second player of a race as the console reads a pad: the race actions of the Controls section for each gamepad, and the keyboard bindings of the PC release for the keyboard.
std::int8_t ScaleStickAxis (std::int16_t axis)
 Scale an SDL axis of -32768 to 32767 to the range of the controller stick.
void SetScriptedKeys (std::vector< int > scancodes)
 Add simulated key presses alongside physical keyboard input, for tests.
bool IsKeyDown (SDL_Scancode scancode)
void IgnoreKeyUntilReleased (SDL_Scancode scancode)
 Report a key as up to IsKeyDown() until it is released, for a key a shortcut of the window consumed, such as Enter of Alt and Enter.
void SetSecondControllerState (const ControllerState &state)
 Set the state of the second controller the race reads for its second player, until the next call.
int TakeMouseWheel ()
void ClearMouseWheel ()
 Discard the wheel of the mouse scrolled since TakeMouseWheel() last read it.
std::expected< DecodedDisc, std::string > DecodeIsz (const std::filesystem::path &image, const ImportProgress &progress={})
 Decode an unencrypted ISZ image, including split segments, to temporary storage.
const std::string & SelectedLanguage ()
StringTable MergeStrings (StringTable fallback, const StringTable &language)
std::filesystem::path ReleaseDirectory (const std::filesystem::path &assets)
std::string CartridgeRegion (const std::filesystem::path &release)
std::vector< std::string > AvailableCartridgeRegions (std::span< const std::filesystem::path > dataRoots)
std::optional< std::string > TitleScreenRegion (std::string_view choice, std::string_view currentRegion, std::span< const std::string > available)
std::filesystem::path FontDirectory (const std::filesystem::path &assets, std::string_view language)
std::string AbbreviateLogPaths (std::string_view message, std::string_view home)
 Abbreviate home-directory paths in a log message without changing similarly prefixed paths.
void StopGameLog ()
 Close the active game log and restore its previous callback before fatal process exit.
int CenterLines (std::string_view text, int y, int lines, int lineHeight)
 Centre a string on the place of a block of a number of lines, as a release that draws a message in fewer lines than the USA release centres it.
void PublishN64Volumes ()
 Hand the volumes the game writes (g_bBgmVolume, g_bMusicVolume, g_bSfxMasterVolume, and g_bSfxVolume) to the mixers.
std::expected< N64Demo, std::string > RecordN64AttractDemo (std::span< const std::uint8_t > rom, N64DemoRelease release)
 Record the attract demo of a cartridge.
std::expected< GltfModel, std::string > CarModelToGltf (std::span< const std::uint8_t > bytes, std::size_t imageOffset, std::string_view bufferUri)
 Describe the model of a car as glTF.
std::expected< GltfModel, std::string > TrackToGltf (std::span< const std::uint8_t > bytes, std::string_view bufferUri)
 Describe a track as glTF.
std::expected< GltfModel, std::string > FrontEndModelToGltf (std::span< const std::uint8_t > bytes, std::string_view bufferUri)
 Describe a model of the front end, such as a logo of the splash screens, as glTF.
std::expected< std::vector< std::uint8_t >, std::string > ModelFromGltf (const nlohmann::ordered_json &json, std::span< const std::uint8_t > buffer)
 Build the file of a model or a track from its glTF, the inverse of CarModelToGltf(), TrackToGltf(), and FrontEndModelToGltf().
bool ValidSavedRaceTime (float seconds)
 Check that a saved race time is finite, non-negative, and safe to display in signed hundredths.
bool ValidOptionsNote (std::span< const std::uint8_t > note, const NoteEquipmentCounts &counts)
 Validate native options-note length, volume levels, units, and equipment indices.
bool ValidSeasonNoteValues (std::span< const std::uint8_t > note, const NoteEquipmentCounts &counts)
 Validate native season-note length, times, placements, and equipment indices.
bool ValidGhostRecording (std::span< const std::uint8_t > recording, std::size_t tracks, std::size_t cars, const NoteEquipmentCounts &counts)
 Validate an expanded console ghost's length, track, car, and equipment header.
std::string Utf8FromPath (const std::filesystem::path &path)
bool PortablePathsEnabled ()
std::filesystem::path PortableRoot (const std::filesystem::path &executable, const std::filesystem::path &appImage={})
 Locate portable files beside an application bundle, AppImage, or ordinary executable.
std::expected< GamePaths, std::string > ResolvePortablePaths (const GamePaths &fallback, const std::filesystem::path &executable, const std::filesystem::path &workingDirectory={})
 Prefer adjacent configuration and assets independently when portable lookup is enabled.
std::filesystem::path StorePortablePath (const std::filesystem::path &path, const std::filesystem::path &root, const std::filesystem::path &home)
 Store an input path relative to the portable directory, using '~' for external home paths.
std::filesystem::path RestorePortablePath (const std::filesystem::path &path, const std::filesystem::path &root, const std::filesystem::path &home)
 Rebuild a stored portable input path at its current executable or home location.
std::optional< GamePaths > ResolveXdgPaths (const EnvironmentReader &environment, const std::string &application)
 Resolve the directories with the XDG Base Directory variables and their defaults under the home directory.
std::optional< GamePaths > ResolveGamePaths (const std::string &application)
 Resolve the directories with the conventions of the running operating system: the XDG Base Directory variables on Linux and the BSDs, the folders of the user's library on macOS, and the roaming and local application data folders on Windows.
std::vector< std::filesystem::path > SystemDataDirectories (const std::filesystem::path &executable)
 List system data roots, including the relocated installation and platform defaults.
std::optional< std::filesystem::path > FindAssetData (const std::filesystem::path &user, std::span< const std::filesystem::path > system)
 Find usable assets in system roots first, then in the writable user data root.
bool CreateGamePaths (const GamePaths &paths)
 Create every directory of paths that does not exist.
std::optional< std::string > MigratePortablePaths (const GamePaths &source, const GamePaths &destination, bool copyOnly=false)
 Move portable assets, settings, saves, screenshots, and state to platform directories.
std::optional< std::string > MakePortablePaths (const GamePaths &source, const std::filesystem::path &directory, bool copyOnly=false)
 Export platform data as a portable installation, without copying the executable.
std::optional< std::string > MakePortableDistribution (const GamePaths &source, const std::filesystem::path &executable, const std::filesystem::path &directory, bool copyOnly=false)
 Export installed program files and platform data into a complete portable distribution.
std::optional< std::string > ResetGamePaths (const GamePaths &paths, bool factoryReset=false)
 Clear imported assets and asset caches, or all application data for a factory reset.
std::filesystem::path DefaultAssets (const std::filesystem::path &data)
 The directory the import writes the game data to, the default pack.
std::filesystem::path PackDirectory (const std::filesystem::path &data, std::string_view pack, const std::filesystem::path &fallback={})
 The directory of a pack under assets of the data directory, named after the pack.
std::optional< std::filesystem::path > PackAssets (const std::filesystem::path &data, const std::filesystem::path &cache, std::string_view pack, const std::filesystem::path &fallback={}, std::string_view region={})
 The directory the game reads its assets from with a pack selected.
std::expected< DecodedDisc, std::string > DecodePdi (const std::filesystem::path &image, const ImportProgress &progress={})
 Decode a Pinnacle InstantCopy PDI image to temporary storage.
std::optional< std::size_t > UniqueGpuIndex (std::string_view active, std::span< const std::string > devices)
 Match the active adapter to one provider device, rejecting absent and ambiguous identities.
std::optional< std::uint64_t > StatmResidentPages (std::string_view text)
std::optional< std::uint64_t > SmapsGamePssBytes (std::string_view text, std::string_view executable)
void OpenRaceData (bool playSounds)
 Set the default configuration, the bindings, and the strings of the race, and open its sound, as the PC release does once at its start.
bool StartRaceMusic (const std::filesystem::path &directory, RaceMusicSource source, int musicTrack=-1)
 Add a user of the music of the races, as the PC release opens its music device.
void StopRaceMusic ()
 Drop a user of the music of the races.
void ShutdownRaceMusic ()
 Release all race music resources regardless of active users, before SDL audio shuts down.
void RestartRaceMusic ()
 Play the track of the race from its start, with the device of the music resumed.
void ShareRaceMusicPlayer (N64Audio *audio)
 Play the modules of the races through the player of the music of the menus, which mixes the channels of the console, instead of a player of their own.
std::size_t RenderRaceMusic (std::size_t frames)
 Render frames of the track that plays, without a device, for tests.
std::array< int, 2 > RaceVolumeLevels ()
int RaceTrack ()
std::vector< RaceCar > RaceCars ()
float RaceFieldOfView (float fovy, float aspect, float scale=1.0f)
 The vertical field of view of a view of the race on a frame.
std::optional< std::vector< std::uint8_t > > ReadWholeFile (const std::filesystem::path &path)
 Reads a whole file with one read of its size.
std::expected< Script, ScriptError > ParseScript (std::string_view text)
 Read a script of run-script: one command a line, with # starting a comment and blank lines ignored.
std::optional< std::vector< std::uint8_t > > ReadSaveFile (const std::filesystem::path &path, std::size_t limit)
 Read a complete regular file without allocating beyond a caller-supplied limit.
bool WriteSaveFile (const std::filesystem::path &path, std::span< const std::uint8_t > bytes)
 Lock and atomically replace a binary save.
bool WriteSaveFile (const std::filesystem::path &path, std::string_view text)
 Lock and atomically replace a text save.
std::optional< std::vector< std::uint8_t > > ReadVerifiedSaveFile (const std::filesystem::path &path, std::size_t limit, bool resetInvalid=true, const SavePayloadValidator &validate={})
 Read an internal binary save with its format signature, payload length, and SHA-1 checksum.
bool WriteVerifiedSaveFile (const std::filesystem::path &path, std::span< const std::uint8_t > bytes)
 Atomically write an internal binary save with a format signature, length, and SHA-1 checksum.
Matrix4 MultiplyMatrices (const Matrix4 &a, const Matrix4 &b)
std::optional< MorphPose > PoseAtTime (const VertexAnimationInfo &animation, float time)
 The pose of a vertex animation at a time, as the console blends its keys.
std::map< unsigned, std::string > ReadLibraryStrings (std::span< const std::uint8_t > image)
 Read the string resources of a Windows library.
void AppendUtf8 (std::string &text, char32_t c)
 Append a code point to UTF-8 text.
char32_t NextCodePoint (std::string_view text, std::size_t &position)
 Decode the code point of UTF-8 text at a position, and step past it.
const std::string * FindString (std::string_view key)
std::string_view GameString (std::string_view key)
constexpr int EngineTrackForMenu (int track)
constexpr int MenuTrackForEngine (int track)
int LoadedTextureMapEntries ()
unsigned ConvertedVertexCount ()
std::vector< std::array< float, 3 > > CarDentOffsets (const VehicleModel *model, std::span< const std::array< float, 3 > > rest)
 How far DeformVehicleMeshByImpact() has moved each vertex of a car from where it rested when the car loaded, by the position it rested at.
std::expected< GltfModel, std::string > TrackPreviewToGltf (const GltfModel &track, std::string_view bufferUri)
 Generate a static menu miniature from a converted track during import.
std::optional< std::string > ConvertIntroMedia (const std::filesystem::path &directory, const ImportProgress &progress={})
 Convert optional disc intro media.
constexpr int RaceVolumeLevel (int level)
constexpr int MenuVolumeLevel (int raceLevel, int level)
 The level of the options menu after the pause menu of a race changed the level of the race engine.
void AttachParentConsole ()
 Attach to an existing parent console and reconnect unavailable standard streams.
std::optional< std::string > VisitZipEntries (const std::filesystem::path &archive, const std::function< bool(const std::string &, std::uint32_t)> &accept, const std::function< bool(const std::string &, std::vector< std::uint8_t > &)> &visit, const std::function< bool(const std::string &, double)> &progress={})
 Visit CRC-checked stored and deflated entries in a ZIP archive without extracting archive paths.
std::optional< std::string > VisitZipRoms (const std::filesystem::path &archive, const std::function< bool(std::vector< std::uint8_t > &)> &visit, const std::function< bool(const std::string &, double)> &progress={})
 Visit CRC-checked ROM entries in a ZIP archive without extracting archive paths.

Variables

constexpr std::string_view BOSS_PACK = "boss"
 The name of the pack of the PC images the default pack replaces with branded images.
constexpr int PACK_SETTINGS_VERSION = 1
 The version of pack.json the import writes.
constexpr float DEFAULT_XM_MUSIC_GAIN = 1.5f
 The gain of the music modules of the default pack, as they play quieter than the CD audio.
constexpr const char * ASSET_ALIASES_FILE = "asset-aliases.txt"
 The alias-table filename for logical paths and their physical backing files.
const std::array< ConsoleString, 147 > CONSOLE_STRINGS
 The messages the Japanese release draws in Japanese and the messages the other releases draw in their place, then the messages of the race that a string of BRString.dll draws in the PC release, paired across the releases by the code that draws them.
const std::array< SaveFolderString, 10 > SAVE_FOLDER_STRINGS
 The messages of the console that name the Controller Pak where the game saves to a folder, as the import writes them to strings/en-us.json with the text of the USA cartridge.
constexpr std::size_t LIBRARY_STRING_COUNT = 303
 The number of strings of BRString.dll, numbered from 1.
const std::array< std::string_view, LIBRARY_STRING_COUNT > LIBRARY_STRING_KEYS
 The key of each string of BRString.dll, by its number less 1.
constexpr std::size_t CONTROLLER_PORTS = 4
 The number of controller ports of the console.
constexpr std::size_t PAK_PAGE_BYTES = 0x100
 The bytes of a page of a Controller Pak, the unit a note takes its room in.
constexpr std::size_t PAK_PAGES = 123
 The pages of a Controller Pak free for notes.
constexpr std::size_t PAK_NOTES = 16
 The notes a Controller Pak has room for.
constexpr std::string_view PAK_SETTINGS_NOTE = "TOP GEAR OPTIONS"
 The note of the settings of the options menu, stored with the settings of the game.
constexpr std::size_t PAK_IMAGE_BYTES = 0x8000
 The bytes of the image of a Controller Pak, as emulators and the tools of a pak store one.
constexpr std::array< std::string_view, CONTROL_ACTION_COUNT > CONTROL_KEYS
 The keys of the Controls section, by ControlAction.
constexpr std::string_view CONTROL_PRESET_KEY = "Preset"
 The key of the Controls section that chooses a preset.
constexpr std::string_view DEAD_ZONE_KEY = "DeadZone"
 The key of the Controls section with the share of the travel of an axis that reads as 0.
constexpr std::array< std::string_view, 2 > PLAYER_DEVICE_KEYS {"Player1", "Player2"}
 The keys of the Controls section that choose the input device of each player.
constexpr ControlPreset DEFAULT_CONTROL_PRESET
 The preset of an absent or unknown Preset key.
constexpr std::size_t RACE_CONTROL_ACTIONS = CONTROL_CHASE_CAMERA + 1
 The actions of a race, from CONTROL_STEER_LEFT to CONTROL_CHASE_CAMERA.
constexpr std::array< ControlPreset, 7 > CONTROL_PRESETS
 The presets the Preset key chooses from, the first the default.
constexpr int CONTROL_FULL = 32768
 The magnitude of a button held down or of an axis at its end.
constexpr int DECAL_SLOTS = 10
 The decals of a car, each the texture of the material of the same number.
constexpr int CAR_MATERIALS = 12
 The materials of a car whose palettes the colour of the car paints.
constexpr int CAR_MATERIAL_PAINT = 2
 The material whose palette is the paint, saved with the decals.
constexpr int CAR_MATERIAL_HEADLIGHTS = 10
 The material whose palette is the headlights.
constexpr int CAR_MATERIAL_REAR_LIGHTS = 11
 The material whose palette is the rear lights.
constexpr std::array< std::string_view, 19 > DISC_IMAGE_EXTENSIONS
 Disc images, track metadata, and companion files accepted by the importer.
constexpr int WIZARD_CARTRIDGES = 3
 The number of supported ROM releases.
constexpr int GRID_WIDTH = GRID_COLUMNS * CELL_WIDTH
 The width of the grid in pixels, 640.
constexpr int GRID_HEIGHT = GRID_ROWS * CELL_HEIGHT
 The height of the grid in pixels, 400.
constexpr int GRID_COLUMNS = 80
 The columns of the grid.
constexpr int GRID_ROWS = 25
 The rows of the grid.
constexpr int CELL_WIDTH = 8
 The width of a cell in pixels.
constexpr int CELL_HEIGHT = 16
 The height of a cell in pixels.
constexpr std::array< std::array< std::uint8_t, 3 >, 16 > CGA_PALETTE
 The red, green, and blue of each colour of CGA, by its number.
constexpr std::uint8_t REPLACEMENT_GLYPH = 0
 The glyph drawn for a character code page 437 does not have.
constexpr float HALF_PI = 1.570796371f
 A quarter turn in radians, in the single precision of the console.
constexpr float PI = 3.141592741f
 A half turn in radians, in the single precision of the console.
constexpr float TWO_PI = 6.283185482f
 A whole turn in radians, in the single precision of the console.
constexpr float SCREEN_WIDTH = 320.0f
 The low-resolution screen of the console, in pixels.
constexpr float SCREEN_HEIGHT = 240.0f
 The height of the low-resolution console screen, in pixels.
constexpr std::size_t SOUND_PADDING = 0x100
 The silence after each sound, for the mixer to read zeros past its end.
constexpr std::uint64_t SFX_STEP_ONE = 1ull << 32
 The 32.32 step that plays a sample at its own rate.
constexpr u8 MAX_SFX_VOLUME = 0xFF
 The volume of the sound effects at full level.
constexpr std::uint32_t COMBINED = 0
 The previous cycle's result as an RDP colour-combiner input.
constexpr std::uint32_t TEXEL0 = 1
 The first sampled texel as an RDP colour-combiner input.
constexpr std::uint32_t TEXEL1 = 2
 The second sampled texel as an RDP colour-combiner input.
constexpr std::uint32_t PRIMITIVE = 3
 The primitive colour as an RDP colour-combiner input.
constexpr std::uint32_t SHADE = 4
 The interpolated vertex colour as an RDP colour-combiner input.
constexpr std::uint32_t ENVIRONMENT = 5
 The environment colour as an RDP colour-combiner input.
constexpr std::uint32_t ZERO_AB = 15
 The zero selector for the A and B RDP colour-combiner operands.
constexpr std::uint32_t ZERO_D = 7
 The zero selector for the D RDP colour-combiner operand.
constexpr std::uint32_t ZERO_ALPHA = 7
 The zero selector for an RDP alpha-combiner operand.
constexpr std::array< std::string_view, 7 > STAGE_CAR_PARTS
 The parts of a car RenderVehicleModel() draws in the menus: the near detail, the textured parts, the painted body, and the normal wheels.
const Lighting STAGE_CAR_LIGHTING
 The lights RenderVehicleModel() lights a car with in the menus: g_DefaultLights, from (84, 84, 84), in the colours of SetupWeatherLights() in clear weather.
constexpr std::size_t GHOST_NOTE_SIZE = 0x3A00
 The size of the note of a ghost car, 58 pages.
constexpr std::size_t GHOST_RECORDING_CAPACITY = 0xDE5C
 The capacity of the recording of the console, its header included.
constexpr UsaMusicModule USA_MUSIC_MODULES []
 The music modules of the USA cartridge: the menus, then the modules of the tracks.
constexpr int DISC_CONVERTER_VERSION = 2
 The version of the conversion of the Boss Rally disc: the cars, the tracks, the images, and the other files ImportDisc() converts, n64model.cpp included.
constexpr int CARTRIDGE_CONVERTER_VERSION = 1
 The version of the conversion of a Top Gear Rally cartridge: the models, the images, the music, and the other files ImportRom() converts, n64model.cpp included.
constexpr std::string_view DEFAULT_LANGUAGE = "en-us"
 The language unless the configuration or the command line selects another.
constexpr u32 MENU_ITEM_ADJUSTABLE = 0x01
 The flag of an item whose up and down change it in place, as MenuResult::Up and Down.
constexpr u32 MENU_ITEM_IMMEDIATE = 0x02
 The flag of an item chosen at once, without fading the screen out.
constexpr u32 MENU_ITEM_SPINNING = 0x04
 The flag of an item drawn as its model spinning round as the items slide.
constexpr u32 MENU_ITEM_UNAVAILABLE = 0x08
 The flag of an item that cannot be chosen, whose screen explains why.
constexpr u32 MENU_ITEM_MIRRORED_MODEL = 0x10
 The flag of an item whose model is drawn mirrored.
constexpr u32 MENU_ITEM_FIRST_PLAYER = 0x20
 The flag of an item only the first player may choose.
constexpr u32 MENU_ITEM_LOCKED = 0x80000000
 The flag of an item that cannot be chosen, without a reason shown.
constexpr int N64_AUDIO_RATE = 21998
 The sample rate of the imported music, in stereo frames per second.
constexpr std::string_view DEFAULT_PACK = "default"
 The name of the asset pack of the import, the directory assets/default.
constexpr int FRAME_RATE_STATES = 3
 The states of F in g_bShowFpsCounter: 0 for off, 1 for the frame rate, and 2 for both.
constexpr int FRAME_RATE_STATISTICS = 2
 The state of F in g_bShowFpsCounter that shows the statistics beside the frame rate.
constexpr int PC_RECORD_TRACKS = 15
 Track record slots in race-engine order, including the SDL Bonus Track.
constexpr int RESULT_LAPS = 12
 The most laps of a race the results record.
constexpr int SCRIPT_PRESS_FRAMES = 6
 The frames a press of a button or a key lasts when its line gives no number.
constexpr Matrix4 IDENTITY_MATRIX {1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1}
 The matrix that changes nothing.
constexpr std::array< std::array< float, 3 >, 4 > CLEAR_LIGHT_RAMP
 The ambient colours of a ramped instance of a track on a clear day, from 0 to 1.
constexpr std::size_t MAX_CAR_SHADOWS = 4
 The most shadows of cars that fall on an instance of a track.
constexpr int CAR_DAMAGE_SIDES = 8
 The number of sides of a car that take damage, as IncrementDamageTextureLevel() counts them.
constexpr int CAR_DAMAGE_LEVELS = 3
 The levels of damage of a car after the first, as LoadCarPaintTextures() makes them.
constexpr int CONSOLE_TRACK_COUNT = 10
 Five console tracks and their five mirrored variants precede additional tracks.
constexpr std::array< ExtraMenuTrack, 5 > EXTRA_MENU_TRACKS
 PC-only track entries; Season Champion (gamewin) remains indexed but unavailable for ordinary selection.
constexpr int MENU_TRACK_COUNT
 The number of track entries before menu actions, including unavailable entries.
constexpr int MAX_VOLUME_LEVEL = 10
 The loudest level of the options menu.
constexpr int MAX_RACE_VOLUME_LEVEL = 9
 The loudest level of the race engine.

Typedef Documentation

◆ WizardProgress

using coastline::WizardProgress = std::function<bool(const std::string &step, double fraction)>

Reports the step of an import and its share done from 0 to 1, and returns false to cancel.

◆ WizardSearchProgress

Initial value:
std::function<bool(const WizardSearchResult &, const std::string &, double)>
The images found during a directory search, indexed by detected release.
Definition setupwizard.h:91

Report search progress and return false to cancel.

◆ ImportProgress

using coastline::ImportProgress = std::function<bool(const std::string &step, double fraction)>

Reports import progress with a description and a fraction from 0 to 1.

It returns false to cancel the import before its next step.

◆ ImportJob

Independent import work in a private destination directory.

Report progress from zero to one and stop when the callback returns false. Return an error on failure, or an empty optional on success.

◆ StringTable

Strings by key, in UTF-8.

◆ NoteEquipmentCounts

Counts of handling, transmission, tyre, suspension, and controller-layout choices, in order.

◆ EnvironmentReader

Reads an environment variable, or nothing when it is unset or empty.

◆ SavePayloadValidator

Validate format-specific fields of an internal save's payload under its exclusive process lock.

Return false to reject the payload before it can be used by the game.

◆ Matrix4

using coastline::Matrix4 = std::array<float, 16>

A 4 by 4 matrix, column by column.

◆ CarDamage

The levels of damage of the sides of a car, each from 0 for none to CAR_DAMAGE_LEVELS.

Enumeration Type Documentation

◆ ControllerButton

The buttons of a Nintendo 64 controller, with the bits libultra reports.

Enumerator
BUTTON_C_RIGHT 

C right.

BUTTON_C_LEFT 

C left.

BUTTON_C_DOWN 

C down.

BUTTON_C_UP 

C up.

BUTTON_R 

The right shoulder.

BUTTON_L 

The left shoulder.

BUTTON_D_RIGHT 

The directional pad right.

BUTTON_D_LEFT 

The directional pad left.

BUTTON_D_DOWN 

The directional pad down.

BUTTON_D_UP 

The directional pad up.

BUTTON_START 

Start.

BUTTON_Z 

The Z trigger.

BUTTON_B 

B.

BUTTON_A 

A.

◆ PakRelease

enum class coastline::PakRelease
strong

The release of the cartridge whose game code and company code the notes of an image take.

Enumerator
Usa 

NGRE and 5D.

Eur 

NTRP and 7F.

Jpn 

NTRJ and 28.

◆ ControlAction

The actions of a gamepad the Controls section of BossRally.ini binds, in the order of keys.

Enumerator
CONTROL_STEER_LEFT 

Steer left in a race.

CONTROL_STEER_RIGHT 

Steer right in a race.

CONTROL_ACCELERATE 

Accelerate in a race.

CONTROL_BRAKE 

Brake in a race.

CONTROL_REVERSE 

Reverse in a race.

CONTROL_GEAR_UP 

Change up a gear in a race.

CONTROL_GEAR_DOWN 

Change down a gear in a race.

CONTROL_COCKPIT_CAMERA 

Choose the cockpit camera in a race.

CONTROL_BUMPER_CAMERA 

Choose the bumper camera in a race.

CONTROL_CHASE_CAMERA 

Choose the chase camera in a race.

CONTROL_PAUSE_MENU_UP 

Move up the pause menu of a race.

CONTROL_PAUSE_MENU_DOWN 

Move down the pause menu of a race.

CONTROL_PAUSE_MENU_SELECT 

Choose an item of the pause menu of a race.

CONTROL_PAUSE 

Pause a race.

CONTROL_START_OR_RESPAWN 

Start a race, and reset the car with a double press.

CONTROL_MENU_A 

The A button of the menus.

CONTROL_MENU_B 

The B button of the menus.

CONTROL_MENU_Z 

The Z trigger of the menus.

CONTROL_MENU_START 

The Start button of the menus.

CONTROL_MENU_L 

The left shoulder of the menus.

CONTROL_MENU_R 

The right shoulder of the menus.

CONTROL_MENU_C_UP 

C up of the menus.

CONTROL_MENU_C_DOWN 

C down of the menus.

CONTROL_MENU_C_LEFT 

C left of the menus.

CONTROL_MENU_C_RIGHT 

C right of the menus.

CONTROL_MENU_D_UP 

The directional pad up of the menus.

CONTROL_MENU_D_DOWN 

The directional pad down of the menus.

CONTROL_MENU_D_LEFT 

The directional pad left of the menus.

CONTROL_MENU_D_RIGHT 

The directional pad right of the menus.

CONTROL_MENU_STICK_LEFT 

The stick of the menus to the left.

CONTROL_MENU_STICK_RIGHT 

The stick of the menus to the right.

CONTROL_MENU_STICK_UP 

The stick of the menus up.

CONTROL_MENU_STICK_DOWN 

The stick of the menus down.

CONTROL_ACTION_COUNT 

The number of actions.

◆ WizardCartridge

enum class coastline::WizardCartridge
strong

A supported ROM release.

Enumerator
Usa 

The USA release.

Eur 

The European release.

Jpn 

The Japanese release.

◆ WizardKey

enum class coastline::WizardKey
strong

A key of the keyboard the wizard reads.

Enumerator
Tab 

Tab, or Shift and Tab.

Enter 

Enter.

Space 

Space.

Escape 

Escape.

Up 

The up arrow.

Down 

The down arrow.

Left 

The left arrow.

Right 

The right arrow.

PageUp 

Page Up.

PageDown 

Page Down.

Home 

Home.

End 

End.

Backspace 

Backspace.

Delete 

Delete.

SelectAll 

Select the entire text.

DeleteWord 

Delete the previous word.

DeleteNextWord 

Delete the next word.

WordLeft 

Move to the previous word.

WordRight 

Move to the next word.

◆ WizardScreen

enum class coastline::WizardScreen
strong

A screen of the wizard, in order.

Enumerator
Reimport 

Explain incompatible assets and offer setup or quit.

SourceSelection 

Choose directory search or manual paths and optional portable storage.

Files 

The disc and three interchangeable ROM paths.

SearchDirectory 

The directory to search.

Search 

Search progress and discovered images.

Import 

The import and its progress.

Done 

The end, with Finish.

◆ WizardEnd

enum class coastline::WizardEnd
strong

How the wizard ended.

Enumerator
Running 

The wizard shows.

Quit 

The user quit.

Finished 

The data was imported and Finish was pressed.

◆ WizardControlId

enum class coastline::WizardControlId
strong

A control of a screen or a dialog of the wizard.

Enumerator
DiscText 

The path of the disc image.

DiscBrowse 

Browse for the disc image.

DiscClear 

Clear the disc path.

Rom1Text 

The first ROM path.

Rom2Text 

The second ROM path.

Rom3Text 

The third ROM path.

Rom1Browse 

Browse for the first ROM image.

Rom2Browse 

Browse for the second ROM image.

Rom3Browse 

Browse for the third ROM image.

Rom1Clear 

Clear the first ROM path.

Rom2Clear 

Clear the second ROM path.

Rom3Clear 

Clear the third ROM path.

SearchAssets 

Open the directory search.

SpecifyPaths 

Open manual disc and ROM path entry.

Portable 

Store imported assets and settings beside the distribution.

SearchText 

The directory path.

SearchBrowse 

Browse for a directory.

SearchClear 

Clear the directory path.

StartSearch 

Start searching.

RetrySearch 

Search another directory.

UseFound 

Return to the setup fields.

Back 

The previous screen.

Next 

The next screen.

Quit 

Quit without importing assets.

Cancel 

Cancel the import.

Finish 

Start the game.

BrowserList 

The entries of the directory of the file browser.

BrowserFilter 

The kinds of file the browser lists.

BrowserOk 

Open or choose the entry of the browser.

BrowserUseDirectory 

Choose the current directory as the disc source.

BrowserCancel 

Close the browser.

MessageOk 

Close a message.

MessageYes 

Quit the wizard.

MessageNo 

Do not quit the wizard.

◆ CgaColor

enum class coastline::CgaColor : std::uint8_t
strong

The 16 colours of CGA, by their number.

Enumerator
Black 

RGB #000000.

Blue 

RGB #0000AA.

Green 

RGB #00AA00.

Cyan 

RGB #00AAAA.

Red 

RGB #AA0000.

Magenta 

RGB #AA00AA.

Brown 

RGB #AA5500.

LightGray 

RGB #AAAAAA.

DarkGray 

RGB #555555.

LightBlue 

RGB #5555FF.

LightGreen 

RGB #55FF55.

LightCyan 

RGB #55FFFF.

LightRed 

RGB #FF5555.

LightMagenta 

RGB #FF55FF.

Yellow 

RGB #FFFF55.

White 

RGB #FFFFFF.

◆ ScaleFilter

enum class coastline::ScaleFilter
strong

How the frame is scaled to the window.

Enumerator
Linear 

Each pixel of the window blends the nearest four of the frame.

Nearest 

Each pixel of the window takes the nearest pixel of the frame.

EdgeAdaptive 

A directional reconstruction filter follows edges of the frame.

◆ TextureFilter

enum class coastline::TextureFilter
strong

How the textures the game filters are filtered.

Enumerator
N64 

Three texels, as the RDP of the Nintendo 64 filters.

Modern 

Four texels, bilinear, and trilinear and anisotropic with mipmaps.

Nearest 

The nearest texel, unfiltered.

◆ PostAntialias

enum class coastline::PostAntialias
strong

The anti-aliasing of the finished frame, before it is scaled to the window.

Enumerator
None 

The frame as the scene drew it.

Fxaa 

Fast approximate anti-aliasing blends along the edges it finds.

◆ ScreenShader

enum class coastline::ScreenShader
strong

Display simulation applied after the internal frame is scaled to the window.

Enumerator
None 

Display the scaled frame without a CRT simulation.

ConsumerCrt 

Simulate a consumer television with scanlines and a shadow mask.

Pvm 

Simulate a professional video monitor.

ApertureGrille 

Simulate an aperture-grille television.

PcCrt 

Simulate a progressive PC monitor.

◆ HdrOutput

enum class coastline::HdrOutput
strong

Whether HDR output follows the window, is requested, or is disabled.

Enumerator
Auto 

Use HDR when the window reports additional display headroom.

On 

Request HDR when the swapchain supports it.

Off 

Use SDR output.

◆ RomRelease

enum class coastline::RomRelease
strong

A Nintendo 64 release the game reads models, textures, and music from.

Enumerator
Usa 

North America, NGRE.

Jpn 

Japan, NTRJ.

Eur 

Europe, NTRP.

Asia 

Asia, NGRX.

◆ ImportSource

enum class coastline::ImportSource
strong

A source of the data of the default pack.

Enumerator
Disc 

The Boss Rally disc.

Usa 

The USA cartridge.

Jpn 

The Japanese cartridge.

Eur 

The European cartridge.

Asia 

The Asian cartridge.

◆ IntroEnd

enum class coastline::IntroEnd
strong

Where the splash screens go once they fade out.

Enumerator
Running 

The splash screens are still showing.

MainMenu 

The player skipped them, for the main menu.

AttractDemo 

They ran to their end, for the demo of a race.

◆ MenusEnd

enum class coastline::MenusEnd
strong

Where the menus go next.

Enumerator
Running 

A menu screen is still showing.

Quit 

Two Escape presses request an application exit.

Splash 

The player went back from the main menu, or it timed out.

AttractDemo 

The asset pack starts a demonstration after main-menu inactivity.

Race 

The race of Menus::ChosenRace() starts.

Credits 

The race of the credits of the options menu starts.

ApplySettings 

Apply pending settings after the options fade out.

Reinitialize 

Reload game resources and return to the logos.

◆ GameMode

enum class coastline::GameMode
strong

The modes of the game, as g_dwGameMode of the console.

Enumerator
Championship 

The races of a season of the championship.

Arcade 

A race against the clock and the gates.

TimeAttack 

A time attack against the ghost car.

Practice 

A race alone.

◆ MenuResult

enum class coastline::MenuResult
strong

What a frame of a menu screen ends with, the results of ProcessScreenState().

Enumerator
None 

The screen is still showing.

Chosen 

The player chose the item under the cursor.

Cancelled 

The player exited the screen, or it timed out.

Up 

The player pushed up on an adjustable item.

Down 

The player pushed down on an adjustable item.

◆ MipsRegister

The numbers of the general registers the calling convention gives a role.

Enumerator
MIPS_ZERO 

Always zero.

MIPS_V0 

The first word of a return value.

MIPS_V1 

The second word of a return value.

MIPS_A0 

The first argument.

MIPS_A1 

The second argument.

MIPS_A2 

The third argument.

MIPS_A3 

The fourth argument.

MIPS_SP 

The stack pointer.

MIPS_RA 

The return address.

◆ N64DemoRelease

enum class coastline::N64DemoRelease
strong

A release of the cartridge whose demo is recorded.

Enumerator
Usa 

North America.

Jpn 

Japan.

Eur 

Europe, whose race steps at 25 Hz.

◆ PaintTool

The tools of the paint shop, each a button, as the console numbers them.

Enumerator
PAINT_TOOL_BRUSH_SIZE 

The buttons that pick the size of the brush.

PAINT_TOOL_BRUSH 

The brush, painting round or square dots.

PAINT_TOOL_FILL 

The flood fill.

PAINT_TOOL_LINE 

A straight line from an anchor to the cursor.

PAINT_TOOL_TEXT 

A text typed on the keyboard of the font of the decals.

PAINT_TOOL_RECTANGLE 

A rectangle in one of four styles.

PAINT_TOOL_OVAL 

An ellipse or a circle in one of four styles.

PAINT_TOOL_MIRROR 

The menu that mirrors or flips the decal.

PAINT_TOOL_CLEAR 

The menu that fills or clears the decal.

PAINT_TOOL_LOAD 

The dialog that loads decals from the Controller Pak.

PAINT_TOOL_SAVE 

The dialog that saves decals to the Controller Pak.

PAINT_TOOL_UNDO 

Undo the last edit and return to the tool before.

PAINT_TOOL_EXIT 

The dialog that confirms the exit from the paint shop.

PAINT_TOOLS 

The number of tools.

◆ RaceMusicSource

enum class coastline::RaceMusicSource
strong

Where the music of a race comes from.

Enumerator
Modules 

The XM modules of the Nintendo 64 release, the default.

CdAudio 

The FLAC files the import made of the CD audio of the PC release.

◆ RaceEnd

enum class coastline::RaceEnd
strong

How a race ends.

Enumerator
Running 

The race goes on.

Results 

The race finished with results, for the results screen.

Menu 

The race was abandoned or had no results, for the main menu.

SeasonMenu 

The race after a season ended, for the next season of the championship.

Credits 

The race after the last season ended, for the ending credits and then the next season of the championship.

◆ ScriptMouseButton

enum class coastline::ScriptMouseButton
strong

The button of the mouse a move holds down.

Enumerator
None 

No button.

Left 

The left button.

Right 

The right button.

Function Documentation

◆ ImportAssetImages()

std::optional< std::string > coastline::ImportAssetImages ( const std::filesystem::path & data,
const std::filesystem::path & disc,
std::span< const std::filesystem::path > roms,
const ImportProgress & progress = {},
std::vector< std::filesystem::path > * sources = nullptr )

Import a disc and every supplied ROM as one batch.

USA is the base when supplied; otherwise the first ROM is the base. Failed or cancelled conversions preserve installed packs. A successful batch replaces generated packs and preserves mod packs. Each additional cartridge produces a regional difference pack over the base. Language fonts and strings remain available independently of the selected region.

Parameters
dataThe data root where generated packs are installed under assets.
discA Boss Rally disc image or mounted disc directory.
romsTop Gear Rally ROM images, with at most one image per region.
progressReport batch progress, or empty. Return false to cancel before installation.
sourcesReceives original input files and searched directories on success, or null.
Returns
An error, or nothing after installation and inventory validation.

◆ WriteImportDependencies()

std::optional< std::string > coastline::WriteImportDependencies ( const std::filesystem::path & file,
const std::filesystem::path & target,
std::span< const std::filesystem::path > sources )

Write a GCC-style dependency file atomically for a completed asset import.

Paths become absolute UTF-8 paths with sorted, unique dependencies. Line breaks and tabs cannot be represented; literal backslashes are also rejected on POSIX.

Parameters
fileThe dependency output file.
targetThe build output depending on imported sources.
sourcesOriginal input files and searched directories.
Returns
An error, or an empty optional after writing the dependency file.

◆ CurateAssetPacks()

std::optional< std::string > coastline::CurateAssetPacks ( const std::filesystem::path & defaults)

Put the images of the cartridges that show the branding the PC release removed (Nintendo, Top Gear, and Kemco) in place of their PC images in the default pack, and move the PC images to the pack boss beside it.

The images are listed in data/branded-textures.json. An image whose model has another image of the PC release in the same file takes a file of its own, and the primitives of the listed meshes sample it; the original model moves to boss. An image whose cartridge or disc is not yet imported is skipped, and an image already in place is not written again. Each file written is read back and compared. The default pack and boss also take their pack.json.

Parameters
defaultsThe directory of the default pack, assets/default of the data directory.
Returns
A message, or nothing.

◆ PackSettings()

nlohmann::json coastline::PackSettings ( const std::filesystem::path & data,
std::string_view pack,
const std::filesystem::path & fallback = {} )

Read default settings from pack.json and replace matching keys with selected pack settings.

Missing or malformed files do not contribute keys.

Parameters
dataThe data directory of the game.
packThe name of the pack.
fallbackAnother data root searched for the selected pack, or empty. Default settings still come from data.
Returns
The settings, an object.

◆ DeduplicateAssetFiles()

std::expected< AssetStorageSavings, std::string > coastline::DeduplicateAssetFiles ( const std::filesystem::path & defaults)

Replace byte-identical generated files with aliases.

Files shared by multiple non-default packs move into default/shared. Mod packs are excluded. Call before recording the inventory.

Parameters
defaultsThe freshly converted default pack, without an alias table.
Returns
Storage savings, or an error. Discard staged packs after a failure.

◆ FinalizeGeneratedAssetPacks()

std::optional< std::string > coastline::FinalizeGeneratedAssetPacks ( const std::filesystem::path & defaults)

Remove empty subdirectories and write permissions from generated packs, excluding mod packs.

Preserve pack roots and reject symbolic links encountered during finalisation. Call after installation and inventory validation, with rollback available on failure.

Parameters
defaultsThe completed default pack beside other generated packs.
Returns
An error if a pack cannot be finalised, or an empty optional on success.

◆ RemoveAssetTree()

void coastline::RemoveAssetTree ( const std::filesystem::path & path,
std::error_code & error )

Delete a tree after restoring directory owner-write permissions, without following symlinks.

Windows files also have their read-only attribute cleared before deletion.

Parameters
pathThe file, directory, or symlink to delete; missing paths are accepted.
errorReceives a filesystem error, or is cleared on success.

◆ ReadAssetFileAliases()

std::expected< std::vector< AssetFileAlias >, std::string > coastline::ReadAssetFileAliases ( const std::filesystem::path & pack,
const std::filesystem::path & defaults )

Read and validate an alias table, including its physical targets.

Targets never refer to aliases or to another optional pack.

Parameters
packThe physical pack directory.
defaultsThe physical default pack directory.
Returns
Aliases, an empty vector without a table, or an error for unreadable or invalid metadata.

◆ ParseAspectRatio()

std::optional< float > coastline::ParseAspectRatio ( std::string_view text)

Read a finite, positive aspect ratio or an automatic-sizing setting.

Parameters
textEmpty text, auto (case-insensitive), a ratio such as 4:3, or a number such as 1.6.
Returns
Width divided by height, 0 for empty text or auto, or std::nullopt for invalid input.

◆ ExpandInternalResolution()

std::array< int, 2 > coastline::ExpandInternalResolution ( int width,
int height,
float aspect )

Expand a resolution to an aspect ratio, with minimum dimensions of 320x240.

Each dimension is limited to 16384 pixels, even when the requested ratio requires more.

Parameters
widthThe requested internal width, in pixels.
heightThe requested internal height, in pixels.
aspectThe output width divided by height; invalid ratios only clamp the dimensions.
Returns
The expanded width and height, in pixels.

◆ ScaleFrameResolution()

std::array< int, 2 > coastline::ScaleFrameResolution ( int width,
int height,
float scale,
float aspect )

Scale window dimensions and fit an aspect ratio before bounded integer conversion.

Parameters
widthWindow width in pixels; non-positive values become 1.
heightWindow height in pixels; non-positive values become 1.
scaleRender scale, clamped to [0.25, 4]; non-finite values use 1.
aspectWidth divided by height; non-finite or non-positive values follow the window.
Returns
Rounded dimensions in [1, 16384], without overflowing for extreme inputs.

◆ ExportPakImage()

std::optional< std::string > coastline::ExportPakImage ( const ControllerPak & pak,
const std::filesystem::path & file,
PakRelease release = PakRelease::Usa )

Write the notes of a pak as the image of a formatted Controller Pak, with the game code and the company code of a release on each note.

An image of four paks of 0x20000 bytes, as mupen64plus writes one, takes the notes in its first pak, and its other paks are retained. Another file is replaced by an image of one pak.

Parameters
pakThe pak of the notes.
fileThe image.
releaseThe release whose cartridge reads the notes.
Returns
Nothing once the image is written, or the reason it was not.

◆ ImportPakImage()

std::optional< std::string > coastline::ImportPakImage ( const ControllerPak & pak,
const std::filesystem::path & file )

Copy the notes of any release of the game from the image of a Controller Pak, or from the first pak of an image of four, to a pak.

A note the pak has already is replaced and the replacement is logged. The notes of other games are skipped.

Parameters
pakThe pak the notes are written to.
fileThe image.
Returns
Nothing once the notes are written, or the reason they were not.

◆ RaceControlPreset()

ControlPreset coastline::RaceControlPreset ( std::string_view name,
const std::array< std::string_view, RACE_CONTROL_ACTIONS > & race )
constexpr
Parameters
nameThe value of the Preset key.
raceThe bindings of the actions of a race.
Returns
The default preset with the bindings of the actions of a race replaced.

◆ LoadControls()

void coastline::LoadControls ( const GameConfig & config)

Read the Controls section of config: the preset of the Preset key, the default for an absent or unknown preset, with each action key present replacing the binding of the preset, the device of each player, and the dead zone of the axes.

A name that is not a button or an axis of a gamepad is logged and ignored.

Parameters
configThe settings of BossRally.ini.

◆ PlayerDevice()

std::string_view coastline::PlayerDevice ( std::size_t player)
Parameters
playerThe player, 0 for the first.
Returns
The value of the Player1 or Player2 key in lowercase, auto when the key is absent or empty.

◆ IsControlAnalog()

bool coastline::IsControlAnalog ( ControlAction action)
Parameters
actionThe action.
Returns
Whether an axis drives the action.

◆ ReadControl()

int coastline::ReadControl ( SDL_Gamepad * gamepad,
ControlAction action )
Parameters
gamepadThe gamepad.
actionThe action.
Returns
The greatest magnitude of the sources of the action, 0 to CONTROL_FULL.

◆ TexelOffset()

int coastline::TexelOffset ( int x,
int y,
int width )
inline

The byte of a texel of a 4-bit texture as the console loads it in one block, the 64-bit words of each odd row swapped.

Parameters
xThe column.
yThe row.
widthThe width of the texture in texels.
Returns
The offset of the byte from the first texel.

◆ CreateDecodedDisc()

std::expected< DecodedDisc, std::string > coastline::CreateDecodedDisc ( bool raw,
std::uint64_t bytes )

Create private temporary storage for an ISO or raw-sector image.

Parameters
rawWhether the image uses raw CD sectors rather than cooked data sectors.
bytesRequired disk space in bytes.
Returns
Destination path for a new image and shared cleanup storage, or a diagnostic on failure.

◆ IsDiscImageExtension()

bool coastline::IsDiscImageExtension ( std::string_view extension)
constexpr

Check a lower-case filename extension, including its initial dot.

Parameters
extensionNormalised extension to test.
Returns
Whether the importer recognises the extension as a disc source.

◆ ReadDiscTracks()

std::expected< std::vector< CueTrack >, std::string > coastline::ReadDiscTracks ( const std::filesystem::path & disc,
const ImportProgress & progress = {},
std::vector< std::filesystem::path > * sources = nullptr )

Resolve tracks from CUE, ISO, BIN, numbered track files, CloneCD, DiscJuggler CDI, Nero NRG, Alcohol MDS, BlindWrite 4/5/6, Pinnacle PDI, or an unencrypted ISZ image.

Returned tracks and readers retain shared temporary storage for decoded images.

Parameters
discDisc image or metadata file. Adjacent CUE sheets precede BIN layout discovery.
progressDecoding progress, or empty. Return false to cancel image decoding.
sourcesOptional output, replaced on success by original metadata and data paths. Temporary decoded files are excluded. BIN discovery also records its directory.
Returns
Track extents, or a message when metadata is unreadable or a data track cannot be located. Container offsets and split-file extents exclude pregaps. Unknown BIN layouts with uncertain audio boundaries return only their data track.

◆ DownloadFile()

std::optional< std::string > coastline::DownloadFile ( const std::string & url,
const std::filesystem::path & output,
const ImportProgress & progress = {} )

Download an HTTPS URL to a file with the HTTP client of the operating system, following redirects.

Parameters
urlThe HTTPS URL.
outputThe file to write.
progressProgress and cancellation callback, or empty.
Returns
An error on failure or cancellation, or an empty optional when complete.

◆ CreateEngineTexture()

unsigned coastline::CreateEngineTexture ( const unsigned char * image,
const unsigned char * palette,
int width,
int height,
int lineBytes )

Create a texture from an 8-bit colour-indexed image of the console, as the hook g_pfnCreateTextureFromN64Image() of the PC release creates one.

Parameters
imageThe indices of the texels.
paletteThe 256 colours, each a big-endian RGBA5551 half.
widthThe width in texels.
heightThe height in texels.
lineBytesThe bytes of a row of the image.
Returns
The texture entry, from 1, or zero without an active EngineTextures instance.

◆ DecodeEngineTexture()

int coastline::DecodeEngineTexture ( void * destination,
const unsigned char * image,
const unsigned char * palette,
int width,
int height,
int lineBytes )

Decode an 8-bit colour-indexed image of the console to its colours, each a big-endian RGBA5551 half, as the hook g_pfnDecodeN64TextureToPixelBuffer() of the PC release decodes one.

Parameters
destinationReceives the colours, row by row.
imageThe indices of the texels.
paletteThe 256 colours, each a big-endian RGBA5551 half.
widthThe width in texels.
heightThe height in texels.
lineBytesThe bytes of a row of the image.
Returns
The bytes written.

◆ LoadEngineTexture()

void coastline::LoadEngineTexture ( unsigned entry,
const unsigned char * colors )

Load the decoded colours of an image into a texture, as a command 0xdd of a display list loads them.

Parameters
entryThe texture entry, from 1. Invalid entries are ignored.
colorsThe colours of its texels, each a big-endian RGBA5551 half, row by row.

◆ FindEngineTexture()

const EngineTexture * coastline::FindEngineTexture ( unsigned entry)
Parameters
entryThe entry of a texture.
Returns
The texture, or null for an invalid entry or without an active collection. The pointer remains valid until another texture is created or the collection is cleared.

◆ ClearEngineTextures()

void coastline::ClearEngineTextures ( )

Drop every texture, as the renderer of the PC release shuts its textures down.

◆ ListBrowserDirectory()

std::optional< std::vector< BrowserEntry > > coastline::ListBrowserDirectory ( const std::filesystem::path & directory,
std::span< const std::string_view > extensions,
bool directoriesOnly = false )

List a directory for the file browser: .. first, or on Windows the drives at the root of a drive, then the directories, then the files with one of extensions.

The directories and the files are each sorted by name without regard to case. An entry whose name starts with a full stop is hidden and not listed.

Parameters
directoryThe directory, absolute.
extensionsThe extensions of the files listed, lowercase with the full stop, such as .cue, or empty for every file.
directoriesOnlyWhether to omit files and list only navigable directories.
Returns
The entries, or nothing when the directory cannot be read.

◆ ResolveUserPath()

std::filesystem::path coastline::ResolveUserPath ( std::string_view text,
const std::filesystem::path & home )

Expand an initial home-directory shorthand and use native separators after expansion.

Parameters
textA UTF-8 path, optionally starting with '~', '~/', or '~\'.
homeThe directory substituted for the initial tilde, or empty to disable expansion.
Returns
The expanded native path; '~user' and embedded tildes are unchanged.

◆ PathFromUtf8()

std::filesystem::path coastline::PathFromUtf8 ( std::string_view text)
Parameters
textA path in UTF-8.
Returns
The path.

◆ LowercaseExtension()

std::string coastline::LowercaseExtension ( const std::filesystem::path & path)
Parameters
pathA path.
Returns
The extension of the path in ASCII lowercase, with the full stop, or empty.

◆ BaseCartridge()

std::optional< WizardCartridge > coastline::BaseCartridge ( const std::array< bool, WIZARD_CARTRIDGES > & checked)

Choose the base release for the default pack.

Prefer the USA release when detected, then the European release, then the Japanese release.

Parameters
checkedWhether each release is available, in the order of WizardCartridge.
Returns
The release, or nothing when no release is available.

◆ SearchWizardDirectory()

WizardSearchResult coastline::SearchWizardDirectory ( const std::filesystem::path & directory,
const WizardServices & services,
const WizardSearchProgress & progress )

Search recursively, including hidden directories, for validated disc and ROM images.

Parameters
directoryThe root directory to traverse.
servicesRequired disc and ROM validators, plus an optional ZIP validator.
progressReports discoveries and validation progress; return false to cancel.
Returns
Discoveries accumulated before completion, cancellation, or failure.

◆ AcceleratorOf()

char coastline::AcceleratorOf ( const std::string & label)
Parameters
labelA label with & before the letter of its accelerator.
Returns
The letter in lowercase, or 0 when the label has none.

◆ TextGridProjection()

Matrix4 coastline::TextGridProjection ( float aspect)
Parameters
aspectThe width of the frame over its height.
Returns
The matrix from the pixels of the grid to the frame, the grid fitted in the middle of the frame with bars at the sides or at the top and bottom.

◆ GridPointInWindow()

std::array< int, 2 > coastline::GridPointInWindow ( float windowWidth,
float windowHeight,
float frameAspect,
float x,
float y )

The place of the mouse on the grid, with the frame fitted to the window and the grid to the frame as TextGridProjection() fits it.

Parameters
windowWidthThe width of the window.
windowHeightThe height of the window.
frameAspectThe width of the frame over its height.
xThe mouse across the window, in the units of the window.
yThe mouse down the window, in the units of the window.
Returns
The place across and down the grid in pixels, outside it past its edges.

◆ Cp437FromCodepoint()

std::uint8_t coastline::Cp437FromCodepoint ( char32_t codepoint)
Parameters
codepointA Unicode code point.
Returns
The character of code page 437 that shows it, or REPLACEMENT_GLYPH.

◆ DecodeUtf8()

std::u32string coastline::DecodeUtf8 ( std::string_view text)
Parameters
textUTF-8 text. A byte that does not start a valid sequence reads as U+FFFD.
Returns
The code points of the text.

◆ EncodeUtf8()

std::string coastline::EncodeUtf8 ( std::u32string_view text)
Parameters
textUnicode code points.
Returns
The text in UTF-8.

◆ RunSetupWizard()

SetupRun coastline::RunSetupWizard ( GpuWindow & window,
GamePaths & paths,
GameConfig & config,
const Script & script,
std::span< const SDL_Scancode > scriptKeys,
const std::filesystem::path & captures,
bool fixedTime,
const std::string & reimportReason = {},
const std::filesystem::path & portableDirectory = {} )

Show the setup wizard until the user finishes or quits it.

Its import deletes the packs default, boss, eur, and jpn under assets of the data directory and imports the chosen files into the default pack. The wizard hides the cursor of the system and draws its own, and shows the cursor again when it ends. Disc, ROM, search, and last-browsed paths are restored from the SetupWizard section of config and updated on exit, including cancellation.

Parameters
windowThe window of the game.
pathsThe directories of the game, updated after a successful portable installation.
configThe settings of the game.
scriptThe run-script input, or an empty script. Scripted key presses, text input, and mouse movements operate wizard controls. Mouse coordinates on the 320 by 240 screen scale to the 640 by 400 grid.
scriptKeysThe scancode of each key of script, in order.
capturesThe directory the frames of the script are saved to.
fixedTimeWhether each frame steps the blink of the cursor by a 60th of a second.
reimportReasonWhy existing assets require another import, or empty for first-run setup.
portableDirectoryPortable destination, or empty to disable the installation checkbox.
Returns
How the wizard ended.

◆ SfxVolume()

std::uint32_t coastline::SfxVolume ( std::uint32_t right,
std::uint32_t left )
constexpr
Parameters
rightThe level of the right side, from 0 to 32.
leftThe level of the left side, from 0 to 32.
Returns
The levels of a sound effect channel, the right in the upper half and the left in the lower.

◆ CombineLerp()

std::array< std::uint32_t, 2 > coastline::CombineLerp ( std::uint32_t a0,
std::uint32_t b0,
std::uint32_t c0,
std::uint32_t d0,
std::uint32_t alphaA0,
std::uint32_t alphaB0,
std::uint32_t alphaC0,
std::uint32_t alphaD0,
std::uint32_t a1,
std::uint32_t b1,
std::uint32_t c1,
std::uint32_t d1,
std::uint32_t alphaA1,
std::uint32_t alphaB1,
std::uint32_t alphaC1,
std::uint32_t alphaD1 )
constexpr

The two words of gDPSetCombineLERP(), from the colour and alpha inputs of each cycle.

Parameters
a0The first cycle's colour operand A, masked to four bits.
b0The first cycle's colour operand B, masked to four bits.
c0The first cycle's colour multiplier C, masked to five bits.
d0The first cycle's colour addend D, masked to three bits.
alphaA0The first cycle's alpha operand A, masked to three bits.
alphaB0The first cycle's alpha operand B, masked to three bits.
alphaC0The first cycle's alpha multiplier C, masked to three bits.
alphaD0The first cycle's alpha addend D, masked to three bits.
a1The second cycle's colour operand A, masked to four bits.
b1The second cycle's colour operand B, masked to four bits.
c1The second cycle's colour multiplier C, masked to five bits.
d1The second cycle's colour addend D, masked to three bits.
alphaA1The second cycle's alpha operand A, masked to three bits.
alphaB1The second cycle's alpha operand B, masked to three bits.
alphaC1The second cycle's alpha multiplier C, masked to three bits.
alphaD1The second cycle's alpha addend D, masked to three bits.
Returns
The upper and the lower word of the combine command.

◆ Translation()

Matrix4 coastline::Translation ( float x,
float y,
float z )
Parameters
xThe horizontal displacement in model units.
yThe vertical displacement in model units.
zThe depth displacement in model units.
Returns
The translation matrix.

◆ Scale()

Matrix4 coastline::Scale ( float s)
Parameters
sThe scale multiplier applied equally to all three axes.
Returns
The uniform scaling matrix.

◆ RotationX()

Matrix4 coastline::RotationX ( float angle)
Parameters
angleThe rotation in radians about the x axis, following guRotateF().
Returns
The rotation matrix.

◆ RotationZ()

Matrix4 coastline::RotationZ ( float angle)
Parameters
angleThe rotation in radians about the z axis, following guRotateF().
Returns
The rotation matrix.

◆ ScreenExtent()

std::array< float, 2 > coastline::ScreenExtent ( float aspect)

The part of the frame the 4:3 screen of the menus covers, centred: the whole height of a frame wider than 4:3 and the whole width of a narrower one.

Parameters
aspectThe width of the frame over its height.
Returns
The width and the height of the screen over those of the frame, each at most 1.

◆ MenuProjection()

Matrix4 coastline::MenuProjection ( float aspect,
float nearPlane,
float farPlane,
const std::optional< Matrix4 > & camera = std::nullopt )

The camera of the menus, which looks at the middle of the 320 by 240 screen from 290 in front of it with a field of 45 degrees, onto the 4:3 screen centred in the frame, to a depth from 0 to 1.

Parameters
aspectThe width of the frame over its height.
nearPlaneThe nearest distance drawn.
farPlaneThe farthest distance drawn.
cameraOptional eye-space camera override; extends draw distance to the maximum.
Returns
The camera and its projection.

◆ FlatProjection()

Matrix4 coastline::FlatProjection ( float aspect)
Parameters
aspectThe width of the frame over its height.
Returns
The flat draws of the 640 by 480 screen, centred in the frame at 4:3 with y down.

◆ ScreenModelAt()

Matrix4 coastline::ScreenModelAt ( float x,
float y,
float z,
float angle,
float scale )

DrawModelAt() of the console: a model turned about its own axis, scaled, stood up, and placed.

The glTF of a model of the console is stood up from z up to y up, and this turns it back.

Parameters
xThe place across, in the space of the screen.
yThe place up.
zThe place forward.
angleThe turn about the axis of the model, in radians.
scaleThe scale.
Returns
The place of the model.

◆ StageCamera()

Matrix4 coastline::StageCamera ( float aspect,
const std::array< float, 3 > & eye,
int x,
int y,
int width,
int height,
const std::optional< Matrix4 > & camera = std::nullopt )

SetupCameraMatrix() of the console for the trackside camera of a stage of the menus.

The camera looks at the origin from an eye with z up, in a viewport of the 320 by 240 screen. The picture is moved and scaled to the rectangle of the viewport in the frame, where the screen is centred at 4:3.

Parameters
aspectThe width of the frame over its height.
eyeThe place of the camera, in the space of the race.
xThe left of the viewport.
yThe top of the viewport.
widthThe width of the viewport.
heightThe height of the viewport.
cameraOptional eye-space camera override; extends draw distance to the maximum.
Returns
The camera and its projection, to a depth from 0 to 1.

◆ StageFrameAt()

Matrix4 coastline::StageFrameAt ( float x,
float y,
float angle )

The frame of a car on a stage of the menus in the space of the console, facing an angle about z, 0.254 above the stage.

Parameters
xThe place across.
yThe place along.
angleThe direction the car faces, in radians.
Returns
The frame of the car.

◆ StageCarAt()

Matrix4 coastline::StageCarAt ( float x,
float y,
float angle )

The place of a car on a stage of the menus, facing an angle about z, 0.254 above the stage.

The frame of the car is turned back from the z up of the console to the y up of the glTF.

Parameters
xThe place across.
yThe place along.
angleThe direction the car faces, in radians.
Returns
The place of the car.

◆ StageReflection()

Reflection coastline::StageReflection ( const RenderTexture * texture,
const std::array< float, 3 > & eye )

The reflection of the sky on a car as RenderVehicleModel() sets it up for the trackside camera of the menus looking at the origin from an eye: the axes of guLookAtReflectF() from the heading of the camera, and the window of the tile turning with the heading.

Parameters
textureThe image of the sky.
eyeThe place of the camera.
Returns
The reflection.

◆ AddTriangle()

void coastline::AddTriangle ( std::vector< FlatVertex > & quads,
const StageVertex & a,
const StageVertex & b,
const StageVertex & c )

Add a shaded triangle to flat quads, as a quad whose last corner repeats its third.

Parameters
quadsThe corners of the quads.
aThe first corner.
bThe second corner.
cThe third corner.

◆ FrameRect()

SDL_Rect coastline::FrameRect ( Uint32 frameWidth,
Uint32 frameHeight,
int x,
int y,
int width,
int height )
Parameters
frameWidthThe width of the frame, in pixels.
frameHeightThe height of the frame, in pixels.
xThe left of a rectangle of the 320 by 240 screen.
yThe top of the rectangle.
widthThe width of the rectangle.
heightThe height of the rectangle.
Returns
The rectangle in pixels of the frame, where the screen is centred at 4:3.

◆ ReadLighting()

Lighting coastline::ReadLighting ( const nlohmann::json & light)
Parameters
lightThe lights of a screen in lights.json.
Returns
The lights, in the space of the console.

◆ ReadSound()

std::optional< std::vector< s8 > > coastline::ReadSound ( const std::filesystem::path & path)
Parameters
pathA sound of the import, an unsigned 8-bit WAV file.
Returns
The signed 8-bit samples of the sound, then SOUND_PADDING of silence, or nothing with the reason logged.

◆ PlaySoundEffect()

s16 coastline::PlaySoundEffect ( std::vector< s8 > & sample,
std::uint32_t volume )

Play a sound on a free sound effect channel.

Parameters
sampleThe samples, with the padding after them.
volumeThe levels of the channel, from SfxVolume().
Returns
The channel, or -1 when none is free.

◆ ApplyGraphicsPreset()

bool coastline::ApplyGraphicsPreset ( GameConfig & config,
std::string_view preset )

Apply a graphics preset without changing language or region.

N64 selects console music and BR selects PC CD music; other presets preserve the music source. N64 and BR select N64 and PC sound effects, respectively. N64 and BR select N64 and PC window reflections, respectively. N64 and BR select 4:3; Ultra fills the screen. Other presets preserve the aspect ratio.

Parameters
configThe configuration to update in memory.
presetcustom, n64, br, ultra, worst, or low-power.
Returns
Whether the identifier selects a recognised preset.

◆ SpeedInMph()

bool coastline::SpeedInMph ( const GameConfig & config,
std::string_view region,
std::string_view country )

Resolve speed units without recording an automatic choice as a user preference.

Game.Units values mph and kph override region and locale. Otherwise, explicit eur and jpn regions use KPH and usa uses MPH. Without a region, MPH jurisdictions use MPH, other countries use KPH, and an absent country defaults to MPH.

Parameters
configSaved settings; an absent or invalid Game.Units value selects automatic units.
regionThe explicit CLI region, or empty to use the system locale.
countryThe first available ISO 3166 country code in preferred locale order, or empty.
Returns
Whether speeds use miles per hour rather than kilometres per hour.

◆ SoundEffectsVolume()

int coastline::SoundEffectsVolume ( const GameConfig & config,
bool n64 )

Resolve SFX volume from a manual preference or the selected sample source.

Parameters
configSaved settings. Game.SfxVolume accepts 0 through 10; other values are automatic.
n64Whether N64 sound effects are selected.
Returns
The manual volume, or 10 for N64 samples and 4 for PC samples.

◆ GhostToJson()

std::optional< nlohmann::ordered_json > coastline::GhostToJson ( std::span< const std::uint8_t > bytes)

Describe a ghost recording of the PC release (RGho) as JSON: the recording, the settings, the name of its slot, and each frame with every bit in a named field.

The checksum and the sizes are left out, as the file computes them from the rest.

Parameters
bytesThe file.
Returns
The JSON, or nothing for a file that is not a recording with a valid checksum.

◆ GhostFromJson()

std::optional< std::vector< std::uint8_t > > coastline::GhostFromJson ( const nlohmann::ordered_json & json)

Build the file of a ghost recording from its JSON, the inverse of GhostToJson().

Parameters
jsonThe JSON.
Returns
The file, or nothing for JSON that does not describe a recording.

◆ FormatGhostJson()

std::string coastline::FormatGhostJson ( const nlohmann::ordered_json & json)

Write the JSON of a recording with each frame on one line.

Parameters
jsonThe JSON of GhostToJson().
Returns
The text.

◆ PackGhostNote()

std::optional< std::vector< u8 > > coastline::PackGhostNote ( std::span< const u8 > recording)

Compress a recording into the note of a ghost car, as SaveSaveLoadNote() of the console does: each of the two channels of the recording (the steering and the actions) with run lengths, and the length of each channel first in the byte order of the console.

The rest of the note is zero.

Parameters
recordingThe recording, its header included.
Returns
The note, or an empty optional when the recording has an invalid length or does not fit.

◆ UnpackGhostNote()

std::optional< std::vector< u8 > > coastline::UnpackGhostNote ( std::span< const u8 > note)

Expand the note of a ghost car into its recording.

Parameters
noteThe note.
Returns
The recording, including its header, or an empty optional for an incorrectly sized note, channel lengths past the note's end, or a recording outside [2, GHOST_RECORDING_CAPACITY] bytes.

◆ PackGhostFrames()

std::vector< u8 > coastline::PackGhostFrames ( std::span< const u8 > recording,
std::span< const u8 > frames )

Store the frames of the race engine with the recording of the console they were recorded with.

Parameters
recordingThe recording of the console.
framesThe frames, GHOST_FRAME_SIZE bytes each.
Returns
The file.

◆ GhostFramesFor()

std::optional< std::vector< u8 > > coastline::GhostFramesFor ( std::span< const u8 > file,
std::span< const u8 > recording )

Read the frames of the race engine of a recording of the console from the file of PackGhostFrames().

Parameters
fileThe file.
recordingThe recording of the console.
Returns
Complete compact frames, or an empty optional for malformed lengths, excessive frame counts, broken files, or data stored with another recording.

◆ SaveGhostFrames()

bool coastline::SaveGhostFrames ( const std::filesystem::path & path,
std::span< const u8 > recording,
std::span< const u8 > frames )

Atomically write the payload of PackGhostFrames() with a verified integrity header.

Parameters
pathThe file.
recordingThe recording of the console.
framesThe frames, GHOST_FRAME_SIZE bytes each.
Returns
Whether the buffers have valid lengths and the file was written.

◆ LoadGhostFrames()

std::optional< std::vector< u8 > > coastline::LoadGhostFrames ( const std::filesystem::path & path,
std::span< const u8 > recording )

Read the frames of a recording from the file of SaveGhostFrames().

Parameters
pathThe file.
recordingThe recording of the console.
Returns
The result of GhostFramesFor(), or an empty optional when the file cannot be read. Invalid checksums, malformed payloads, and frames for another recording trigger an attempt to delete the sidecar under its lock.

◆ ReadGltfDocument()

std::expected< GltfDocument, std::string > coastline::ReadGltfDocument ( const std::filesystem::path & path)

Read a model or image-override document.

A sibling .gltf takes precedence over .glb, including when the .gltf is invalid. Embedded images remain in their buffer views.

Parameters
pathThe document path, with either extension.
Returns
The document and its buffers, or an error.

◆ CreateGpuTexture()

SDL_GPUTexture * coastline::CreateGpuTexture ( SDL_GPUDevice * device,
const SDL_GPUTextureCreateInfo * info )

SDL_CreateGPUTexture(), recording bytes of every level and sample in GpuWindow::GpuMemoryBytes().

Parameters
deviceThe GPU device.
infoThe texture to create.
Returns
The texture, or null when the device cannot create it.

◆ CreateGpuBuffer()

SDL_GPUBuffer * coastline::CreateGpuBuffer ( SDL_GPUDevice * device,
const SDL_GPUBufferCreateInfo * info )

SDL_CreateGPUBuffer(), recording its size in GpuWindow::GpuMemoryBytes().

Parameters
deviceThe GPU device.
infoThe buffer to create.
Returns
The buffer, or null when the device cannot create it.

◆ CreateGpuTransferBuffer()

SDL_GPUTransferBuffer * coastline::CreateGpuTransferBuffer ( SDL_GPUDevice * device,
const SDL_GPUTransferBufferCreateInfo * info )

SDL_CreateGPUTransferBuffer(), recording its size in GpuWindow::GpuMemoryBytes().

Parameters
deviceThe GPU device.
infoThe transfer buffer to create.
Returns
The transfer buffer, or null when the device cannot create it.

◆ ReleaseGpuTexture()

void coastline::ReleaseGpuTexture ( SDL_GPUDevice * device,
SDL_GPUTexture * texture )

SDL_ReleaseGPUTexture(), subtracting its bytes from GpuWindow::GpuMemoryBytes().

Parameters
deviceThe GPU device.
textureA texture of CreateGpuTexture(), or null.

◆ ReleaseGpuBuffer()

void coastline::ReleaseGpuBuffer ( SDL_GPUDevice * device,
SDL_GPUBuffer * buffer )

SDL_ReleaseGPUBuffer(), subtracting its bytes from GpuWindow::GpuMemoryBytes().

Parameters
deviceThe GPU device.
bufferA buffer of CreateGpuBuffer(), or null.

◆ ReleaseGpuTransferBuffer()

void coastline::ReleaseGpuTransferBuffer ( SDL_GPUDevice * device,
SDL_GPUTransferBuffer * buffer )

SDL_ReleaseGPUTransferBuffer(), subtracting its bytes from GpuWindow::GpuMemoryBytes().

Parameters
deviceThe GPU device.
bufferA transfer buffer of CreateGpuTransferBuffer(), or null.

◆ ParseIconName()

std::optional< IconSize > coastline::ParseIconName ( std::string_view name)

Read the size of an image of the icon from the name the import gives its PNG file.

Parameters
nameThe file name, such as 32x32x4.png.
Returns
The size, or nothing for any other name.

◆ IconName()

std::string coastline::IconName ( const IconSize & size)

Give the name of the PNG file of an image of the icon.

Parameters
sizeThe size of the image.
Returns
The name, such as 32x32x4.png.

◆ ListIconImages()

std::vector< IconEntry > coastline::ListIconImages ( std::span< const std::uint8_t > icon)

List the images of an icon file.

An entry that records 0 bits per pixel takes the bits per pixel of its bitmap, or 32 for a PNG image.

Parameters
iconThe bytes of the icon file, which must outlive the entries.
Returns
The images in the order of the directory, or none when the file is not an icon file or an image lies outside it.

◆ DecodeIconBitmap()

std::optional< IconPixels > coastline::DecodeIconBitmap ( std::span< const std::uint8_t > image)

Decode an icon image that is a device-independent bitmap: the colours, then the AND mask that makes a pixel transparent.

A 32-bit image with any alpha takes its alpha in place of the mask.

Parameters
imageThe bitmap, from its BITMAPINFOHEADER, with the height of the colours and the mask together.
Returns
The pixels, or nothing when the bitmap is compressed, is not 1, 4, 8, 24, or 32 bits a pixel, or is cut short.

◆ NormalizeRomByteOrder()

bool coastline::NormalizeRomByteOrder ( std::span< std::uint8_t > image)

Convert a cartridge image in any of the three byte orders (z64, v64, n64) to big-endian.

Parameters
imageThe image, converted in place.
Returns
Whether the first word identified a byte order.

◆ IdentifyRom()

std::expected< RomRelease, std::string > coastline::IdentifyRom ( std::span< const std::uint8_t > image)

Identify a big-endian cartridge image by its SHA-1.

Parameters
imageThe big-endian image.
Returns
The release, or a message when the image is not an unmodified release.

◆ IdentifyRomFile()

std::expected< RomRelease, std::string > coastline::IdentifyRomFile ( const std::filesystem::path & image)

Identify a cartridge image file in any of the three byte orders by its SHA-1.

Parameters
imageThe cartridge image.
Returns
The release, or a message when the file cannot be read or is not an unmodified release.

◆ ImportRom()

std::expected< RomRelease, std::string > coastline::ImportRom ( const std::filesystem::path & image,
const std::filesystem::path & dataDirectory,
const ImportProgress & progress = {} )

Check a cartridge image and extract its main segment and its assets, inflated, to n64/usa, n64/jpn, n64/eur, or n64/asia under dataDirectory.

The cartridge also provides XM modules in music when music/menu.xm does not exist.

Parameters
imageThe cartridge image.
dataDirectoryThe directory of the pack to write, assets/default of the data directory.
progressReports extraction and conversion progress, or empty. Return false to cancel.
Returns
The release, or a message.

◆ ParseCueSheet()

std::expected< std::vector< CueTrack >, std::string > coastline::ParseCueSheet ( const std::filesystem::path & cue)

Parse a CUE sheet.

Track extents end at the INDEX 00 or INDEX 01 of the next track in the same file, or at the end of the file.

Parameters
cueThe CUE sheet.
Returns
The tracks, or a message.

◆ ImportDisc()

std::expected< std::size_t, std::string > coastline::ImportDisc ( const std::filesystem::path & disc,
const std::filesystem::path & dataDirectory,
const ImportProgress & progress,
std::vector< std::filesystem::path > * sources = nullptr )

Copy the files of the Boss Rally disc the game opens to dataDirectory, and its CD audio tracks as music/trackNN.flac.

An ISO image or mounted disc directory provides only data files. The icon Boss.ico moves to icon/coastline.ico, beside a PNG image of each of its sizes.

Parameters
discA mounted disc directory, CUE sheet, ISO, BIN, numbered Track NN.bin file, CloneCD, DiscJuggler CDI, Nero NRG, Alcohol MDS, BlindWrite 4/5/6, PDI, or unencrypted ISZ image. Adjacent CUE metadata precedes known-dump and discovered BIN layouts. Uncertain audio layouts import data only.
dataDirectoryThe directory of the pack to write, assets/default of the data directory.
progressCalled as each file and track is written, or empty.
sourcesReceives original input files and searched directories on success, or null.
Returns
The number of files written, or a message, also when progress cancels the import.

◆ CheckDisc()

std::optional< std::string > coastline::CheckDisc ( const std::filesystem::path & disc)

Check that a disc image or directory provides Boss Rally files without copying them.

Parameters
discA mounted disc directory, CUE sheet, ISO, BIN, numbered track file, or CloneCD image.
Returns
Why the disc cannot be imported, or nothing.

◆ RunImportJobs()

std::optional< std::string > coastline::RunImportJobs ( std::span< const ImportJob > jobs,
const ImportProgress & progress = {} )

Run independent jobs with at most four workers, limited by available CPU concurrency.

Progress callbacks are serialised, may run on any worker, and have a monotonic combined fraction. Cancellation and failures stop scheduling work and request active jobs to stop through progress. All workers finish before this function returns, including when a job or callback throws. A rejected progress report cancels its job regardless of the job's returned error text. A conversion failure takes precedence over cancellation of other jobs in the batch.

Parameters
jobsIndependent jobs with equal progress weights; empty input succeeds.
progressCombined progress, or empty. Return false to cancel the complete batch.
Returns
An error from a failed job, a cancellation message, or an empty optional on success.

◆ RecordImport()

bool coastline::RecordImport ( const std::filesystem::path & defaults,
ImportSource source )

Record in import.ini of the default pack that source was imported with the current version of its conversion.

Parameters
defaultsThe directory of the default pack.
sourceThe source imported.
Returns
Whether the file was written.

◆ StaleImports()

std::vector< ImportSource > coastline::StaleImports ( const std::filesystem::path & defaults)

The sources of the default pack imported with a conversion version different from the current one.

Source directories without version records also require a new import.

Parameters
defaultsThe directory of the default pack.
Returns
The incompatible sources, in the order of ImportSource.

◆ DefaultPackUsable()

bool coastline::DefaultPackUsable ( const std::filesystem::path & defaults)

Check whether import.ini records the disc and at least one cartridge at current conversion versions, the regional layout is current, and every recorded file exists at its imported size.

Require a complete inventory with a matching record count and SHA-1 digest. Required converted POD metadata and attract recordings must be available.

Parameters
defaultsThe directory of the default pack.
Returns
Whether the default pack is usable.

◆ RecordImportFiles()

bool coastline::RecordImportFiles ( const std::filesystem::path & defaults)

Atomically record the relative path and size of every generated file after a successful import.

A versioned header records the file count and SHA-1 of the complete inventory body.

Parameters
defaultsThe directory of the default pack.
Returns
Whether the inventory was written.

◆ ReimportMessage()

std::string coastline::ReimportMessage ( std::span< const ImportSource > sources)
Parameters
sourcesThe sources to import again, at least one.
Returns
A sentence that requests the sources be imported again, such as "Import the disc and the USA cartridge again."

◆ SaveIndexed4Png()

bool coastline::SaveIndexed4Png ( const std::filesystem::path & path,
std::span< const std::uint8_t > texels,
std::span< const std::uint8_t, 32 > palette,
int width,
int height )

Write a 4-bit colour-indexed image of the console as an indexed PNG image.

Parameters
pathThe PNG image to write.
texelsThe texels, two to a byte with the first in the high four bits, row by row, each row starting on a byte.
paletteThe 16 colours, each a big-endian RGBA5551 half.
widthThe width in texels.
heightThe height in texels.
Returns
Whether the image was written and reads back with the same texels and palette.

◆ LoadIndexed4Png() [1/2]

bool coastline::LoadIndexed4Png ( const std::filesystem::path & path,
std::span< std::uint8_t > texels,
std::span< std::uint8_t, 32 > palette )

Read an indexed PNG image as the 4-bit texels and the RGBA5551 palette of the console.

Parameters
pathThe PNG image.
texelsReceives the texels, two to a byte with the first in the high four bits, each row starting on a byte.
paletteReceives the 16 colours, each a big-endian RGBA5551 half.
Returns
Whether the image uses palette indices below 16 and its packed texels fill texels.

◆ LoadIndexed4Png() [2/2]

bool coastline::LoadIndexed4Png ( std::span< const std::uint8_t > bytes,
std::span< std::uint8_t > texels,
std::span< std::uint8_t, 32 > palette )

Read an encoded indexed PNG with the same requirements as the file overload.

Parameters
bytesThe encoded PNG image, borrowed for this call.
texelsReceives packed 4-bit texels, with each row starting on a byte.
paletteReceives 16 big-endian RGBA5551 colours.
Returns
Whether the image uses palette indices below 16 and its packed texels fill texels.

◆ SaveRgba8Png()

bool coastline::SaveRgba8Png ( const std::filesystem::path & path,
std::span< const std::uint8_t > rgba,
int width,
int height )

Write 8-bit RGBA texels as a PNG image, and read it back to check it.

Parameters
pathThe image to write.
rgbaThe texels, red, green, blue, and alpha each, row by row from the top.
widthThe width in texels.
heightThe height in texels.
Returns
Whether the image was written and reads back as the same texels.

◆ EncodeIndexed4Png()

std::optional< std::vector< std::uint8_t > > coastline::EncodeIndexed4Png ( std::span< const std::uint8_t > texels,
std::span< const std::uint8_t, 32 > palette,
int width,
int height )

Encode a 4-bit colour-indexed image of the console as an indexed PNG image in memory.

Parameters
texelsThe texels, two to a byte with the first in the high four bits, row by row, each row starting on a byte.
paletteThe 16 colours, each a big-endian RGBA5551 half.
widthThe width in texels.
heightThe height in texels.
Returns
The PNG image, or no value unless it decodes to the same texels and palette.

◆ EncodeRgba8Png()

std::optional< std::vector< std::uint8_t > > coastline::EncodeRgba8Png ( std::span< const std::uint8_t > rgba,
int width,
int height )

Encode 8-bit RGBA texels as a PNG image in memory.

Parameters
rgbaThe texels, red, green, blue, and alpha each, row by row from the top.
widthThe width in texels.
heightThe height in texels.
Returns
The PNG image, or no value unless it decodes to the same texels.

◆ AssignedDevices()

PlayerDevices coastline::AssignedDevices ( std::size_t player,
std::size_t players )

Resolve the Player1 and Player2 keys of the Controls section against the open gamepads.

A key that is auto takes the gamepads no other key chooses, one each in the order of the players and the rest by the first player that is auto, and the keyboard goes to the first player that is auto with no gamepad, else to the first player that is auto.

Parameters
playerThe player, 0 for the first.
playersThe number of players, 1 or 2. One player takes the devices of both.
Returns
The devices of the player.

◆ ReadRacePad()

ControllerState coastline::ReadRacePad ( const PlayerDevices & devices)

Read the second player of a race as the console reads a pad: the race actions of the Controls section for each gamepad, and the keyboard bindings of the PC release for the keyboard.

Parameters
devicesThe devices of the player.
Returns
The state of the pad, connected.

◆ ScaleStickAxis()

std::int8_t coastline::ScaleStickAxis ( std::int16_t axis)

Scale an SDL axis of -32768 to 32767 to the range of the controller stick.

The axis has passed through the dead zone of ReadControl().

Parameters
axisThe SDL axis value.
Returns
The stick value from -80 to 80, rounded towards zero.

◆ SetScriptedKeys()

void coastline::SetScriptedKeys ( std::vector< int > scancodes)

Add simulated key presses alongside physical keyboard input, for tests.

Parameters
scancodesThe SDL scancodes to report as down, replacing the previous list.

◆ IsKeyDown()

bool coastline::IsKeyDown ( SDL_Scancode scancode)
Parameters
scancodeThe key.
Returns
Whether the key is down on the keyboard or reported by SetScriptedKeys(), and not ignored by IgnoreKeyUntilReleased(). Without active bindings, only physical input is read.

◆ IgnoreKeyUntilReleased()

void coastline::IgnoreKeyUntilReleased ( SDL_Scancode scancode)

Report a key as up to IsKeyDown() until it is released, for a key a shortcut of the window consumed, such as Enter of Alt and Enter.

Parameters
scancodeThe key.

◆ SetSecondControllerState()

void coastline::SetSecondControllerState ( const ControllerState & state)

Set the state of the second controller the race reads for its second player, until the next call.

Parameters
stateThe state of the second port.

◆ TakeMouseWheel()

int coastline::TakeMouseWheel ( )
Returns
The wheel of the mouse scrolled since the last call, in the units of the third axis of a DirectInput mouse (120 a notch, positive away from the user). A fraction of a unit is retained for the next call.

◆ ClearMouseWheel()

void coastline::ClearMouseWheel ( )

Discard the wheel of the mouse scrolled since TakeMouseWheel() last read it.

◆ DecodeIsz()

std::expected< DecodedDisc, std::string > coastline::DecodeIsz ( const std::filesystem::path & image,
const ImportProgress & progress = {} )

Decode an unencrypted ISZ image, including split segments, to temporary storage.

Validate metadata, compressed stream lengths, and checksums when supplied by the header.

Parameters
imageFirst segment of an ISZ image.
progressDecoding progress, or empty. Return false to cancel and discard temporary data.
Returns
A decoded image with shared storage, or a diagnostic on invalid input or cancellation.

◆ SelectedLanguage()

const std::string & coastline::SelectedLanguage ( )
Returns
The active text catalogue's language, or DEFAULT_LANGUAGE without a catalogue.

◆ MergeStrings()

StringTable coastline::MergeStrings ( StringTable fallback,
const StringTable & language )
Parameters
fallbackThe strings of DEFAULT_LANGUAGE.
languageThe strings of the selected language.
Returns
The strings of the language, with the string of fallback for each key the language lacks.

◆ ReleaseDirectory()

std::filesystem::path coastline::ReleaseDirectory ( const std::filesystem::path & assets)
Parameters
assetsThe assets of the pack.
Returns
The selected cartridge directory, independent of language.

◆ CartridgeRegion()

std::string coastline::CartridgeRegion ( const std::filesystem::path & release)
Parameters
releaseThe converted cartridge directory with cartridge.ini.
Returns
usa, eur, or jpn from recorded metadata, or empty for absent or invalid metadata.

◆ AvailableCartridgeRegions()

std::vector< std::string > coastline::AvailableCartridgeRegions ( std::span< const std::filesystem::path > dataRoots)
Parameters
dataRootsThe data directories searched for default and regional packs.
Returns
Available regions without duplicates, sorted lexicographically.

◆ TitleScreenRegion()

std::optional< std::string > coastline::TitleScreenRegion ( std::string_view choice,
std::string_view currentRegion,
std::span< const std::string > available )
Parameters
choiceregional, japanese, or international; another value is unavailable.
currentRegionThe active cartridge region, assumed available.
availableOther available cartridge regions.
Returns
The requested region, independent of language, or std::nullopt when unavailable. International prefers the active USA or European region, then USA, then Europe.

◆ FontDirectory()

std::filesystem::path coastline::FontDirectory ( const std::filesystem::path & assets,
std::string_view language )
Parameters
assetsThe prepared asset directory.
languageja for Japanese fonts, en-gb for European fonts, or another value for USA fonts.
Returns
The selected fonts directory when fonts.json exists, or the imported base directory.

◆ AbbreviateLogPaths()

std::string coastline::AbbreviateLogPaths ( std::string_view message,
std::string_view home )

Abbreviate home-directory paths in a log message without changing similarly prefixed paths.

Windows drive and UNC paths accept either separator and match ASCII letters without case sensitivity.

Parameters
messageThe formatted message, possibly including several paths.
homeThe absolute home directory, with or without a trailing separator. Empty and single-character directories disable abbreviation.
Returns
The message with recognised home-directory prefixes replaced by tildes.

◆ StopGameLog()

void coastline::StopGameLog ( )

Close the active game log and restore its previous callback before fatal process exit.

◆ CenterLines()

int coastline::CenterLines ( std::string_view text,
int y,
int lines,
int lineHeight )

Centre a string on the place of a block of a number of lines, as a release that draws a message in fewer lines than the USA release centres it.

Parameters
textThe string, with a newline between lines.
yThe baseline of the first line of the block.
linesThe lines of the block.
lineHeightThe distance between the baselines of two lines.
Returns
The baseline of the first line of the string.

◆ PublishN64Volumes()

void coastline::PublishN64Volumes ( )

Hand the volumes the game writes (g_bBgmVolume, g_bMusicVolume, g_bSfxMasterVolume, and g_bSfxVolume) to the mixers.

The mixers read the copy, and the game calls this once a frame.

◆ RecordN64AttractDemo()

std::expected< N64Demo, std::string > coastline::RecordN64AttractDemo ( std::span< const std::uint8_t > rom,
N64DemoRelease release )

Record the attract demo of a cartridge.

Parameters
romThe image, in the byte order of the console.
releaseThe release of the image.
Returns
The demo, or the reason it could not be recorded.

◆ CarModelToGltf()

std::expected< GltfModel, std::string > coastline::CarModelToGltf ( std::span< const std::uint8_t > bytes,
std::size_t imageOffset,
std::string_view bufferUri )

Describe the model of a car as glTF.

The document has a scene for each level of detail, with a mesh for each display list of the body and the wheels at their places. Every vertex the display lists load appears once, in the order of the file, and the bytes of the file outside the vertices are retained in the buffer for ModelFromGltf().

Parameters
bytesThe file, a header of imageOffset bytes followed by the image of the model as the console loads it at 0x803c8000.
imageOffsetThe size of the header before the image, 0x8000 for a .rca file of the PC release and 0 for a model of the cartridge.
bufferUriThe URI the document gives its buffer.
Returns
The glTF, or a description of why the file is not a model of a car.

◆ TrackToGltf()

std::expected< GltfModel, std::string > coastline::TrackToGltf ( std::span< const std::uint8_t > bytes,
std::string_view bufferUri )

Describe a track as glTF.

The document has one scene, with a node for each placed model at its place, and the sky as a node outside the scene. The bytes of the file outside the vertices are retained in the buffer for ModelFromGltf(), the textures of the bank after the geometry among them.

Parameters
bytesThe file, the image of the geometry as the console loads it at 0x80025c00, followed by the textures that stream from it.
bufferUriThe URI the document gives its buffer.
Returns
The glTF, or a description of why the file is not a track.

◆ FrontEndModelToGltf()

std::expected< GltfModel, std::string > coastline::FrontEndModelToGltf ( std::span< const std::uint8_t > bytes,
std::string_view bufferUri )

Describe a model of the front end, such as a logo of the splash screens, as glTF.

The document has one scene, with a node for each part at its place. Each key of each animation of the vertices is a morph target of every mesh, and the animation blends from each key to the next, with the flags and the span of time the game plays it by in its extras. The bytes of the file outside the vertices are retained in the buffer for ModelFromGltf().

Parameters
bytesThe model as it inflates from the cartridge, its offsets from its first byte.
bufferUriThe URI the document gives its buffer.
Returns
The glTF, or a description of why the file is not a model.

◆ ModelFromGltf()

std::expected< std::vector< std::uint8_t >, std::string > coastline::ModelFromGltf ( const nlohmann::ordered_json & json,
std::span< const std::uint8_t > buffer )

Build the file of a model or a track from its glTF, the inverse of CarModelToGltf(), TrackToGltf(), and FrontEndModelToGltf().

The vertices come from the accessors of the document.

Parameters
jsonThe document.
bufferThe bytes of its buffer.
Returns
The file, or a description of why the glTF does not describe a model of the console.

◆ ValidSavedRaceTime()

bool coastline::ValidSavedRaceTime ( float seconds)

Check that a saved race time is finite, non-negative, and safe to display in signed hundredths.

Parameters
secondsSaved time in seconds; zero represents an unset record.
Returns
Whether display conversion can represent the time.

◆ ValidOptionsNote()

bool coastline::ValidOptionsNote ( std::span< const std::uint8_t > note,
const NoteEquipmentCounts & counts )

Validate native options-note length, volume levels, units, and equipment indices.

Parameters
noteNative Controller Pak payload.
countsAvailable equipment choices in the active menu.
Returns
Whether every field the options screen reads is valid.

◆ ValidSeasonNoteValues()

bool coastline::ValidSeasonNoteValues ( std::span< const std::uint8_t > note,
const NoteEquipmentCounts & counts )

Validate native season-note length, times, placements, and equipment indices.

Season, round, and unlock availability must also be checked against the active championship.

Parameters
noteNative Controller Pak payload.
countsAvailable equipment choices in the active menu.
Returns
Whether numeric profile fields are safe to load and display.

◆ ValidGhostRecording()

bool coastline::ValidGhostRecording ( std::span< const std::uint8_t > recording,
std::size_t tracks,
std::size_t cars,
const NoteEquipmentCounts & counts )

Validate an expanded console ghost's length, track, car, and equipment header.

Parameters
recordingExpanded header and paired steering/action bytes.
tracksNumber of available tracks.
carsNumber of available cars.
countsAvailable equipment choices in the active menu.
Returns
Whether the recording can index menu data and unlock masks safely.

◆ Utf8FromPath()

std::string coastline::Utf8FromPath ( const std::filesystem::path & path)
inline
Parameters
pathA native filesystem path.
Returns
The path in UTF-8, with native directory separators.

◆ PortablePathsEnabled()

bool coastline::PortablePathsEnabled ( )
Returns
Whether this build supports adjacent portable configuration and assets.

◆ PortableRoot()

std::filesystem::path coastline::PortableRoot ( const std::filesystem::path & executable,
const std::filesystem::path & appImage = {} )

Locate portable files beside an application bundle, AppImage, or ordinary executable.

Parameters
executableAbsolute base directory reported by SDL.
appImageAbsolute AppImage filename, or empty for other distributions.
Returns
CoastlineData beside a bundle or AppImage, the distribution root above bin, or executable for other layouts.

◆ ResolvePortablePaths()

std::expected< GamePaths, std::string > coastline::ResolvePortablePaths ( const GamePaths & fallback,
const std::filesystem::path & executable,
const std::filesystem::path & workingDirectory = {} )

Prefer adjacent configuration and assets independently when portable lookup is enabled.

Parameters
fallbackPlatform directories used for absent adjacent files.
executableAbsolute portable directory of the application distribution.
workingDirectoryLaunch directory checked after the distribution, including its CoastlineData child, or empty to omit it.
Returns
Selected directories, or an error when an adjacent location cannot be written.

◆ StorePortablePath()

std::filesystem::path coastline::StorePortablePath ( const std::filesystem::path & path,
const std::filesystem::path & root,
const std::filesystem::path & home )

Store an input path relative to the portable directory, using '~' for external home paths.

Parameters
pathInput path; empty and relative paths remain unchanged.
rootPortable directory rebuilt from the executable location on startup.
homeHome directory, or empty to disable home shorthand.
Returns
Relative path, home shorthand, or the original path when no relative path exists.

◆ RestorePortablePath()

std::filesystem::path coastline::RestorePortablePath ( const std::filesystem::path & path,
const std::filesystem::path & root,
const std::filesystem::path & home )

Rebuild a stored portable input path at its current executable or home location.

Parameters
pathStored path, possibly relative or starting with a '~' component.
rootCurrent portable directory.
homeCurrent home directory, or empty to preserve home shorthand.
Returns
Rebuilt path, with absolute input paths preserved.

◆ ResolveXdgPaths()

std::optional< GamePaths > coastline::ResolveXdgPaths ( const EnvironmentReader & environment,
const std::string & application )

Resolve the directories with the XDG Base Directory variables and their defaults under the home directory.

A relative XDG value is ignored, as the specification requires.

Parameters
environmentThe source of the environment variables.
applicationThe name of the directory created under each base directory.
Returns
The four directories, or nothing when neither HOME nor an XDG variable gives a base.

◆ ResolveGamePaths()

std::optional< GamePaths > coastline::ResolveGamePaths ( const std::string & application)

Resolve the directories with the conventions of the running operating system: the XDG Base Directory variables on Linux and the BSDs, the folders of the user's library on macOS, and the roaming and local application data folders on Windows.

Parameters
applicationThe name of the directory created under each base directory.
Returns
The four directories, or nothing when the operating system does not report a base.

◆ SystemDataDirectories()

std::vector< std::filesystem::path > coastline::SystemDataDirectories ( const std::filesystem::path & executable)

List system data roots, including the relocated installation and platform defaults.

Parameters
executableThe directory of the executable, or empty to omit relative roots.
Returns
Data roots in lookup order.

◆ FindAssetData()

std::optional< std::filesystem::path > coastline::FindAssetData ( const std::filesystem::path & user,
std::span< const std::filesystem::path > system )

Find usable assets in system roots first, then in the writable user data root.

Parameters
userThe writable user data root.
systemSystem data roots in lookup order.
Returns
The first root with usable default assets, or nothing.

◆ CreateGamePaths()

bool coastline::CreateGamePaths ( const GamePaths & paths)

Create every directory of paths that does not exist.

Parameters
pathsThe directories to create.
Returns
Whether every directory exists afterwards.

◆ MigratePortablePaths()

std::optional< std::string > coastline::MigratePortablePaths ( const GamePaths & source,
const GamePaths & destination,
bool copyOnly = false )

Move portable assets, settings, saves, screenshots, and state to platform directories.

Derived cache is not copied and is removed only when moving the installation. Existing destination entries are never overwritten.

Parameters
sourceSelected portable directories; unrelated neighbouring files are preserved.
destinationNormal platform directories, outside the portable source trees.
copyOnlyWhether to preserve the portable installation after copying.
Returns
An error on failure, or an empty optional on success. Copy failures preserve source data; cleanup failures preserve the completed destination.

◆ MakePortablePaths()

std::optional< std::string > coastline::MakePortablePaths ( const GamePaths & source,
const std::filesystem::path & directory,
bool copyOnly = false )

Export platform data as a portable installation, without copying the executable.

Existing destination entries are never overwritten. Derived cache is regenerated.

Parameters
sourceNormal platform directories with imported assets and BossRally.ini.
directoryAbsolute destination directory for assets, settings, and state.
copyOnlyWhether to preserve platform data after copying.
Returns
An error on failure, or an empty optional on success.

◆ MakePortableDistribution()

std::optional< std::string > coastline::MakePortableDistribution ( const GamePaths & source,
const std::filesystem::path & executable,
const std::filesystem::path & directory,
bool copyOnly = false )

Export installed program files and platform data into a complete portable distribution.

Bundles use CoastlineData beside the copied bundle; bin packages store data at their root. Source program files are preserved. Data is removed only after publishing the completed copy.

Parameters
sourceNormal platform directories with imported assets and BossRally.ini.
executableAbsolute SDL base directory within an installed bundle or bin directory.
directoryNew absolute parent directory for the complete portable distribution.
copyOnlyWhether to preserve platform data after copying.
Returns
An error on failure, or an empty optional on success.

◆ ResetGamePaths()

std::optional< std::string > coastline::ResetGamePaths ( const GamePaths & paths,
bool factoryReset = false )

Clear imported assets and asset caches, or all application data for a factory reset.

Parameters
pathsAbsolute, non-root application directories whose generated data is removed.
factoryResetWhether to remove all four directories, including settings and saves.
Returns
An error message on failure, or std::nullopt on success.

◆ DefaultAssets()

std::filesystem::path coastline::DefaultAssets ( const std::filesystem::path & data)
inline

The directory the import writes the game data to, the default pack.

A mod pack is a directory beside it under assets.

Parameters
dataThe data directory of the game.
Returns
The directory of the default pack.

◆ PackDirectory()

std::filesystem::path coastline::PackDirectory ( const std::filesystem::path & data,
std::string_view pack,
const std::filesystem::path & fallback = {} )

The directory of a pack under assets of the data directory, named after the pack.

Parameters
dataThe data directory of the game.
packThe name of the pack.
fallbackAnother data root used when data lacks the pack directory, or empty.
Returns
The directory of the pack.

◆ PackAssets()

std::optional< std::filesystem::path > coastline::PackAssets ( const std::filesystem::path & data,
const std::filesystem::path & cache,
std::string_view pack,
const std::filesystem::path & fallback = {},
std::string_view region = {} )

The directory the game reads its assets from with a pack selected.

Duplicate-file aliases are expanded under cache before layering. Without aliases, the default pack is read in place. Another pack is layered over the default pack in a directory under cache. An entry of the pack replaces the entry of the same name in the default pack, and a directory in both is layered in turn. Each entry is a link to the file or the directory it comes from, or a copy where the file system has no links. The directory is made again only when the path or the write time of an entry of either pack differs from the stamp recorded in it, or the stamp is missing.

Parameters
dataThe data directory of the game.
cacheThe cache directory of the game.
packThe name of the pack.
fallbackAnother data root searched for the selected pack, or empty. Default assets still come from data.
regionA regional difference pack applied before pack, or empty for the base region.
Returns
The directory, or nothing when the pack does not exist or the directory cannot be made.

◆ DecodePdi()

std::expected< DecodedDisc, std::string > coastline::DecodePdi ( const std::filesystem::path & image,
const ImportProgress & progress = {} )

Decode a Pinnacle InstantCopy PDI image to temporary storage.

Support cooked data, raw data and audio, scrambled data, and interleaved subchannels.

Parameters
imagePDI image with a 304-byte container header.
progressDecoding progress, or empty. Return false to discard temporary data and cancel.
Returns
Headerless ISO or BIN with shared cleanup storage, or a diagnostic on failure.

◆ UniqueGpuIndex()

std::optional< std::size_t > coastline::UniqueGpuIndex ( std::string_view active,
std::span< const std::string > devices )
inline

Match the active adapter to one provider device, rejecting absent and ambiguous identities.

Parameters
activeThe active adapter identifier, compared exactly.
devicesThe provider identifiers in device-index order.
Returns
The unique matching index, or std::nullopt for an empty, absent, or duplicate identifier.

◆ StatmResidentPages()

std::optional< std::uint64_t > coastline::StatmResidentPages ( std::string_view text)
inline
Parameters
textA line of /proc/self/statm.
Returns
The resident pages, the second number of the line, or nothing when the line has no second number.

◆ SmapsGamePssBytes()

std::optional< std::uint64_t > coastline::SmapsGamePssBytes ( std::string_view text,
std::string_view executable )
inline
Parameters
textThe contents of /proc/self/smaps.
executableThe path of the program, as /proc/self/exe links to it.
Returns
The proportional set size in bytes of the memory of the game: the mappings without a file (the heap, the stacks, and other anonymous memory) and those of the program. The shared libraries, among them the GPU driver, and the mappings of devices are left out. The driver's own anonymous memory cannot be told apart and is counted. Nothing when the text has no Pss line.

◆ OpenRaceData()

void coastline::OpenRaceData ( bool playSounds)

Set the default configuration, the bindings, and the strings of the race, and open its sound, as the PC release does once at its start.

The models of BossRally.pod load from its import. The working directory is the directory of the default assets.

Parameters
playSoundsWhether the race plays its sound effects.

◆ StartRaceMusic()

bool coastline::StartRaceMusic ( const std::filesystem::path & directory,
RaceMusicSource source,
int musicTrack = -1 )

Add a user of the music of the races, as the PC release opens its music device.

The first user finds the tracks and opens the playback device, when the game plays music.

Parameters
directoryThe directory of the music files.
sourceWhere the music comes from.
musicTrackThe engine track selecting XM music, or -1 for the current race track. PC CD selection ignores this parameter.
Returns
Whether the music can play.

◆ StopRaceMusic()

void coastline::StopRaceMusic ( )

Drop a user of the music of the races.

The last user stops the music of the CD and closes its device. A shared player of the menus then plays the module of the track on, as the console plays it on the screens after a race.

◆ ShutdownRaceMusic()

void coastline::ShutdownRaceMusic ( )

Release all race music resources regardless of active users, before SDL audio shuts down.

◆ RestartRaceMusic()

void coastline::RestartRaceMusic ( )

Play the track of the race from its start, with the device of the music resumed.

◆ ShareRaceMusicPlayer()

void coastline::ShareRaceMusicPlayer ( N64Audio * audio)

Play the modules of the races through the player of the music of the menus, which mixes the channels of the console, instead of a player of their own.

Two players would mix the same channels on two threads.

Parameters
audioThe player of the menus, with its device open, or null for a player of their own.

◆ RenderRaceMusic()

std::size_t coastline::RenderRaceMusic ( std::size_t frames)

Render frames of the track that plays, without a device, for tests.

Parameters
framesThe stereo frames.
Returns
The number of samples that are not silent.

◆ RaceVolumeLevels()

std::array< int, 2 > coastline::RaceVolumeLevels ( )
Returns
Music and sound effect levels of the race RaceSession::Start() started last, from 0 to 9, as set by its pause menu.

◆ RaceTrack()

int coastline::RaceTrack ( )
Returns
The track of the race that loaded last, an index of g_apszTrackFilenames: the track of the race after a season in its mode.

◆ RaceCars()

std::vector< RaceCar > coastline::RaceCars ( )
Returns
The car of each vehicle of the race that loaded last, in the colour of the vehicle as InitVehicleColorAndPhysics() paints it.

◆ RaceFieldOfView()

float coastline::RaceFieldOfView ( float fovy,
float aspect,
float scale = 1.0f )

The vertical field of view of a view of the race on a frame.

A frame at least as wide as 4:3 keeps the vertical field and widens across, and a narrower frame keeps the field across of 4:3 and grows the vertical field. Neither field exceeds 120 degrees, and past the widest field across the vertical field shrinks.

Parameters
fovyThe vertical field in radians of the view on the 4:3 screen of the PC release, before the configured multiplier.
aspectThe width of the view over its height on the frame.
scaleThe field multiplier, with non-positive values treated as 1.
Returns
The vertical field in radians.

◆ ReadWholeFile()

std::optional< std::vector< std::uint8_t > > coastline::ReadWholeFile ( const std::filesystem::path & path)

Reads a whole file with one read of its size.

Parameters
pathThe file.
Returns
The bytes of the file, or no value when it cannot be opened or read.

◆ ParseScript()

std::expected< Script, ScriptError > coastline::ParseScript ( std::string_view text)

Read a script of run-script: one command a line, with # starting a comment and blank lines ignored.

A line that starts with a frame number acts at that frame, and the lines autopilot and screenshot-every N take no frame and apply from the start.

Parameters
textThe text of the script.
Returns
The script, or the first line that cannot be read.

◆ ReadSaveFile()

std::optional< std::vector< std::uint8_t > > coastline::ReadSaveFile ( const std::filesystem::path & path,
std::size_t limit )

Read a complete regular file without allocating beyond a caller-supplied limit.

Parameters
pathFile to read. Concurrent atomic replacement preserves the opened contents.
limitMaximum accepted length in bytes.
Returns
Complete contents, or std::nullopt for missing, oversized, or unreadable files.

◆ WriteSaveFile() [1/2]

bool coastline::WriteSaveFile ( const std::filesystem::path & path,
std::span< const std::uint8_t > bytes )

Lock and atomically replace a binary save.

Parameters
pathDestination file.
bytesComplete new contents.
Returns
Whether replacement and synchronisation succeed. Failures before replacement preserve the previous save.

◆ WriteSaveFile() [2/2]

bool coastline::WriteSaveFile ( const std::filesystem::path & path,
std::string_view text )

Lock and atomically replace a text save.

Parameters
pathDestination file.
textComplete new contents, written without newline conversion.
Returns
Whether replacement and synchronisation succeed. Failures before replacement preserve the previous save.

◆ ReadVerifiedSaveFile()

std::optional< std::vector< std::uint8_t > > coastline::ReadVerifiedSaveFile ( const std::filesystem::path & path,
std::size_t limit,
bool resetInvalid = true,
const SavePayloadValidator & validate = {} )

Read an internal binary save with its format signature, payload length, and SHA-1 checksum.

Exclude cooperating writers while validating and optionally removing damaged or oversized saves. Unreadable files are preserved when their size cannot prove corruption.

Parameters
pathInternal save file; native interchange files and editable INI files are excluded.
limitMaximum payload size in bytes, excluding the integrity header.
resetInvalidRemove damaged saves; disable when scanning possibly unrelated files.
validateOptional format-specific validator, called after the checksum passes.
Returns
Verified payload, or std::nullopt for a missing, unreadable, or invalid save or size limit.

◆ WriteVerifiedSaveFile()

bool coastline::WriteVerifiedSaveFile ( const std::filesystem::path & path,
std::span< const std::uint8_t > bytes )

Atomically write an internal binary save with a format signature, length, and SHA-1 checksum.

The payload and integrity header are replaced together under the save's process lock.

Parameters
pathInternal save file, with parent directories created as needed.
bytesComplete binary payload.
Returns
Whether replacement and synchronisation succeed.

◆ MultiplyMatrices()

Matrix4 coastline::MultiplyMatrices ( const Matrix4 & a,
const Matrix4 & b )
Parameters
aThe matrix applied second.
bThe matrix applied first.
Returns
The product a b.

◆ PoseAtTime()

std::optional< MorphPose > coastline::PoseAtTime ( const VertexAnimationInfo & animation,
float time )

The pose of a vertex animation at a time, as the console blends its keys.

Parameters
animationThe animation.
timeThe time of the animation, in seconds.
Returns
The two keys around the time and the share of the second, in 4096ths, or nothing for an animation of fewer than two keys.

◆ ReadLibraryStrings()

std::map< unsigned, std::string > coastline::ReadLibraryStrings ( std::span< const std::uint8_t > image)

Read the string resources of a Windows library.

Parameters
imageThe bytes of the library file.
Returns
The strings of the RT_STRING resources as UTF-8, by identifier. A library that is not a PE image or has no string resources gives none.

◆ AppendUtf8()

void coastline::AppendUtf8 ( std::string & text,
char32_t c )

Append a code point to UTF-8 text.

Parameters
textThe UTF-8 text.
cThe code point.

◆ NextCodePoint()

char32_t coastline::NextCodePoint ( std::string_view text,
std::size_t & position )

Decode the code point of UTF-8 text at a position, and step past it.

A sequence cut short by the end of the text decodes from the bytes it has.

Parameters
textThe UTF-8 text.
positionThe byte of the code point, moved to the byte after it.
Returns
The code point.

◆ FindString()

const std::string * coastline::FindString ( std::string_view key)
Parameters
keyThe key of a string, such as 1 or n64.carSelect.rumblePakNote.
Returns
The active catalogue's string in UTF-8, or nothing.

◆ GameString()

std::string_view coastline::GameString ( std::string_view key)
Parameters
keyThe key of a string, such as n64.carSelect.rumblePakNote.
Returns
The active catalogue's string in UTF-8, the string of the selected language or else of en-us, or key when neither file has it, logged the first time.

◆ EngineTrackForMenu()

int coastline::EngineTrackForMenu ( int track)
constexpr
Parameters
trackThe zero-based track-selection index.
Returns
The race-engine track, or -1 for a menu action or invalid index.

◆ MenuTrackForEngine()

int coastline::MenuTrackForEngine ( int track)
constexpr
Parameters
trackThe PC race-engine track index.
Returns
The menu track, or -1 for an invalid engine track.

◆ LoadedTextureMapEntries()

int coastline::LoadedTextureMapEntries ( )
Returns
The entries of the texture map LoadTrackTextureMap() read last.

◆ ConvertedVertexCount()

unsigned coastline::ConvertedVertexCount ( )
Returns
The vertices converted into the pool since ResetModelDataPool().

◆ CarDentOffsets()

std::vector< std::array< float, 3 > > coastline::CarDentOffsets ( const VehicleModel * model,
std::span< const std::array< float, 3 > > rest )

How far DeformVehicleMeshByImpact() has moved each vertex of a car from where it rested when the car loaded, by the position it rested at.

Parameters
modelThe model of the car.
restThe position each vertex rests at, in the units of the model.
Returns
The displacement of each vertex of rest, or nothing when the car has no dent.

◆ TrackPreviewToGltf()

std::expected< GltfModel, std::string > coastline::TrackPreviewToGltf ( const GltfModel & track,
std::string_view bufferUri )

Generate a static menu miniature from a converted track during import.

Instance transforms are flattened, sky geometry is omitted, convex planar openings are capped, exposed terrain edges extend to the base, and attribute-aware simplification reduces detail. Average texture colours become vertex colours; the result does not require external images.

Parameters
trackThe complete result of TrackToGltf(), including decoded images.
bufferUriThe relative URI of the generated binary buffer.
Returns
A centred glTF miniature, or an error for invalid or empty geometry.

◆ ConvertIntroMedia()

std::optional< std::string > coastline::ConvertIntroMedia ( const std::filesystem::path & directory,
const ImportProgress & progress = {} )

Convert optional disc intro media.

Linux uses libav directly. Windows and macOS use a temporary FFmpeg executable when one is absent from PATH.

Parameters
directoryThe extracted disc assets, including optional brally.avi and splash.img.
progressProgress and cancellation callback, or empty.
Returns
An error on conversion or cancellation, or an empty optional when complete or media is absent.

◆ RaceVolumeLevel()

int coastline::RaceVolumeLevel ( int level)
constexpr
Parameters
levelA level of the options menu.
Returns
The nearest level of the race engine. The loudest level of each is the same.

◆ MenuVolumeLevel()

int coastline::MenuVolumeLevel ( int raceLevel,
int level )
constexpr

The level of the options menu after the pause menu of a race changed the level of the race engine.

Parameters
raceLevelThe level of the race engine as the race ended.
levelThe level of the options menu the race started at.
Returns
level when RaceVolumeLevel() gives raceLevel for it, else the highest level of the options menu RaceVolumeLevel() gives raceLevel for.

◆ AttachParentConsole()

void coastline::AttachParentConsole ( )

Attach to an existing parent console and reconnect unavailable standard streams.

Redirected streams are preserved. A console window is never allocated.

◆ VisitZipEntries()

std::optional< std::string > coastline::VisitZipEntries ( const std::filesystem::path & archive,
const std::function< bool(const std::string &, std::uint32_t)> & accept,
const std::function< bool(const std::string &, std::vector< std::uint8_t > &)> & visit,
const std::function< bool(const std::string &, double)> & progress = {} )

Visit CRC-checked stored and deflated entries in a ZIP archive without extracting archive paths.

Parameters
archiveThe ZIP archive.
acceptReceive the path and unpacked size of an entry. Return true to unpack it.
visitProcess the path and unpacked bytes of an accepted entry. Return false to stop.
progressReport entry progress, or empty. Return false to stop.
Returns
A failure or cancellation message, or nothing on success.

◆ VisitZipRoms()

std::optional< std::string > coastline::VisitZipRoms ( const std::filesystem::path & archive,
const std::function< bool(std::vector< std::uint8_t > &)> & visit,
const std::function< bool(const std::string &, double)> & progress = {} )

Visit CRC-checked ROM entries in a ZIP archive without extracting archive paths.

Parameters
archiveThe ZIP archive.
visitProcess unpacked entry bytes. Return false to stop.
progressReport entry progress, or empty. Return false to stop.
Returns
A failure or cancellation message, or nothing on success.

Variable Documentation

◆ BOSS_PACK

std::string_view coastline::BOSS_PACK = "boss"
inlineconstexpr

The name of the pack of the PC images the default pack replaces with branded images.

◆ PACK_SETTINGS_VERSION

int coastline::PACK_SETTINGS_VERSION = 1
inlineconstexpr

The version of pack.json the import writes.

◆ DEFAULT_XM_MUSIC_GAIN

float coastline::DEFAULT_XM_MUSIC_GAIN = 1.5f
inlineconstexpr

The gain of the music modules of the default pack, as they play quieter than the CD audio.

◆ ASSET_ALIASES_FILE

const char* coastline::ASSET_ALIASES_FILE = "asset-aliases.txt"
inlineconstexpr

The alias-table filename for logical paths and their physical backing files.

◆ CONSOLE_STRINGS

const std::array<ConsoleString, 147> coastline::CONSOLE_STRINGS
extern

The messages the Japanese release draws in Japanese and the messages the other releases draw in their place, then the messages of the race that a string of BRString.dll draws in the PC release, paired across the releases by the code that draws them.

A message without lines in a release is absent from that release.

◆ SAVE_FOLDER_STRINGS

const std::array<SaveFolderString, 10> coastline::SAVE_FOLDER_STRINGS
extern

The messages of the console that name the Controller Pak where the game saves to a folder, as the import writes them to strings/en-us.json with the text of the USA cartridge.

Every other language takes them from there.

◆ LIBRARY_STRING_COUNT

std::size_t coastline::LIBRARY_STRING_COUNT = 303
inlineconstexpr

The number of strings of BRString.dll, numbered from 1.

◆ LIBRARY_STRING_KEYS

const std::array<std::string_view, LIBRARY_STRING_COUNT> coastline::LIBRARY_STRING_KEYS
extern

The key of each string of BRString.dll, by its number less 1.

The import writes the string under the key, and GetStringResource() of the race reads it from there. A key of the race (race.) is also in CONSOLE_STRINGS, where the PC and the Nintendo 64 releases draw the same text in the same place, and every other key (pc.) is the PC release's alone.

◆ CONTROLLER_PORTS

std::size_t coastline::CONTROLLER_PORTS = 4
inlineconstexpr

The number of controller ports of the console.

◆ PAK_PAGE_BYTES

std::size_t coastline::PAK_PAGE_BYTES = 0x100
inlineconstexpr

The bytes of a page of a Controller Pak, the unit a note takes its room in.

◆ PAK_PAGES

std::size_t coastline::PAK_PAGES = 123
inlineconstexpr

The pages of a Controller Pak free for notes.

◆ PAK_NOTES

std::size_t coastline::PAK_NOTES = 16
inlineconstexpr

The notes a Controller Pak has room for.

◆ PAK_SETTINGS_NOTE

std::string_view coastline::PAK_SETTINGS_NOTE = "TOP GEAR OPTIONS"
inlineconstexpr

The note of the settings of the options menu, stored with the settings of the game.

◆ PAK_IMAGE_BYTES

std::size_t coastline::PAK_IMAGE_BYTES = 0x8000
inlineconstexpr

The bytes of the image of a Controller Pak, as emulators and the tools of a pak store one.

◆ CONTROL_KEYS

std::array<std::string_view, CONTROL_ACTION_COUNT> coastline::CONTROL_KEYS
inlineconstexpr
Initial value:
{
"SteerLeft", "SteerRight", "Accelerate", "Brake", "Reverse",
"GearUp", "GearDown", "CockpitCamera", "BumperCamera", "ChaseCamera",
"PauseMenuUp", "PauseMenuDown", "PauseMenuSelect", "Pause", "StartOrRespawn",
"MenuA", "MenuB", "MenuZ", "MenuStart", "MenuL",
"MenuR", "MenuCUp", "MenuCDown", "MenuCLeft", "MenuCRight",
"MenuDUp", "MenuDDown", "MenuDLeft", "MenuDRight", "MenuStickLeft",
"MenuStickRight", "MenuStickUp", "MenuStickDown",
}

The keys of the Controls section, by ControlAction.

◆ CONTROL_PRESET_KEY

std::string_view coastline::CONTROL_PRESET_KEY = "Preset"
inlineconstexpr

The key of the Controls section that chooses a preset.

◆ DEAD_ZONE_KEY

std::string_view coastline::DEAD_ZONE_KEY = "DeadZone"
inlineconstexpr

The key of the Controls section with the share of the travel of an axis that reads as 0.

◆ PLAYER_DEVICE_KEYS

std::array<std::string_view, 2> coastline::PLAYER_DEVICE_KEYS {"Player1", "Player2"}
inlineconstexpr

The keys of the Controls section that choose the input device of each player.

◆ DEFAULT_CONTROL_PRESET

ControlPreset coastline::DEFAULT_CONTROL_PRESET
inlineconstexpr

The preset of an absent or unknown Preset key.

◆ RACE_CONTROL_ACTIONS

std::size_t coastline::RACE_CONTROL_ACTIONS = CONTROL_CHASE_CAMERA + 1
inlineconstexpr

The actions of a race, from CONTROL_STEER_LEFT to CONTROL_CHASE_CAMERA.

◆ CONTROL_PRESETS

std::array<ControlPreset, 7> coastline::CONTROL_PRESETS
inlineconstexpr

The presets the Preset key chooses from, the first the default.

Kart follows Mario Kart 8 on the Pro Controller, with the east button for accelerate and A of the menus, and the south button for brake and B of the menus.

The five after Kart are the button layouts of the controller screen of the Nintendo 64 release, as TranslateControllerInput() of the console reads them, with A of the console on the south button, B on the east, Z on the left trigger, L and R on the shoulders, and the C buttons on the right stick. An action of the console that needs two buttons at once has the second alone: down reverses without A, and the e-brake of A and B, or of C down in TypeB, has no binding.

◆ CONTROL_FULL

int coastline::CONTROL_FULL = 32768
inlineconstexpr

The magnitude of a button held down or of an axis at its end.

◆ DECAL_SLOTS

int coastline::DECAL_SLOTS = 10
inlineconstexpr

The decals of a car, each the texture of the material of the same number.

◆ CAR_MATERIALS

int coastline::CAR_MATERIALS = 12
inlineconstexpr

The materials of a car whose palettes the colour of the car paints.

◆ CAR_MATERIAL_PAINT

int coastline::CAR_MATERIAL_PAINT = 2
inlineconstexpr

The material whose palette is the paint, saved with the decals.

◆ CAR_MATERIAL_HEADLIGHTS

int coastline::CAR_MATERIAL_HEADLIGHTS = 10
inlineconstexpr

The material whose palette is the headlights.

◆ CAR_MATERIAL_REAR_LIGHTS

int coastline::CAR_MATERIAL_REAR_LIGHTS = 11
inlineconstexpr

The material whose palette is the rear lights.

◆ DISC_IMAGE_EXTENSIONS

std::array<std::string_view, 19> coastline::DISC_IMAGE_EXTENSIONS
inlineconstexpr
Initial value:
{".b5i",
".b5t",
".b6i",
".b6t",
".bin",
".bwi",
".bws",
".bwt",
".ccd",
".cdi",
".cue",
".img",
".iso",
".isz",
".mdf",
".mds",
".nrg",
".pdi",
".sub"}

Disc images, track metadata, and companion files accepted by the importer.

◆ WIZARD_CARTRIDGES

int coastline::WIZARD_CARTRIDGES = 3
inlineconstexpr

The number of supported ROM releases.

◆ GRID_WIDTH

int coastline::GRID_WIDTH = GRID_COLUMNS * CELL_WIDTH
inlineconstexpr

The width of the grid in pixels, 640.

◆ GRID_HEIGHT

int coastline::GRID_HEIGHT = GRID_ROWS * CELL_HEIGHT
inlineconstexpr

The height of the grid in pixels, 400.

◆ GRID_COLUMNS

int coastline::GRID_COLUMNS = 80
inlineconstexpr

The columns of the grid.

◆ GRID_ROWS

int coastline::GRID_ROWS = 25
inlineconstexpr

The rows of the grid.

◆ CELL_WIDTH

int coastline::CELL_WIDTH = 8
inlineconstexpr

The width of a cell in pixels.

◆ CELL_HEIGHT

int coastline::CELL_HEIGHT = 16
inlineconstexpr

The height of a cell in pixels.

◆ CGA_PALETTE

std::array<std::array<std::uint8_t, 3>, 16> coastline::CGA_PALETTE
inlineconstexpr
Initial value:
{{
{0x00, 0x00, 0x00},
{0x00, 0x00, 0xAA},
{0x00, 0xAA, 0x00},
{0x00, 0xAA, 0xAA},
{0xAA, 0x00, 0x00},
{0xAA, 0x00, 0xAA},
{0xAA, 0x55, 0x00},
{0xAA, 0xAA, 0xAA},
{0x55, 0x55, 0x55},
{0x55, 0x55, 0xFF},
{0x55, 0xFF, 0x55},
{0x55, 0xFF, 0xFF},
{0xFF, 0x55, 0x55},
{0xFF, 0x55, 0xFF},
{0xFF, 0xFF, 0x55},
{0xFF, 0xFF, 0xFF},
}}

The red, green, and blue of each colour of CGA, by its number.

◆ REPLACEMENT_GLYPH

std::uint8_t coastline::REPLACEMENT_GLYPH = 0
inlineconstexpr

The glyph drawn for a character code page 437 does not have.

◆ HALF_PI

float coastline::HALF_PI = 1.570796371f
constexpr

A quarter turn in radians, in the single precision of the console.

◆ PI

float coastline::PI = 3.141592741f
constexpr

A half turn in radians, in the single precision of the console.

◆ TWO_PI

float coastline::TWO_PI = 6.283185482f
constexpr

A whole turn in radians, in the single precision of the console.

◆ SCREEN_WIDTH

float coastline::SCREEN_WIDTH = 320.0f
constexpr

The low-resolution screen of the console, in pixels.

◆ SCREEN_HEIGHT

float coastline::SCREEN_HEIGHT = 240.0f
constexpr

The height of the low-resolution console screen, in pixels.

◆ SOUND_PADDING

std::size_t coastline::SOUND_PADDING = 0x100
constexpr

The silence after each sound, for the mixer to read zeros past its end.

◆ SFX_STEP_ONE

std::uint64_t coastline::SFX_STEP_ONE = 1ull << 32
constexpr

The 32.32 step that plays a sample at its own rate.

◆ MAX_SFX_VOLUME

u8 coastline::MAX_SFX_VOLUME = 0xFF
constexpr

The volume of the sound effects at full level.

◆ COMBINED

std::uint32_t coastline::COMBINED = 0
constexpr

The previous cycle's result as an RDP colour-combiner input.

◆ TEXEL0

std::uint32_t coastline::TEXEL0 = 1
constexpr

The first sampled texel as an RDP colour-combiner input.

◆ TEXEL1

std::uint32_t coastline::TEXEL1 = 2
constexpr

The second sampled texel as an RDP colour-combiner input.

◆ PRIMITIVE

std::uint32_t coastline::PRIMITIVE = 3
constexpr

The primitive colour as an RDP colour-combiner input.

◆ SHADE

std::uint32_t coastline::SHADE = 4
constexpr

The interpolated vertex colour as an RDP colour-combiner input.

◆ ENVIRONMENT

std::uint32_t coastline::ENVIRONMENT = 5
constexpr

The environment colour as an RDP colour-combiner input.

◆ ZERO_AB

std::uint32_t coastline::ZERO_AB = 15
constexpr

The zero selector for the A and B RDP colour-combiner operands.

◆ ZERO_D

std::uint32_t coastline::ZERO_D = 7
constexpr

The zero selector for the D RDP colour-combiner operand.

◆ ZERO_ALPHA

std::uint32_t coastline::ZERO_ALPHA = 7
constexpr

The zero selector for an RDP alpha-combiner operand.

◆ STAGE_CAR_PARTS

std::array<std::string_view, 7> coastline::STAGE_CAR_PARTS
inlineconstexpr
Initial value:
{"lod0-nearDetail",
"lod0-textured",
"lod0-paint",
"lod0-wheel0",
"lod0-wheel1",
"lod0-wheel2",
"lod0-wheel3"}

The parts of a car RenderVehicleModel() draws in the menus: the near detail, the textured parts, the painted body, and the normal wheels.

The underside shows only from below.

◆ STAGE_CAR_LIGHTING

const Lighting coastline::STAGE_CAR_LIGHTING
extern

The lights RenderVehicleModel() lights a car with in the menus: g_DefaultLights, from (84, 84, 84), in the colours of SetupWeatherLights() in clear weather.

◆ GHOST_NOTE_SIZE

std::size_t coastline::GHOST_NOTE_SIZE = 0x3A00
inlineconstexpr

The size of the note of a ghost car, 58 pages.

◆ GHOST_RECORDING_CAPACITY

std::size_t coastline::GHOST_RECORDING_CAPACITY = 0xDE5C
inlineconstexpr

The capacity of the recording of the console, its header included.

◆ USA_MUSIC_MODULES

UsaMusicModule coastline::USA_MUSIC_MODULES[]
inlineconstexpr
Initial value:
= {{0x0EBC00, "menu"},
{0x113660, "race1"},
{0x12EAB0, "race2"},
{0x149C80, "race3"},
{0x164B60, "race4"},
{0x17FD10, "race5"}}

The music modules of the USA cartridge: the menus, then the modules of the tracks.

The table of the tracks also lists 0x19BC10 for track 10, a sound sample rather than a module.

◆ DISC_CONVERTER_VERSION

int coastline::DISC_CONVERTER_VERSION = 2
inlineconstexpr

The version of the conversion of the Boss Rally disc: the cars, the tracks, the images, and the other files ImportDisc() converts, n64model.cpp included.

Increase it with every change to the output of the conversion, so that the game warns about data imported before the change.

◆ CARTRIDGE_CONVERTER_VERSION

int coastline::CARTRIDGE_CONVERTER_VERSION = 1
inlineconstexpr

The version of the conversion of a Top Gear Rally cartridge: the models, the images, the music, and the other files ImportRom() converts, n64model.cpp included.

Increase it with every change to the output of the conversion, so that the game warns about data imported before the change.

◆ DEFAULT_LANGUAGE

std::string_view coastline::DEFAULT_LANGUAGE = "en-us"
inlineconstexpr

The language unless the configuration or the command line selects another.

◆ MENU_ITEM_ADJUSTABLE

u32 coastline::MENU_ITEM_ADJUSTABLE = 0x01
constexpr

The flag of an item whose up and down change it in place, as MenuResult::Up and Down.

◆ MENU_ITEM_IMMEDIATE

u32 coastline::MENU_ITEM_IMMEDIATE = 0x02
constexpr

The flag of an item chosen at once, without fading the screen out.

◆ MENU_ITEM_SPINNING

u32 coastline::MENU_ITEM_SPINNING = 0x04
constexpr

The flag of an item drawn as its model spinning round as the items slide.

◆ MENU_ITEM_UNAVAILABLE

u32 coastline::MENU_ITEM_UNAVAILABLE = 0x08
constexpr

The flag of an item that cannot be chosen, whose screen explains why.

◆ MENU_ITEM_MIRRORED_MODEL

u32 coastline::MENU_ITEM_MIRRORED_MODEL = 0x10
constexpr

The flag of an item whose model is drawn mirrored.

◆ MENU_ITEM_FIRST_PLAYER

u32 coastline::MENU_ITEM_FIRST_PLAYER = 0x20
constexpr

The flag of an item only the first player may choose.

◆ MENU_ITEM_LOCKED

u32 coastline::MENU_ITEM_LOCKED = 0x80000000
constexpr

The flag of an item that cannot be chosen, without a reason shown.

◆ N64_AUDIO_RATE

int coastline::N64_AUDIO_RATE = 21998
inlineconstexpr

The sample rate of the imported music, in stereo frames per second.

◆ DEFAULT_PACK

std::string_view coastline::DEFAULT_PACK = "default"
inlineconstexpr

The name of the asset pack of the import, the directory assets/default.

◆ FRAME_RATE_STATES

int coastline::FRAME_RATE_STATES = 3
inlineconstexpr

The states of F in g_bShowFpsCounter: 0 for off, 1 for the frame rate, and 2 for both.

◆ FRAME_RATE_STATISTICS

int coastline::FRAME_RATE_STATISTICS = 2
inlineconstexpr

The state of F in g_bShowFpsCounter that shows the statistics beside the frame rate.

◆ PC_RECORD_TRACKS

int coastline::PC_RECORD_TRACKS = 15
constexpr

Track record slots in race-engine order, including the SDL Bonus Track.

◆ RESULT_LAPS

int coastline::RESULT_LAPS = 12
constexpr

The most laps of a race the results record.

◆ SCRIPT_PRESS_FRAMES

int coastline::SCRIPT_PRESS_FRAMES = 6
inlineconstexpr

The frames a press of a button or a key lasts when its line gives no number.

◆ IDENTITY_MATRIX

Matrix4 coastline::IDENTITY_MATRIX {1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1}
inlineconstexpr

The matrix that changes nothing.

◆ CLEAR_LIGHT_RAMP

std::array<std::array<float, 3>, 4> coastline::CLEAR_LIGHT_RAMP
inlineconstexpr
Initial value:
{
{{63 / 255.0f, 63 / 255.0f, 51 / 255.0f},
{127 / 255.0f, 127 / 255.0f, 102 / 255.0f},
{190 / 255.0f, 190 / 255.0f, 153 / 255.0f},
{1.0f, 1.0f, 204 / 255.0f}}}

The ambient colours of a ramped instance of a track on a clear day, from 0 to 1.

◆ MAX_CAR_SHADOWS

std::size_t coastline::MAX_CAR_SHADOWS = 4
inlineconstexpr

The most shadows of cars that fall on an instance of a track.

◆ CAR_DAMAGE_SIDES

int coastline::CAR_DAMAGE_SIDES = 8
constexpr

The number of sides of a car that take damage, as IncrementDamageTextureLevel() counts them.

◆ CAR_DAMAGE_LEVELS

int coastline::CAR_DAMAGE_LEVELS = 3
constexpr

The levels of damage of a car after the first, as LoadCarPaintTextures() makes them.

◆ CONSOLE_TRACK_COUNT

int coastline::CONSOLE_TRACK_COUNT = 10
inlineconstexpr

Five console tracks and their five mirrored variants precede additional tracks.

◆ EXTRA_MENU_TRACKS

std::array<ExtraMenuTrack, 5> coastline::EXTRA_MENU_TRACKS
inlineconstexpr
Initial value:
{{
{5, "Race Track", "race", false},
{11, "Mirror Race Track", "race", true},
{14, "Bonus Track", "bonus", false},
{13, "Mirror Bonus Track", "bonus", true},
{12, "Season Champion", "gamewin", false, false},
}}

PC-only track entries; Season Champion (gamewin) remains indexed but unavailable for ordinary selection.

◆ MENU_TRACK_COUNT

int coastline::MENU_TRACK_COUNT
inlineconstexpr
Initial value:
=
CONSOLE_TRACK_COUNT + static_cast<int>(EXTRA_MENU_TRACKS.size())
constexpr std::array< ExtraMenuTrack, 5 > EXTRA_MENU_TRACKS
PC-only track entries; Season Champion (gamewin) remains indexed but unavailable for ordinary selecti...
Definition trackcatalog.h:23
constexpr int CONSOLE_TRACK_COUNT
Five console tracks and their five mirrored variants precede additional tracks.
Definition trackcatalog.h:10

The number of track entries before menu actions, including unavailable entries.

◆ MAX_VOLUME_LEVEL

int coastline::MAX_VOLUME_LEVEL = 10
inlineconstexpr

The loudest level of the options menu.

◆ MAX_RACE_VOLUME_LEVEL

int coastline::MAX_RACE_VOLUME_LEVEL = 9
inlineconstexpr

The loudest level of the race engine.