nCine namespace

Root namespace of nCine game engine.

Namespaces

namespace AudioMixer
namespace Backends
Platform-specific backends.
namespace Primitives
Primitives.
namespace RHI
Render Hardware Interface — compile-time-selectable graphics backend abstraction.

Classes

class AccelerometerEvent
Accelerometer sensor reading.
class AicaAudioDevice
Dreamcast implementation of IAudioDevice on top of the AICA.
class ALAudioDevice
OpenAL implementation of IAudioDevice.
class AmigaAudioDevice
Classic Amiga implementation of IAudioDevice on top of ahi.device.
class AndroidApplication
Main entry point and handler for Android applications.
class AnimatedSprite
Textured sprite that cycles through one or more frame animations.
class AppConfiguration
Initialization settings for an nCine application.
class Application
Base class for the main entry point of an nCine application.
class AsndAudioDevice
Wii/GameCube implementation of IAudioDevice on top of libogc's ASND.
class AudioBuffer
Fully decoded audio buffer.
class AudioBufferPlayer
Plays back a fully decoded AudioBuffer.
class AudioDeviceBase
Backend-independent part of an audio device.
class AudioLoaderMpt
Audio loader for tracker module formats, backed by libopenmpt.
class AudioLoaderOgg
Audio loader for the Ogg Vorbis format, backed by libvorbis.
class AudioLoaderWav
Audio loader for the WAVE (.wav) format.
class AudioLoaderXmp
Audio loader for tracker module formats, backed by libxmp (see AudioReaderXmp).
class AudioReaderMpt
Audio reader for tracker module formats, backed by libopenmpt.
class AudioReaderOgg
Audio reader for the Ogg Vorbis format, backed by libvorbis.
class AudioReaderWav
Audio reader for the WAVE (.wav) format.
class AudioReaderXmp
Audio reader for tracker module formats, backed by libxmp.
class AudioStream
Streams audio decoded on the fly into a rotating set of backend buffers.
class AudioStreamPlayer
Plays back an AudioStream decoded on the fly.
class Barrier
Barrier for thread synchronization.
class BaseSprite
Base class for textured sprites.
class BinaryShaderCache
Caches compiled OpenGL shader programs in binary form on disk.
class BitArray
Dynamically allocated array of bits.
class BitArrayIndex
Proxy referring to a single bit of a BitArray.
template<class T>
class BitSet
Fixed-size sequence of bits backed by an unsigned integer.
class Camera
Provides the projection and view matrices used by shaders.
class Clock
High-resolution monotonic system clock.
class ColorAffector
Affector that animates the color of a particle.
class CondVariable
Condition variable for thread synchronization.
class DisplayMode
Describes the pixel format and buffering properties of a display surface.
class DrawableNode
Base class for scene nodes that can be drawn through the render queue.
template<class K>
class FNV1aHashFunc
Fowler-Noll-Vo (FNV-1a) hash function.
class FrameStatistics
Frame timing and backend counters, averaged for an on-screen overlay.
class FrameTimer
Tracks per-frame timing and computes the average FPS and frame time multiplier.
class Geometry
Contains the vertex and index buffer data for a drawable node.
struct HatState
Bit flags describing the direction of a joystick hat (D-pad).
class I18n
Provides internationalization and translation support.
class IAppEventHandler
Interface for handling nCine application lifecycle and frame events.
class IAudioDevice
Interface for an audio device backend.
class IAudioLoader
Interface for an audio loader.
class IAudioPlayer
Interface for an audio player.
class IAudioReader
Interface for an audio reader.
class IDebugOverlay
Interface for an on-screen debug overlay.
class IGfxDevice
Represents the interface to the graphics device where everything is rendered.
class IInputEventHandler
Interface for handling input events from keyboard, touch screen, mouse, accelerometer and joysticks.
class IInputManager
Interface for querying input state and dispatching input events.
class ImGuiDebugOverlay
Debug overlay implemented with the ImGui interface.
class ImGuiDrawing
Handles ImGui drawing.
class ITextureLoader
Texture loader interface class.
class IThreadCommand
Thread pool command interface.
class IThreadPool
Thread pool interface.
class JoyAxisEvent
Joystick axis event.
class JoyButtonEvent
Joystick button event.
class JoyConnectionEvent
Joystick connection or disconnection event.
class JoyHatEvent
Joystick hat event.
class JoyMappedAxisEvent
Mapped joystick axis event.
class JoyMappedButtonEvent
Mapped joystick button event.
class JoyMappedState
Current state of a joystick translated through its mapping into unified buttons and axes.
class JoyMapping
Translation layer that maps raw gamepad and joystick inputs to a unified layout.
class JoystickGuid
Parsed 16-byte GUID that identifies a joystick model.
class JoystickState
Current raw state of a joystick.
class KeyboardEvent
Keyboard key event.
class KeyboardState
Current state of the keyboard.
template<class T, class TLock>
class LockedPtr
Pointer wrapper that keeps the object locked for the duration of its existence.
class MainApplication
Main entry point and event loop driver for standard (desktop) applications.
class Material
Contains material data for a drawable node.
class MeshSprite
A scene node representing a mesh with vertices and UVs.
class MouseEvent
Mouse button event.
class MouseState
Current state of the mouse.
class Mutex
Mutex for thread synchronization.
class N64AudioDevice
Nintendo 64 implementation of IAudioDevice on top of libdragon's RSP mixer.
class NdspAudioDevice
Implementation of IAudioDevice on top of the Nintendo 3DS's NDSP.
class Object
Base class of all nCine objects.
class Particle
Renders a single particle.
class ParticleAffector
Base class for all particle affectors.
struct ParticleInitializer
Initialization parameters for a batch of emitted particles.
class ParticleSystem
Scene node that emits and simulates a pool of textured particles.
class PositionAffector
Affector that animates the position of a particle.
class Ps2AudioDevice
PlayStation 2 implementation of IAudioDevice on top of audsrv.
class Ps3AudioDevice
PlayStation 3 implementation of IAudioDevice on top of PSL1GHT's libaudio.
class PspAudioDevice
Implementation of IAudioDevice on top of the PSP's sceAudio hardware channel.
class RandomGenerator
PCG32 pseudo-random number generator.
class ReadWriteLock
Read/write lock for thread synchronization.
class RectAnimation
Sequence of texture rectangles forming a sprite animation.
class RenderBatcher
Merges compatible render commands into fewer draw calls.
class RenderBuffersManager
Suballocates vertex, index and uniform data from a pool of OpenGL buffer objects.
class RenderCommand
Holds all the state needed to issue a single draw call.
class RenderCommandPool
Pool of reusable render commands.
class RenderDocCapture
In-application integration of the RenderDoc graphics debugger.
class RenderQueue
Sorts and issues the render commands collected during a scene graph visit.
class RenderResources
Creates and holds the OpenGL rendering resources shared by the whole application.
class RenderStatistics
Gathers statistics about the rendering subsystem.
class RenderVaoPool
Pool of reusable Vertex Array Objects.
class RotationAffector
Affector that animates the rotation of a particle.
class SceneNode
Base node of the scene graph transformation hierarchy.
class ScreenViewport
Viewport that renders directly to the screen.
class ScrollEvent
Scroll event (mouse wheel, touchpad gesture, etc.).
class SdlAudioDevice
Implementation of IAudioDevice on top of SDL2's audio queue.
class ServiceLocator
Central registry that provides engine services to requesting classes.
class Shader
GPU shader program usable by materials and drawable nodes.
class ShaderState
Binds a custom shader to a drawable node and feeds its uniforms and textures.
class SizeAffector
Affector that animates the scale of a particle.
class Sprite
Scene node that draws a single textured quad.
template<class K, class T, std::uint32_t Capacity, class HashFunc = xxHash32Func<K>>
class StaticHashMap
Statically allocated hashmap with open addressing and leapfrog probing.
template<class K, class T, class HashFunc, std::uint32_t Capacity, bool IsConst>
struct StaticHashMapHelperTraits
Primary template for the StaticHashMapIterator type traits helper.
template<class K, class T, class HashFunc, std::uint32_t Capacity>
struct StaticHashMapHelperTraits<K, T, HashFunc, Capacity, false>
Type traits used by the non-constant StaticHashMapIterator.
template<class K, class T, class HashFunc, std::uint32_t Capacity>
struct StaticHashMapHelperTraits<K, T, HashFunc, Capacity, true>
Type traits used by the constant StaticHashMapIterator.
template<class K, class T, class HashFunc, std::uint32_t Capacity, bool IsConst>
class StaticHashMapIterator
Bidirectional iterator over the elements of a StaticHashMap.
struct StreamDecodeRequest
Request to decode one buffer of audio stream data, usually on the decoding thread.
template<typename T>
struct Task
Awaitable result of an asynchronous coroutine operation.
class TextInputEvent
Text input event.
class Texture
Image data uploaded to the GPU and sampled by shaders.
class TextureFormat
Backend-neutral pixel format descriptor of a texture.
class TextureLoaderDds
Texture loader for the DirectDraw Surface (.dds) format.
class TextureLoaderKtx
Texture loader for the Khronos Texture (.ktx) format.
class TextureLoaderPkm
Texture loader for the ETC1 PKM (.pkm) format.
class TextureLoaderPng
Texture loader for the Portable Network Graphics (.png) format.
class TextureLoaderPvr
Texture loader for the PowerVR (.pvr) format.
class TextureLoaderQoi
Texture loader for the Quite OK Image (.qoi) format.
class TextureLoaderRaw
Texture loader that describes an empty raw-format texture.
class Thread
Operating system thread.
class ThreadAffinityMask
CPU affinity mask for a thread.
class ThreadPool
Thread pool.
class Timer
Stopwatch that accumulates elapsed time across start/stop intervals.
class TimeStamp
Wraps a clock counter value representing a point in time or a duration.
class TouchEvent
Screen touch event.
class UwpApplication
Main entry point and handler for UWP (Universal Windows Platform) applications.
class VelocityAffector
Affector that animates the velocity of a particle.
class Viewport
Render target with its own scene root, camera and render queue.
template<class K>
class xxHash32Func
xxHash3 hash function producing a 32-bit value
template<class K>
class xxHash64Func
xxHash3 hash function producing a 64-bit value

Enums

enum class PrimitiveType : std::uint32_t { Points = 0x0000, Lines = 0x0001, LineLoop = 0x0002, LineStrip = 0x0003, Triangles = 0x0004, TriangleStrip = 0x0005, TriangleFan = 0x0006 }
Primitive topology of a draw call.
enum class BlendingFactor : std::uint32_t { Zero = 0x0000, One = 0x0001, SrcColor = 0x0300, OneMinusSrcColor = 0x0301, SrcAlpha = 0x0302, OneMinusSrcAlpha = 0x0303, DstAlpha = 0x0304, OneMinusDstAlpha = 0x0305, DstColor = 0x0306, OneMinusDstColor = 0x0307, SrcAlphaSaturate = 0x0308, ConstantColor = 0x8001, OneMinusConstantColor = 0x8002, ConstantAlpha = 0x8003, OneMinusConstantAlpha = 0x8004 }
Source or destination factor of the blending equation.
enum class BufferUsage : std::uint32_t { StreamDraw = 0x88E0, StaticDraw = 0x88E4, DynamicDraw = 0x88E8 }
Expected update pattern of a vertex or index buffer.
enum class BufferTarget : std::uint32_t { Vertex = 0x8892, Index = 0x8893, Uniform = 0x8A11 }
Binding target of a buffer object.
enum class MapFlags : std::uint32_t { None = 0, Write = 0x0002, InvalidateRange = 0x0004, InvalidateBuffer = 0x0008, FlushExplicit = 0x0010, Unsynchronized = 0x0020, Persistent = 0x0040, Coherent = 0x0080 }
Buffer mapping and immutable storage flags.
enum class IndexFormat : std::uint32_t { UInt16 = 0x1403, UInt32 = 0x1405 }
Data format of the indices in an index buffer.
enum class CullFaceMode : std::uint32_t { Front = 0x0404, Back = 0x0405, FrontAndBack = 0x0408 }
Face culling mode.
enum class VertexAttribType : std::uint32_t { UnsignedByte = 0x1401, Float = 0x1406 }
Component data type of a vertex attribute.
enum class ShaderStage { Vertex, Fragment }
Programmable pipeline stage a shader source is attached to.
enum class DepthStencilFormat { None, Depth16, Depth24, Depth24_Stencil8 }
Depth and stencil format of a render target.
enum class ClearFlags : std::uint32_t { None = 0, Color = 0x01, Depth = 0x02, Stencil = 0x04 }
Buffers of a render target that can be cleared.
enum class PixelFormat { Unknown, R8, RG8, RGB8, RGBA8, RGB565, RGB5A1, RGBA4, RGB16F, RGBA16F, RGB32F, RGBA32F, Depth16, Depth24, Depth32F, DXT1RGB, DXT1RGBA, DXT3, DXT5, ETC1, ETC2RGB8, ETC2RGB8A1, ETC2RGBA8, EAC_R11, EAC_RG11, ATC_RGB, ATC_RGBA_Explicit, ATC_RGBA_Interpolated, PVRTC_2BPP_RGB, PVRTC_2BPP_RGBA, PVRTC_4BPP_RGB, PVRTC_4BPP_RGBA, ASTC_4x4, ASTC_5x4, ASTC_5x5, ASTC_6x5, ASTC_6x6, ASTC_8x5, ASTC_8x6, ASTC_8x8, ASTC_10x5, ASTC_10x6, ASTC_10x8, ASTC_10x10, ASTC_12x10, ASTC_12x12 }
Pixel format of texture data.
enum class TextureTarget { Texture2D }
Type of texture the backend allocates and binds.
enum class SamplerFilter { Unknown, Nearest, Linear, NearestMipmapNearest, LinearMipmapNearest, NearestMipmapLinear, LinearMipmapLinear }
Texture minification and magnification filtering modes.
enum class SamplerWrapping { Unknown, ClampToEdge, MirroredRepeat, Repeat }
Texture coordinate wrapping modes.
enum class SwizzleChannel { Red, Green, Blue, Alpha, Zero, One }
Source for a sampled texture channel (see Texture::SetSwizzle()).
enum class JoystickGuidType { Unknown, Standard, Default, Hidapi, Xinput }
Well-known joystick GUID layouts.
enum class ButtonName : std::int16_t { Unknown = -1, A = 0, B, X, Y, Back, Guide, Start, LeftStick, RightStick, LeftBumper, RightBumper, Up, Down, Left, Right, Misc1, Paddle1, Paddle2, Paddle3, Paddle4, Touchpad, Count }
Gamepad buttons.
enum class AxisName : std::int16_t { Unknown = -1, LeftX = 0, LeftY, RightX, RightY, LeftTrigger, RightTrigger }
Gamepad axes.
enum class TouchEventType { Down, Up, Move, PointerDown, PointerUp }
Type of a touch event.
enum class MouseButton : short int { Left, Right, Middle, Fourth, Fifth }
Mouse buttons.
enum class Keys { Backspace, Tab, Return, Escape, Space, Quote, Plus, Comma, Minus, Period, Slash, D0, D1, D2, D3, D4, D5, D6, D7, D8, D9, Semicolon, LeftBracket, Backslash, RightBracket, Backquote, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, Delete, NumPad0, NumPad1, NumPad2, NumPad3, NumPad4, NumPad5, NumPad6, NumPad7, NumPad8, NumPad9, NumPadPeriod, NumPadDivide, NumPadMultiply, NumPadMinus, NumPadPlus, NumPadEnter, NumPadEquals, Up, Down, Right, Left, Insert, Home, End, PageUp, PageDown, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, NumLock, CapsLock, ScrollLock, RShift, LShift, RCtrl, LCtrl, RAlt, LAlt, RSuper, LSuper, PrintScreen, Pause, Menu, Clear, Exclaim, QuoteDbl, Hash, Dollar, Ampersand, LeftParen, RightParen, Asterisk, Colon, Less, Equals, Greater, Question, At, Caret, Underscore, Mode, Application, Help, SysReq, Power, Undo, World1, World2, SoftLeft, SoftRight, Back, Call, EndCall, Star, Pound, DpadCenter, VolumeUp, VolumeDown, Camera, Sym, Explorer, Envelope, Num, HeadsetHook, Focus, Notification, Search, MediaPlayPause, MediaStop, MediaNext, MediaPrevious, MediaRewind, MediaFastForward, Mute, PictSymbols, SwitchCharset, ButtonA, ButtonB, ButtonC, ButtonX, ButtonY, ButtonZ, ButtonL1, ButtonR1, ButtonL2, ButtonR2, ButtonThumbLeft, ButtonThumbRight, ButtonStart, ButtonSelect, ButtonMode, FunctionKey, MoveHome, MoveEnd, Forward, MediaPlay, MediaPause, MediaClose, MediaEject, MediaRecord, NumPadComma, NumPadLeftParen, NumPadRightParen, VolumeMute, Info, ChannelUp, ChannelDown, ZoomIn, ZoomOut, TV, Window, Guide, DVR, Bookmark, Captions, Settings, TVPower, TVInput, STBPower, STBInput, AVRPower, AVRInput, ProgRed, ProgGreen, ProgYellow, ProgBlue, AppSwitch, Button1, Button2, Button3, Button4, Button5, Button6, Button7, Button8, Button9, Button10, Button11, Button12, Button13, Button14, Button15, Button16, Count, Unknown = Count }
Keyboard key symbols.
enum KeyMod { None = 0x0000, LShift = 0x0001, RShift = 0x0002, LCtrl = 0x0040, RCtrl = 0x0080, LAlt = 0x0100, RAlt = 0x0200, LSuper = 0x0400, RSuper = 0x0800, NumLock = 0x1000, CapsLock = 0x2000, Mode = 0x4000, Sym = 0x8000, Ctrl = (LCtrl | RCtrl), Shift = (LShift | RShift), Alt = (LAlt | RAlt), Super = (LSuper | RSuper), Mask = (Ctrl | Shift | Alt | Super), Count }
Keyboard modifier flags.

Typedefs

using CreateAppEventHandlerDelegate = std::unique_ptr<IAppEventHandler>(*)()
Delegate that creates an instance of IAppEventHandler.
using hash_t = std::uint32_t
32-bit hash value
using hash64_t = std::uint64_t
64-bit hash value
template<class K, class V, class Hash = xxHash64Func<K>, class Eq = phmap::priv::hash_default_eq<K>>
using HashMap = phmap::flat_hash_map<K, V, Hash, Eq>
Generic hash map.
using FenceHandle = void*
Opaque handle to a GPU fence created by the device.
using NativeArgument = char*
Native argument type, wchar_t* on Windows, otherwise char*.

Functions

auto theApplication() -> Application&
Returns the application instance.
auto sinApprox(float x) -> float
Returns $ \sin(x) $ as cheaply as the platform can, within 1e-5 of full scale for |x| <= 64.
auto cosApprox(float x) -> float
Returns $ \cos(x) $ as cheaply as the platform can, see sinApprox().
void sincosApprox(float x, float& s, float& c)
Returns both $ \sin(x) $ and $ \cos(x) $ as cheaply as the platform can, see sinApprox().
auto atan2Approx(float y, float x) -> float
Returns $ \operatorname{atan2}(y, x) $ as cheaply as the platform can, within 1.2e-5 rad.
auto floorFast(float x) -> float
Returns $ \lfloor x \rfloor $ without a libm call, for $ |x| < 2^{22} $ .
auto ceilFast(float x) -> float
Returns $ \lceil x \rceil $ without a libm call, for $ |x| < 2^{22} $ , see floorFast().
auto roundFast(float x) -> float
Returns $ x $ rounded to the nearest integer without a libm call, for $ |x| < 2^{22} $ , see floorFast().
auto sqrtApprox(float x) -> float
Returns $ \sqrt{x} $ as cheaply as the platform can, and 0 for a non-positive argument.
auto lerp(float a, float b, float ratio) -> float
Linearly interpolates between two values by the given ratio.
auto lerp(std::int32_t a, std::int32_t b, float ratio) -> std::int32_t
Linearly interpolates between two integers by the given ratio, rounding the result.
auto lerpByTime(float a, float b, float ratio, float timeMult) -> float
Frame-rate independent interpolation between two values.
auto copyStringFirst(char* dest, std::int32_t destSize, const char* source, std::int32_t count = -1) -> std::int32_t
Copies the beginning of a string into a fixed-size buffer, always null-terminating it.
template<std::size_t size>
auto copyStringFirst(char(&dest)[size], const char* source, std::int32_t count = -1) -> std::int32_t
Copies the beginning of a string into a fixed-size array, deducing its size.
template<std::size_t size>
auto copyStringFirst(char(&dest)[size], Containers::StringView source) -> std::int32_t
Copies the beginning of a string view into a fixed-size array, deducing its size.
auto formatString(char* buffer, std::size_t maxLen, const char* format, ...) -> std::int32_t
Writes a printf-style formatted string into a buffer.
template<std::size_t size, class ... TArg>
auto formatString(char(&dest)[size], const char* format, const TArg&... args) -> std::int32_t
Writes a printf-style formatted string into a fixed-size array, deducing its size.
void u32tos(std::uint32_t value, char* buffer)
Writes an unsigned 32-bit integer to a buffer as a decimal string.
void i32tos(std::int32_t value, char* buffer)
Writes a signed 32-bit integer to a buffer as a decimal string.
void u64tos(std::uint64_t value, char* buffer)
Writes an unsigned 64-bit integer to a buffer as a decimal string.
void i64tos(std::int64_t value, char* buffer)
Writes a signed 64-bit integer to a buffer as a decimal string.
void ftos(double value, char* buffer, std::int32_t bufferSize)
Writes a floating-point value to a buffer as a decimal string.
auto isDigit(char c) -> bool constexpr
Returns true if the character is a decimal digit.
auto stou32(const char* str, std::size_t length) -> std::uint32_t constexpr
Parses up to length leading decimal digits into an unsigned 32-bit integer.
auto stou64(const char* str, std::size_t length) -> std::uint64_t constexpr
Parses up to length leading decimal digits into an unsigned 64-bit integer.
template<class Iter, class Compare>
void sort(Iter begin, Iter end, Compare comp)
Sorts the range in place using the given comparator.
template<class Iter>
void sort(Iter begin, Iter end)
Sorts the range in place into ascending order.
auto halfToFloat(std::uint16_t value) -> float
Converts a 16-bit half-precision value to a single-precision float.
auto floatToHalf(float value) -> std::uint16_t
Converts a single-precision float to a 16-bit half-precision value.
auto parseVersion(Containers::StringView version) -> std::uint64_t constexpr
Packs a dotted version string into a single 64-bit number.
template<class Iterator>
static auto toBase64Url(const Iterator begin, const Iterator end) -> std::string
Encodes the byte range into a URL-safe Base64 string (without padding).
auto crc32(Containers::ArrayView<std::uint8_t> data) -> std::uint32_t
Returns the CRC-32 checksum of the given byte buffer.
auto crc32(IO::Stream& stream) -> std::uint32_t
Returns the CRC-32 checksum of the remaining contents of the given stream.
auto clock() -> Clock&
Returns the shared system clock instance.
auto Random() -> RandomGenerator& noexcept
Returns the shared random number generator instance.
auto operator|(MapFlags a, MapFlags b) -> MapFlags constexpr
auto operator&(MapFlags a, MapFlags b) -> MapFlags constexpr
auto operator|(ClearFlags a, ClearFlags b) -> ClearFlags constexpr
auto operator&(ClearFlags a, ClearFlags b) -> ClearFlags constexpr
auto BytesPerPixel(PixelFormat format) -> std::int32_t constexpr
Bytes one pixel of an uncompressed PixelFormat occupies, or 0 (unknown or compressed).
auto theServiceLocator() -> ServiceLocator&
Returns the singleton service locator instance.
auto _(const char* text) -> StringView
Translates text in singular form using the primary translation catalog.
auto _x(StringView context, const char* text) -> StringView
Translates text in singular form using the primary translation catalog and the specified context.
auto _n(const char* singular, const char* plural, std::int32_t n) -> StringView
Translates text in singular or plural form (selected by count n) using the primary translation catalog.
auto _nx(StringView context, const char* singular, const char* plural, std::int32_t n) -> StringView
Translates text in singular or plural form (selected by count n) using the primary translation catalog and the specified context.
template<class ... Args>
auto _f(const char* text, const Args&... args) -> String
Translates and formats text in singular form using the primary translation catalog.
template<class ... Args>
auto _fn(const char* textSingular, const char* textPlural, std::int32_t n, const Args&... args) -> String
Translates and formats text in singular or plural form (selected by count n) using the primary translation catalog.

Variables

const hash_t NullHash
Reserved hash value marking an empty or invalid entry.
const unsigned int StepsInitialSize
Initial capacity reserved for the step array of each affector.

Constants

double Pi constexpr
3.1415... (double)
float fPi constexpr
3.1415...
float fPiOver2 constexpr
3.1415... / 2
float fPiOver3 constexpr
3.1415... / 3
float fPiOver4 constexpr
3.1415... / 4
float fPiOver6 constexpr
3.1415... / 6
float fTwoPi constexpr
3.1415... * 2
double DegToRad constexpr
Multiply to convert degrees to radians (double).
float fDegToRad constexpr
Multiply to convert degrees to radians.
double RadToDeg constexpr
Multiply to convert radians to degrees (double).
float fRadToDeg constexpr
Multiply to convert radians to degrees.
float fRadAngle1 constexpr
1 degree as radians
float fRadAngle30 constexpr
30 degrees as radians
float fRadAngle45 constexpr
45 degrees as radians
float fRadAngle90 constexpr
90 degrees as radians
float fRadAngle180 constexpr
180 degrees as radians
float fRadAngle270 constexpr
270 degrees as radians
float fRadAngle360 constexpr
360 degrees as radians

Enum documentation

enum class nCine::PrimitiveType : std::uint32_t

Primitive topology of a draw call.

Backend-neutral replacement for the GL_TRIANGLES-style primitive enums. The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast. Other backends map these values through their own tables.

Enumerators
Points

A list of individual points

Lines

A list of independent line segments

LineLoop

A connected line strip closed back to the first vertex

LineStrip

A connected strip of line segments

Triangles

A list of independent triangles

TriangleStrip

A connected strip of triangles

TriangleFan

A fan of triangles sharing the first vertex

enum class nCine::BlendingFactor : std::uint32_t

Source or destination factor of the blending equation.

Backend-neutral replacement for the GL_SRC_ALPHA-style blending factor enums. The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
Zero

Multiplies by zero

One

Multiplies by one

SrcColor

Multiplies by the source color

OneMinusSrcColor

Multiplies by one minus the source color

SrcAlpha

Multiplies by the source alpha

OneMinusSrcAlpha

Multiplies by one minus the source alpha

DstAlpha

Multiplies by the destination alpha

OneMinusDstAlpha

Multiplies by one minus the destination alpha

DstColor

Multiplies by the destination color

OneMinusDstColor

Multiplies by one minus the destination color

SrcAlphaSaturate

Multiplies by the saturated source alpha (source factor only)

ConstantColor

Multiplies by the constant blend color

OneMinusConstantColor

Multiplies by one minus the constant blend color

ConstantAlpha

Multiplies by the constant blend alpha

OneMinusConstantAlpha

Multiplies by one minus the constant blend alpha

enum class nCine::BufferUsage : std::uint32_t

Expected update pattern of a vertex or index buffer.

Backend-neutral replacement for the GL_STATIC_DRAW-style buffer usage hints. The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
StreamDraw

Written once and drawn only a few times

StaticDraw

Written once and drawn many times

DynamicDraw

Rewritten repeatedly and drawn many times

enum class nCine::BufferTarget : std::uint32_t

Binding target of a buffer object.

Backend-neutral replacement for the GL_ARRAY_BUFFER-style buffer binding targets. The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
Vertex

Vertex attribute data

Index

Index (element array) data

Uniform

Uniform block data

enum class nCine::MapFlags : std::uint32_t

Buffer mapping and immutable storage flags.

Backend-neutral replacement for the GL_MAP_WRITE_BIT-style mapping flags, combinable as bit flags. The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
None

No mapping (a host-side buffer is used instead)

Write

The mapping is written to

InvalidateRange

The previous contents of the mapped range can be discarded

InvalidateBuffer

The previous contents of the whole buffer can be discarded

FlushExplicit

Modified ranges are flushed explicitly

Unsynchronized

The device does not synchronize pending operations on the buffer

Persistent

The mapping stays valid while the device reads from the buffer

Coherent

Writes become visible to the device without an explicit flush

enum class nCine::IndexFormat : std::uint32_t

Data format of the indices in an index buffer.

The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
UInt16

16-bit unsigned indices

UInt32

32-bit unsigned indices

enum class nCine::CullFaceMode : std::uint32_t

Face culling mode.

The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
Front

Front faces are culled

Back

Back faces are culled

FrontAndBack

All faces are culled

enum class nCine::VertexAttribType : std::uint32_t

Component data type of a vertex attribute.

Backend-neutral replacement for the GL_FLOAT-style component type constants used with vertex formats. The numeric values intentionally match the corresponding OpenGL constants, so the OpenGL backend can translate with a plain cast.

Enumerators
UnsignedByte

8-bit unsigned components

Float

32-bit floating-point components

enum class nCine::ShaderStage

Programmable pipeline stage a shader source is attached to.

Backend-neutral replacement for the GL_VERTEX_SHADER-style shader type constants, so that shared pipeline code (Shader / RenderResources) never names a GL constant. Each backend maps the stage to its own compiler input.

Enumerators
Vertex

The vertex stage

Fragment

The fragment (pixel) stage

enum class nCine::DepthStencilFormat

Depth and stencil format of a render target.

The values are backend-neutral, each backend maps them to its own depth/stencil storage formats.

Enumerators
None

No depth or stencil buffer

Depth16

16-bit depth buffer

Depth24

24-bit depth buffer

Depth24_Stencil8

24-bit depth buffer with an 8-bit stencil buffer

enum class nCine::ClearFlags : std::uint32_t

Buffers of a render target that can be cleared.

Combinable as bit flags. Unlike the other enums in this header the values are backend-neutral, each backend maps them to its own clear mask.

Enumerators
None

No buffer

Color

The color buffer

Depth

The depth buffer

Stencil

The stencil buffer

enum class nCine::PixelFormat

Pixel format of texture data.

Backend-neutral description of every texel layout supported for empty and decoded textures, shared by Texture (as Texture::Format), TextureFormat and the texture loaders. Each backend maps these logical formats to its own internal/external formats and data types. The external channel order (RGB vs. BGR) is carried separately by TextureFormat.

Enumerators
Unknown

Unknown or unsupported format

R8

One channel, 8 bits per pixel

RG8

Two channels, 16 bits per pixel

RGB8

Three channels, 24 bits per pixel

RGBA8

Four channels, 32 bits per pixel

RGB565

Packed RGB, 5/6/5 bits per channel

RGB5A1

Packed RGBA, 5/5/5/1 bits per channel

RGBA4

Packed RGBA, 4 bits per channel

RGB16F

Three half-float channels

RGBA16F

Four half-float channels

RGB32F

Three single-float channels

RGBA32F

Four single-float channels

Depth16

16-bit depth

Depth24

24-bit depth

Depth32F

32-bit floating-point depth

DXT1RGB

S3TC DXT1, RGB (no alpha)

DXT1RGBA

S3TC DXT1, RGBA (1-bit alpha)

DXT3

S3TC DXT3, RGBA (explicit alpha)

DXT5

S3TC DXT5, RGBA (interpolated alpha)

ETC1

ETC1, RGB

ETC2RGB8

ETC2, RGB

ETC2RGB8A1

ETC2, RGB with 1-bit punch-through alpha

ETC2RGBA8

ETC2 + EAC, RGBA

EAC_R11

EAC, one channel

EAC_RG11

EAC, two channels

ATC_RGB

ATC, RGB

ATC_RGBA_Explicit

ATC, RGBA with explicit alpha

ATC_RGBA_Interpolated

ATC, RGBA with interpolated alpha

PVRTC_2BPP_RGB

PVRTC v1, 2 bpp, RGB

PVRTC_2BPP_RGBA

PVRTC v1, 2 bpp, RGBA

PVRTC_4BPP_RGB

PVRTC v1, 4 bpp, RGB

PVRTC_4BPP_RGBA

PVRTC v1, 4 bpp, RGBA

ASTC_4x4

ASTC, 4x4 block

ASTC_5x4

ASTC, 5x4 block

ASTC_5x5

ASTC, 5x5 block

ASTC_6x5

ASTC, 6x5 block

ASTC_6x6

ASTC, 6x6 block

ASTC_8x5

ASTC, 8x5 block

ASTC_8x6

ASTC, 8x6 block

ASTC_8x8

ASTC, 8x8 block

ASTC_10x5

ASTC, 10x5 block

ASTC_10x6

ASTC, 10x6 block

ASTC_10x8

ASTC, 10x8 block

ASTC_10x10

ASTC, 10x10 block

ASTC_12x10

ASTC, 12x10 block

ASTC_12x12

ASTC, 12x12 block

enum class nCine::TextureTarget

Type of texture the backend allocates and binds.

The renderer only uses two-dimensional textures; the enum exists so pipeline code does not name a backend-specific texture target constant.

Enumerators
Texture2D

A two-dimensional texture

enum class nCine::SamplerFilter

Texture minification and magnification filtering modes.

enum class nCine::SamplerWrapping

Texture coordinate wrapping modes.

enum class nCine::SwizzleChannel

Source for a sampled texture channel (see Texture::SetSwizzle()).

enum class nCine::JoystickGuidType

Well-known joystick GUID layouts.

Identifies how the bytes of a JoystickGuid are laid out so they can be parsed accordingly.

enum class nCine::ButtonName : std::int16_t

Gamepad buttons.

Unified button names a mapped joystick can report, regardless of the physical controller layout.

enum class nCine::AxisName : std::int16_t

Gamepad axes.

Unified axis names a mapped joystick can report, regardless of the physical controller layout.

enum class nCine::TouchEventType

Type of a touch event.

Enumerators
Down

The first pointer touched the screen

Up

The last pointer was released

Move

A pointer moved

PointerDown

An additional pointer touched the screen

PointerUp

An additional pointer was released

enum class nCine::MouseButton : short int

Mouse buttons.

enum class nCine::Keys

Keyboard key symbols.

Platform-independent key codes. Not every value is produced by every backend; comments mark values specific to SDL, GLFW or Android.

enum nCine::KeyMod

Keyboard modifier flags.

Bit flags reported in KeyboardEvent::mod. The combined values (Ctrl, Shift, etc.) match either the left or the right modifier.

Typedef documentation

using nCine::CreateAppEventHandlerDelegate = std::unique_ptr<IAppEventHandler>(*)()

Delegate that creates an instance of IAppEventHandler.

Passed to MainApplication::Run() so the engine can instantiate the user's event handler.

using nCine::hash_t = std::uint32_t

32-bit hash value

using nCine::hash64_t = std::uint64_t

64-bit hash value

template<class K, class V, class Hash = xxHash64Func<K>, class Eq = phmap::priv::hash_default_eq<K>>
using nCine::HashMap = phmap::flat_hash_map<K, V, Hash, Eq>

Generic hash map.

Alias for phmap::flat_hash_map from the Parallel Hashmap library, defaulting to the xxHash3 hash function sized to the target architecture.

using nCine::FenceHandle = void*

Opaque handle to a GPU fence created by the device.

typedef char* nCine::NativeArgument

Native argument type, wchar_t* on Windows, otherwise char*.

Function documentation

Application& nCine::theApplication()

Returns the application instance.

Returns the singleton application instance.

float nCine::sinApprox(float x)

Returns $ \sin(x) $ as cheaply as the platform can, within 1e-5 of full scale for |x| <= 64.

Parameters
x Angle in radians, $ |x| \lesssim 4096 $ - past that a float no longer resolves the fraction of a turn that is left (an angle of 1e6 has a resolution of 0.06 rad), so larger values are handed to libm. Nothing here should pass one, but a phase accumulator that is never wrapped eventually would; it is one compare on a path that is already the slow one.

For values that drive something's appearance or motion - a flicker phase, a pulse, an orbit, a sprite's rotation, a shot's launch direction - where the library function's last bits buy nothing. On a platform whose libm is fast this simply calls it, because an approximation is not automatically cheaper: measured on x86-64 against wrapped phases, a polynomial of this shape was SLOWER than glibc's sinf() (4.9 ns against 3.5 ns, same with clang). It is only worth substituting where libm is genuinely bad, which on the consoles it is - a sinf() on the PSP measures 13.5 us, about 4,500 cycles, against a few dozen cycles here (see NCINE_APPROX_TRIG for the list).

What each console gets:

  • Dreamcast: the SH4's fsca instruction, sine and cosine together at about 2^-21.
  • Everything else on the list: a half-turn fold and an odd degree-9 minimax polynomial, 6.3e-6 over the fold, 9e-6 within ±64 rad. The N64's libdragon ships fm_sinf() at a similar accuracy and cost; this polynomial is used there too so that every console runs (and is measured on) the same code. The PSP's VFPU has vsin/vcos/vrot, but a VFPU context exists only on threads created with PSP_THREAD_ATTR_VFPU, which the engine's pthread workers and the audio thread are not, and the few dozen cycles it would save per call are not worth a function that is unsafe off the main thread. The polynomial is already ~250x faster than that libm.

Precision: at the 6e-6 here, a rotation matrix built from the result is off by less than a 0.001 % scale, which no sprite in the game can resolve, and a shot's launch angle by 0.0004 degrees. The only callers that should stay on libm are one-time table generation (already amortized), anything that uses sin() of a huge argument as a hash (it needs the chaotic low bits), and the sin/cos registered for level scripts, whose contract is the C library's.

float nCine::cosApprox(float x)

Returns $ \cos(x) $ as cheaply as the platform can, see sinApprox().

void nCine::sincosApprox(float x, float& s, float& c)

Returns both $ \sin(x) $ and $ \cos(x) $ as cheaply as the platform can, see sinApprox().

Prefer this wherever both are needed of the same angle: the fold is done once and the two polynomials share $ x^2 $ , and on the Dreamcast fsca produces both in the same instruction anyway. On a desktop libm this is the sincosf() pair the compiler already merges.

Keep in mind the SH4 codegen note in Matrix4x4::RotationZ(): where a caller needs -s as well, take it from sinApprox(-x) on the Dreamcast rather than negating s.

float nCine::atan2Approx(float y, float x)

Returns $ \operatorname{atan2}(y, x) $ as cheaply as the platform can, within 1.2e-5 rad.

For a sprite's facing angle or a debris rotation. Newlib's atan2f() on the consoles is two software routines of about 300 instructions with divisions; this is one division, an octant reduction and an odd degree-9 minimax polynomial on [0, 1] - about 20 instructions, mapping onto multiply-adds. On a platform with a fast libm (see NCINE_APPROX_TRIG) it calls std::atan2() instead.

Same conventions as the library function: the result is in $ [-\pi, \pi] $ , the sign of y picks the half-plane, and (0, 0) yields 0. Infinities and NaN are not handled.

Not used on the Dreamcast, where this is std::atan2(). The approximation is miscompiled there for negative y: measured on hardware over a swept direction, every sample with y >= 0 was exact and the ones with y < 0 were wrong, with the magnitude matching std::fabs(y) having been dropped, so the min/max selection inverted and the ratio came out as mx / mn - atan2Approx(-1.0f, -0.0006f) returned -1.9e27 instead of -1.5714. Restructuring it moved the failure rather than removing it (an earlier shape lost the final sign instead), and the symptom shifted whenever unrelated code in the same function changed, so the fault is in what the compiler emits rather than in the arithmetic, which is correct on every other target and on the host. The library call costs more than the polynomial but this is a few calls a frame, not a hot loop.

float nCine::floorFast(float x)

Returns $ \lfloor x \rfloor $ without a libm call, for $ |x| < 2^{22} $ .

std::floor(), std::ceil() and std::round() on a float are real calls into newlib on every console in NCINE_APPROX_TRIG - MIPS and SH-4 have no floor instruction and PowerPC's rounds only to an integer register through memory - 36 to 68 instructions each, and the collision code and the HUD call them per actor or per element every frame. These are exact for any value a pixel or tile coordinate can take; the range limit comes from the float-to-int cast (MIPS, SH-4, ARM) or the 1.5 * 2^23 rounding trick (PowerPC, 68k, see Implementation::FoldHalfTurn()) they are built on. Elsewhere they are the library functions, which the compiler turns into one instruction on any SSE4.1 or ARMv8 machine.

float nCine::ceilFast(float x)

Returns $ \lceil x \rceil $ without a libm call, for $ |x| < 2^{22} $ , see floorFast().

float nCine::roundFast(float x)

Returns $ x $ rounded to the nearest integer without a libm call, for $ |x| < 2^{22} $ , see floorFast().

Halfway cases go away from zero like std::round(), except within one ulp of the halfway point, where adding the half can itself round; a position snapped to a pixel cannot tell the difference.

float nCine::sqrtApprox(float x)

Returns $ \sqrt{x} $ as cheaply as the platform can, and 0 for a non-positive argument.

On the Dreamcast this is the SH4's fsrra (reciprocal square root, accurate to the last bits, 1 cycle) and a multiply, against about 23 cycles for fsqrt; fsrra of zero is infinity and 0 * inf is NaN, hence the guard, which also turns a negative argument into 0 where std::sqrt() would return NaN. Every other target has a hardware square root that libm or the compiler already uses, so this is std::sqrt() there, with the same guard for the same answer on every platform.

float nCine::lerp(float a, float b, float ratio)

Linearly interpolates between two values by the given ratio.

std::int32_t nCine::lerp(std::int32_t a, std::int32_t b, float ratio)

Linearly interpolates between two integers by the given ratio, rounding the result.

float nCine::lerpByTime(float a, float b, float ratio, float timeMult)

Frame-rate independent interpolation between two values.

Applies ratio per nominal frame and scales it by timeMult so the result is independent of the actual frame duration.

std::int32_t nCine::copyStringFirst(char* dest, std::int32_t destSize, const char* source, std::int32_t count = -1)

Copies the beginning of a string into a fixed-size buffer, always null-terminating it.

Parameters
dest Destination buffer
destSize Size of the destination buffer in bytes
source Source string
count Maximum number of characters to copy, or -1 to copy the whole source
Returns Number of characters written, excluding the null terminator

template<std::size_t size>
std::int32_t nCine::copyStringFirst(char(&dest)[size], const char* source, std::int32_t count = -1)

Copies the beginning of a string into a fixed-size array, deducing its size.

template<std::size_t size>
std::int32_t nCine::copyStringFirst(char(&dest)[size], Containers::StringView source)

Copies the beginning of a string view into a fixed-size array, deducing its size.

std::int32_t nCine::formatString(char* buffer, std::size_t maxLen, const char* format, ...)

Writes a printf-style formatted string into a buffer.

Returns Number of characters written, excluding the null terminator

template<std::size_t size, class ... TArg>
std::int32_t nCine::formatString(char(&dest)[size], const char* format, const TArg&... args)

Writes a printf-style formatted string into a fixed-size array, deducing its size.

void nCine::u32tos(std::uint32_t value, char* buffer)

Writes an unsigned 32-bit integer to a buffer as a decimal string.

void nCine::i32tos(std::int32_t value, char* buffer)

Writes a signed 32-bit integer to a buffer as a decimal string.

void nCine::u64tos(std::uint64_t value, char* buffer)

Writes an unsigned 64-bit integer to a buffer as a decimal string.

void nCine::i64tos(std::int64_t value, char* buffer)

Writes a signed 64-bit integer to a buffer as a decimal string.

void nCine::ftos(double value, char* buffer, std::int32_t bufferSize)

Writes a floating-point value to a buffer as a decimal string.

bool nCine::isDigit(char c) constexpr

Returns true if the character is a decimal digit.

std::uint32_t nCine::stou32(const char* str, std::size_t length) constexpr

Parses up to length leading decimal digits into an unsigned 32-bit integer.

std::uint64_t nCine::stou64(const char* str, std::size_t length) constexpr

Parses up to length leading decimal digits into an unsigned 64-bit integer.

template<class Iter, class Compare>
void nCine::sort(Iter begin, Iter end, Compare comp)

Sorts the range in place using the given comparator.

template<class Iter>
void nCine::sort(Iter begin, Iter end)

Sorts the range in place into ascending order.

float nCine::halfToFloat(std::uint16_t value)

Converts a 16-bit half-precision value to a single-precision float.

std::uint16_t nCine::floatToHalf(float value)

Converts a single-precision float to a 16-bit half-precision value.

std::uint64_t nCine::parseVersion(Containers::StringView version) constexpr

Packs a dotted version string into a single 64-bit number.

Parses a "major.minor.patch" string into a 64-bit value with the major part in bits 48-63, the minor part in bits 32-47 and the patch part in the low 32 bits. A patch part beginning with 'r' (a Git revision) is encoded with a special maximum value so it always compares as the latest.

template<class Iterator>
static std::string nCine::toBase64Url(const Iterator begin, const Iterator end)

Encodes the byte range into a URL-safe Base64 string (without padding).

std::uint32_t nCine::crc32(Containers::ArrayView<std::uint8_t> data)

Returns the CRC-32 checksum of the given byte buffer.

std::uint32_t nCine::crc32(IO::Stream& stream)

Returns the CRC-32 checksum of the remaining contents of the given stream.

Clock& nCine::clock()

Returns the shared system clock instance.

RandomGenerator& nCine::Random() noexcept

Returns the shared random number generator instance.

std::int32_t nCine::BytesPerPixel(PixelFormat format) constexpr

Bytes one pixel of an uncompressed PixelFormat occupies, or 0 (unknown or compressed).

The one authoritative table next to the enum itself, so a backend that needs the answer does not grow its own switch (which then silently answers 0 for every entry added after it was copied). Compressed formats have no per-pixel size - callers reason about their blocks instead.

ServiceLocator& nCine::theServiceLocator()

Returns the singleton service locator instance.

Variable documentation

const hash_t nCine::NullHash

Reserved hash value marking an empty or invalid entry.

const unsigned int nCine::StepsInitialSize

Initial capacity reserved for the step array of each affector.

double nCine::Pi constexpr

3.1415... (double)

float nCine::fPi constexpr

3.1415...

float nCine::fPiOver2 constexpr

3.1415... / 2

float nCine::fPiOver3 constexpr

3.1415... / 3

float nCine::fPiOver4 constexpr

3.1415... / 4

float nCine::fPiOver6 constexpr

3.1415... / 6

float nCine::fTwoPi constexpr

3.1415... * 2

double nCine::DegToRad constexpr

Multiply to convert degrees to radians (double).

float nCine::fDegToRad constexpr

Multiply to convert degrees to radians.

double nCine::RadToDeg constexpr

Multiply to convert radians to degrees (double).

float nCine::fRadToDeg constexpr

Multiply to convert radians to degrees.

float nCine::fRadAngle1 constexpr

1 degree as radians

float nCine::fRadAngle30 constexpr

30 degrees as radians

float nCine::fRadAngle45 constexpr

45 degrees as radians

float nCine::fRadAngle90 constexpr

90 degrees as radians

float nCine::fRadAngle180 constexpr

180 degrees as radians

float nCine::fRadAngle270 constexpr

270 degrees as radians

float nCine::fRadAngle360 constexpr

360 degrees as radians