Apus.Engine.API.pas

// Definition of engine's abstract classes structure
//
// Copyright (C) 2003 Ivan Polyacov, Apus Software (ivan@apus-software.com)
// This file is licensed under the terms of BSD-3 license (see license.txt)
// This file is a part of the Apus Game Engine (https://github.com/Cooler2/ApusGameEngine)

unit Apus.Engine.API;
interface
 uses Apus.Core, Apus.Lib, Apus.Engine.Types, Apus.Engine.Window, Apus.Engine.Keys,
   Apus.Images, Apus.Geom2D, Apus.Geom3D, Apus.Colors, Apus.EventMan, Apus.VertexLayout,
   Apus.Engine.GpuLayout,
   Apus.Engine.Mesh, Apus.Engine.Resources, Apus.Engine.Scene, Apus.Engine.UIScene;

const
 // Image allocation flags (ai - AllocImage)
 aiAutoMipmap     =  1; // Automatically generate mip-map levels (number of levels is implementation-dependent)
 aiTexture        =  2; // Allocate full texture object of the underlying API (no texture sharing, no dynamic atlas)
 aiRenderTarget   =  4; // Image can be used as Render Target for GPU (no CPU access)
 aiSysMem         =  8; // Image will have its buffer in system RAM, so can be accessed by CPU
 aiPow2           = 16; // Enlarge dimensions to be PoT
// aiWriteOnly      = 32; // Can be locked, but for write only operation
 aiDontScale      = 64;  // Use exact width/height for render target allocation (otherwise they're scaled using current scale factor)
 aiClampUV        = $80; // clamp texture coordinates instead of wrapping them (for aiTexture only)
 aiDepthBuffer    = $0100; // allocate a Depth Buffer for this image (requires aiRenderTarget flag)
                           // use ipfNone or ipfDepth to allocate only depth buffer without image
 aiTexture3D      = $0200; // allocate a 3D texture instead of 2D texture array
 aiThreadLocal    = $0400; // texture is owned by a single thread/window, never shared across threads
 aiPixelated      = $2000; // disable tri/bilinear filtering for this image

 // Buffer allocation policy flags
 abThreadLocal = Apus.Engine.Resources.abThreadLocal;
 abImmutable    = Apus.Engine.Resources.abImmutable;
 abShared      = Apus.Engine.Resources.abShared;

 // DynamicAtlas dimension flags
 aiMW256   = $010000;
 aiMW512   = $020000;
 aiMW1024  = $030000;
 aiMW2048  = $040000;
 aiMW4096  = $050000;
 aiMH256   = $100000;
 aiMH512   = $200000;
 aiMH1024  = $300000;
 aiMH2048  = $400000;
 aiMH4096  = $500000;

 // Color values
 clNeutral = $FF808080;
 clDefault = $010F0F0F; // special value assumed to be replaced by some generic/default color
 clWhite   = $FFFFFFFF;
 clBlack   = $FF000000;
 clTransparent = 0;
 clTranspWhite = $FFFFFF;
 clRed     = $FFFF0000;
 clGreen   = $FF00FF00;
 clBlue    = $FF0000FF;

 // LoadImageFromFile flags
 liffSysMem  = aiSysMem; // Image will be allocated in system memory only and can't be used for accelerated rendering!
 liffTexture = aiTexture; // Image will be allocated as a whole texture (wrap UV enabled, otherwise - disabled!)
 liffPow2    = aiPow2; // Image dimensions will be increased to the nearest pow2
 liffMipMaps = aiAutoMipmap; // Image will be loaded with mip-maps (auto-generated if no mips in the file)
 liffAllowChange = $100;    // Ensure that image won't be read-only
 liffNoFail  = $40000000;   // Don't raise exception if file not loaded, return nil instead
 liffDefault = $FFFFFFFF;   // Use defaultLoadImageFlags for default flag values

 // width and height of atlas-texture
 liffMW256   = aiMW256;
 liffMW512   = aiMW512;
 liffMW1024  = aiMW1024;
 liffMW2048  = aiMW2048;
 liffMW4096  = aiMW4096;

 liffMH256   = aiMH256;
 liffMH512   = aiMH512;
 liffMH1024  = aiMH1024;
 liffMH2048  = aiMH2048;
 liffMH4096  = aiMH4096;

 // Some texture flags (not all)
 tfRenderTarget = Apus.Engine.Resources.tfRenderTarget;
 tfScaled       = Apus.Engine.Resources.tfScaled;
 tfTexture      = Apus.Engine.Resources.tfTexture;
 tfDirty        = Apus.Engine.Resources.tfDirty;

 // Special flags for the "index" field of particles
 partPosU  = $00000001; // horizontal position in the atlas (in cells)
 partPosV  = $00000100; // vertical position in the atlas (in cells)
 partSizeU = $00010000; // particle width (in cells)
 partSizeV = $00100000; // particle height (in cells)
 partFlip  = $01000000; // mirror
 partEndpoint = $02000000; // indicate that particle is a free end of a polyline (draw.Band)
 partLoop = $04000000; // indicate end of a polyline loop (draw.Band)

 // txt.Write() options flags (overrides font handle flags)
 toDontTranslate  =  1; // Don't use UDict to translate
 toDrawToBitmap   =  2; // Draw to bitmap buffer instead of current render target
 toDontCache      =  4; // Text attributes are dynamic, so no need to cache glyphs for any long period (temp cache is used)
 toWithShadow     =  8; // Draw twice with 1,1 offset shadow
 toComplexText    =  16; // String is complex - parse it
 toMeasure        =  32; // Fill measurement data, if query<>0 - check point and set current link
 toDontDraw       =  64; // Just measure - don't draw anything
 toBold           =      $100;  // Overrides font style flag
 toAddBaseline    =    $10000;  // y-coordinate passed is not for baseline, but for top line, so need to be corrected
 toNoHinting      =    $20000; // Disable hinting for vector fonts (good for large text)
 toAutoHinting    =    $40000; // Force use of FT-autohinting (may produce better or more uniform results)
 toItalic         =  $2000000; // Overrides font style flag
 toUnderline      =  $4000000; // Overrides font style flag
 toLetterSpacing  = $10000000; // Additional spacing between letters
 toTabularDigits  = $20000000; // Digits 0..9 take equal cells (overrides font style flag, see fsTabularDigits)

 // GetFont() style flags
 fsDontTranslate = 1; // Don't use UDict to translate strings
 fsNoHinting     = 2; // Disable hinting for vector fonts (good for large text)
 fsAutoHinting   = 4; // Force use of FT-autohinting (may produce better or more uniform results)
 fsIgnoreScale   = 8; // Ignore global font scale (use real pixels instead of virtual pixels)
 fsStrictMatch = 128; // strict match for font name
 fsBold        =         $100;
 fsItalic      =     $2000000;
 fsUnderline   =     $4000000;
 fsLetterSpacing  = $10000000;
 // Digits 0..9 take equal cells: the widest digit's advance, a glyph centered in its cell.
 // Changing numbers keep their digits in place. Width, Advance, PenPositions and the
 // output all follow it; a digit at an edge of a text counts by its cell, not its ink
 fsTabularDigits  = $20000000;

 // Font options (for SetFontOption)
 foDownscaleFactor = 1;
 foUpscaleFactor   = 2;
 foGlobalScale     = 3;

 // FireMessage severity (mirrors TToastKind in Apus.Engine.Notifications)
 msgInfo    = 0;
 msgSuccess = 1;
 msgWarning = 2;
 msgError   = 3;

 // Keyboard shift state codes
 sscShift = 1;
 sscCtrl  = 2;
 sscAlt   = 4;
 sscWin   = 8;
 sscBaseMask=$0F; // aggregate modifier bits
 // Detailed right-side bits. Left state is derived: (aggregate bit set) and (right bit clear)
 sscRShift=$10;
 sscRCtrl =$20;
 sscRAlt  =$40;
 sscRWin  =$80;
 sscRightMask=$F0;

 // Mouse buttons
 mbLeft   = Apus.Engine.Types.mbLeft;
 mbRight  = Apus.Engine.Types.mbRight;
 mbMiddle = Apus.Engine.Types.mbMiddle;

type
 CursorID=record // Namespace for cursor identifiers
  const
   Default        =  0;  // Default arrow
   Link           =  1;  // Link-over (hand/finger)
   Wait           =  2;  // busy cursor (hourglass)
   Input          =  3;  // Text input cursor (beam)
   Help           =  4;  // Arrow with question mark
   ResizeH        = 10;  // resize height: N-S arrows
   ResizeW        = 11;  // resize width: E-W arrows
   ResizeHW       = 12;  // N-S-E-W arrows (also the "move" cursor)
   Cross          = 13;  //
   ResizeNWSE     = 14;  // diagonal resize: NW-SE arrows (top-left / bottom-right corner)
   ResizeNESW     = 15;  // diagonal resize: NE-SW arrows (top-right / bottom-left corner)
   None           = 99;  // No cursor (hidden)
 end;

 // Other types
 TRect2 = Apus.Engine.Types.TRect2;
 TVertexComponent = Apus.Engine.Types.TVertexComponent;
 TVertexLayout = Apus.Engine.Types.TVertexLayout;
 TPrimitiveType = Apus.Engine.Types.TPrimitiveType;

 // Packed ARGB color
 TARGBColor = Apus.Engine.Types.TARGBColor;
 PARGBColor = Apus.Engine.Types.PARGBColor;

 // Fills of shapes (solid or gradient) and corner radii
 TFill = Apus.Engine.Types.TFill;
 TFillStop = Apus.Engine.Types.TFillStop;
 TCornerRadii = Apus.Engine.Types.TCornerRadii;

 // SDL cursors are pointers; Unix THandle is only a 32-bit file descriptor.
 TCursorHandle = NativeUInt;

 TKey = Apus.Engine.Keys.TKey;
 TKeyMod = Apus.Engine.Keys.TKeyMod;
 Scan = Apus.Engine.Keys.Scan;

 TDisplayMode = Apus.Engine.Types.TDisplayMode;
 TWindowFrame = Apus.Engine.Types.TWindowFrame;
 TWindowArea = Apus.Engine.Types.TWindowArea;
 TSurfaceConfig = Apus.Engine.Types.TSurfaceConfig;
 TSurfaceInput = Apus.Engine.Types.TSurfaceInput;
 TSurfaceState = Apus.Engine.Types.TSurfaceState;
 TSurfaceFit = Apus.Engine.Types.TSurfaceFit;
 TSurfaceChange = Apus.Engine.Types.TSurfaceChange;
 TSurfaceChanges = Apus.Engine.Types.TSurfaceChanges;
 TSurfaceMechanism = Apus.Engine.Types.TSurfaceMechanism;
 TGameSettings = Apus.Engine.Types.TGameSettings;
 TWindow = Apus.Engine.Window.TWindow;
 TWindowState = Apus.Engine.Window.TWindowState;

const
 // Vertex layout with 3 attributes: position[3] (location=0), color[3] (location=1) and uv[2] (location=2)
 DEFAULT_VERTEX_LAYOUT : TVertexLayout = (layout:$4300; stride:6*4;);

 // Mouse-move kinds (see TMoveKind) re-exported so gameplay scenes can test window.moveKind
 mkLeave = Apus.Engine.Types.mkLeave;
 mkMove  = Apus.Engine.Types.mkMove;
 mkEnter = Apus.Engine.Types.mkEnter;

type
 TImagePixelFormat = Apus.Images.TImagePixelFormat;
 // Pointer of the current thread's window: Mouse.Pos, Mouse.InRect(r), Mouse.Down...
 Mouse = Apus.Engine.Window.Mouse;

 // Which API use for rendering
 TGraphicsAPI=(gaAuto,     // Check one considering defined symbols
               gaOpenGL2); // OpenGL 2.0 or higher with shaders

 TSystemPlatform=(spDefault, // OS default
                  spWindows, // Native Windows
                  spSDL);    // SDL-2 library (cross-platform)

 // Blending mode (operation applied to the background)
 TBlendingMode=(blNone,   // background not modified
                blAlpha,  // regular alpha blending
                blAdd,    // additive mode ("Screen"
                blSub,    // subtractive mode
                blModulate,   // "Multiply" mode
                blModulate2X,  // "Multiply" mode with 2x factor
                blMove     // Direct move
                );
 // Texture blending mode (operation applied to a single texturing stage, separately for alpha or color)
 TTexBlendingMode=(tblNone,  // undefined (don't change current value)
                   tblDisable, // disable texture stage
                   tblKeep,  // keep previous pixel value (previous=diffuse for stage 0)
                   tblReplace, // use texture value
                   tblModulate, // previous*texture
                   tblModulate2X, // previous*texture*2
                   tblAdd,     // previous+texture
                   tblSub,     // previous-texture
                   tblInterpolate // previous*factor+texture*(1-factor): texture stages are blended with each other
                   );
{ TTexInterpolateMode=(tintFactor, // factor=constant
                      tintDiffuse, // factor=diffuse alpha
                      tintTexture, // factor=texture alpha
                      tintCurrent); // factor=previous stage alpha}

 // Texture interpolation (filtering) mode
 TTexFilter = Apus.Engine.Resources.TTexFilter;

 // Access mode for locked resources
 TLockMode = Apus.Engine.Resources.TLockMode;

 // Base texture class
 TTexture = Apus.Engine.Resources.TTexture;

 // Buffer classes
 TVertexBuffer = Apus.Engine.Resources.TVertexBuffer;
 TIndexBuffer = Apus.Engine.Resources.TIndexBuffer;
 // Buffer usage options
 TBufferUsage = Apus.Engine.Resources.TBufferusage;

 // Text alignment
 TTextAlignment = Apus.Engine.Types.TTextAlignment;

 // Mouse-move kind delivered to gameplay scenes (read via window.moveKind)
 TMoveKind = Apus.Engine.Types.TMoveKind;

 // Nine Patch: resizable image
 TNinePatch=class(TNamedObject)
  minWidth,minHeight:integer; // minimal possible dimension (in pixels, when scale=1.0)
  baseWidth,baseHeight:integer; // dimension without any stretching (in pixels, when scale=1.0)
  scaleFactor:single; // scale modifier: for example, use 0.5 for images with double resolution
  procedure Draw(x,y,width,height:single;scale:single=1.0); virtual; abstract;
 protected
  class function ClassHash:pointer; override; // override this to provide a separate hash for object instances
 end;

 // Interface to the native OS functions or underlying library.
 // Provides system-level services and a window factory.
 // Window-specific operations are methods on TWindow.
 ISystemPlatform=interface
  // System information
  function GetPlatformName:string; // TSystemPlatform value of this backend: 'spWindows', 'spSDL'
  function CanChangeSettings:boolean;
  procedure GetScreenSize(out width,height:integer); // screen size in virtual pixels
  procedure GetRealScreenSize(out width,height:integer); // screen size in real pixels
  function GetScreenDPI:integer;

  // System functions
  function GetSystemCursor(cursorId:integer):TCursorHandle;
  function LoadCursor(filename:string):TCursorHandle;
  procedure SetCursor(cur:TCursorHandle);
  procedure FreeCursor(cur:TCursorHandle);
  function GetMousePos:TPoint; // mouse position on screen
  procedure SetMousePos(scrX,scrY:integer); // move mouse cursor (screen coordinates)
  function GetShiftKeysState:cardinal;

  // Window factory: name - ASCII identifier (TWindow.name), title - caption shown to the user
  function CreateWindow(const name:String8;title:string):TWindow;
 end;

{$SCOPEDENUMS ON}
 // Depth test comparison mode
 TDepthTest=(
   Disabled,  // disable depth test
   Pass,      // always pass depth test
   Less,      // pass lesser values
   LessEqual, // pass lesser or equal values
   Greater,   // pass greater values
   Never,     // never pass depth test
   Keep);     // leave the current test unchanged
 // Depth write mask control
 TDepthWrite=(
   Keep, // leave the current write mask unchanged
   Off,  // disable depth writes
   On);  // enable depth writes
{$SCOPEDENUMS OFF}
 // Snapshot of the depth state (returned by IRenderTarget.DepthMode)
 TDepthMode=record
   test:TDepthTest;
   write:TDepthWrite;
 end;

{$SCOPEDENUMS ON}
 // Which faces to draw, by the winding seen on the canvas - the same for the backbuffer
 // and for a texture target (the backend compensates the Y flip between them).
 // Generators emit CCW-outward faces, so DrawCCW = show outer surface (cull backfaces).
 TCullMode=(DrawAll,  // display both sides
   DrawCCW,  // draw CCW faces only (cull CW). Default for 3D solids
   DrawCW);  // draw CW faces only (cull CCW). 2D drawing uses CW winding
{$SCOPEDENUMS OFF}

 // Shader mode for shadow mapping
 TShadowMapMode=(shadowDisabled,  // No shadow mapping (default, no shadows)
                 shadowDepthPass, // Render shadowmap (depth-only, no color output)
                 shadowMainPass); // Render using shadowmap (enable shadows)

 TShader = Apus.Engine.Resources.TShader;

 // Control render target
 IRenderTarget=interface
  // Clear whole render target (not only the viewport): fill colorbuffer and optionally depth buffer and stencil buffer
  procedure Clear(color:cardinal;zbuf:single=0;stencil:integer=-1);
  // Clear depth buffer and (optionally) stencil buffer. Don't clear the color buffer
  procedure ClearDepth(zbuf:single=0;stencil:integer=-1);
  // Setup viewport (output position) for the current render target
  // After viewport change don't forget to update projection and clipping
  procedure Viewport(oX,oY,VPwidth,VPheight:integer;renderWidth:integer=0;renderHeight:integer=0);
  // Setup depth test and/or write mask. TDepthTest.Keep / TDepthWrite.Keep leave that axis unchanged.
  procedure SetDepthMode(test:TDepthTest=TDepthTest.Keep;write:TDepthWrite=TDepthWrite.Keep);
  // Current depth state (test mode + write mask)
  function DepthMode:TDepthMode;
  // Depth bias of filled polygons, for a layer drawn over a coplanar one (road marks, decals):
  // offset = factor*depthSlope + units*minDepthStep (glPolygonOffset). Negative values move
  // towards the camera for the Less/LessEqual tests. (0,0) - no bias
  procedure SetDepthBias(factor,units:single);
  // Set blending mode
  procedure BlendMode(blend:TBlendingMode);
  // Set write mask (push previous mask)
  procedure Mask(rgb:boolean;alpha:boolean);
  // Restore (pop) previous mask
  procedure UnMask;

  function width:integer;  //< width of the render area in virtual pixels
  function height:integer; //< height of the render area in virtual pixels
  function aspect:single; // width/height
  // Real pixels per virtual pixel: >1 when the projection scales the virtual area up
  // (a canvas smaller than the render surface), 1 otherwise
  function pixelRatio:single;

  procedure Backbuffer; //< Render to the backbuffer
  procedure Texture(tex:TTexture); //< render to the texture (nil - render to the Backbuffer)
  procedure Push;  //< Save (push) current target in stack (including viewport)
  procedure Pop; //< Restore target from stack

  procedure Resized(newWidth,newHeight:integer); // Must be called by external code when backbuffer size was changed
 end;

 // Control clipping
 IClipping=interface
  procedure Rect(r:TRect;combine:boolean=true);  //< Set clipping rect (combine with previous or override), save previous
  procedure Nothing; //< don't clip anything, save previous (the same as Rect() for the whole render target area)
  procedure Restore; //< restore previous clipping rect
  procedure Reject(rejectPrimitives:boolean); // enable/disable primitive-level rejection base on clip area
  function  Get:TRect; //< return current clipping rect
  // Call this before draw something within R.
  // It sets actual clipping if needed.
  // Returns false if R doesn't intersect the current clipping rect (so no need to draw anything inside R)
  function Prepare(r:TRect):boolean; overload;
  function Prepare(x1,y1,x2,y2:NativeInt):boolean; overload;
  function Prepare(x1,y1,x2,y2:single):boolean; overload;  //< return false if r doesn't intersect the current clipping rect (so no need to draw anything inside r)
 end;

 // Control transformation and projection
 ITransformation=interface
  // Switch to default 2D view (use screen coordinates)
  procedure DefaultView;

  // Set 3D view with given field of view (in radians) - set perspective projection matrix
  // with the render target aspect ratio. fovRad spans the LARGER dimension: horizontal on a
  // wide target, vertical on a tall one (the smaller dimension gets a narrower angle).
  // Use big enough zMin and zMax since z-range is not linear and precision near zMax is much lower than near zMin.
  // So use values where main visible geometry is at least in the near 10% Z-range
  procedure Perspective(fovRad:single;zMin,zMax:double); overload;
  // The same with the FOV spanning the given axis: e.g. TFovAxis.diagonal keeps the angle
  // corner to corner on a normal, ultrawide or tall target (see FovExtents)
  procedure Perspective(fovRad:single;axis:TFovAxis;zMin,zMax:double); overload;

  // Switch to 3D view - set perspective projection (in camera space: camera pos = 0,0,0, Z-forward, X-right, Y-down)
  // zMin, zMax - near and far Z plane
  // xMin,xMax - x coordinate range on the zScreen Z plane
  // yMin,yMax - y coordinate range on the zScreen Z plane
  // I.e. the points (x,y,zScreen) with xMin <= x <= xMax, yMin <= y <= yMax cover the whole output area and only it
  procedure Perspective(xMin,xMax,yMin,yMax,zScreen,zMin,zMax:double); overload;
  // Set orthographic projection matrix
  // For example: scale=3 means that 1 unit in the world space is mapped to 3 pixels (in backbuffer)
  procedure Orthographic(scale,zMin,zMax:double);
  // Set arbitrary projection matrix
  procedure SetProjection(proj:TMat4d);
  // Set view transformation matrix (camera position)
  // View matrix is (R - right, D - down, F - forward, O - origin):
  // Rx Ry Rz
  // Dx Dy Dz
  // Fx Fy Fz
  // Ox Oy Oz
  procedure SetView(view:TMat4d);
  // Alternate way to set camera position and orientation
  // (origin - camera center, target - point to look, upPoint - any point ABOVE camera view line, so plane OTU is vertical),
  // turnCW - camera turn angle (along view axis, CW direction)
  procedure SetCamera(origin,target,upPoint:TVec3d;turnCW:double=0); overload;
  procedure SetCamera(origin,target,upPoint:TVec3;turnCW:single=0); overload;
  // Set Object (model to world) transformation matrix (must be used AFTER setting the view/camera)
  procedure SetObj(mat:TMat4d); overload;
  procedure SetObj(mat:TMat4); overload;
  // Set object position/scale/rotate
  procedure SetObj(oX,oY,oZ:single;scale:single=1;yaw:single=0;roll:single=0;pitch:single=0); overload;
  // Reset object matrix to the current base (identity if no base is set)
  procedure ResetObj;
  // Set the base (world) coordinate system: all subsequent SetObj matrices are
  // applied relative to it, so a whole group can be drawn "here" without multiplying
  // the base into every object manually. Right after SetBase the object matrix equals
  // the base itself (relative part is reset). Pass identity or call ResetBase to leave it.
  procedure SetBase(mat:TMat4d);
  // Leave the base coordinate system (back to world space, base = identity)
  procedure ResetBase;
  // Get Model-View-Projection matrix (i.e. transformation from model space to screen space)
  function MVPMatrix:TMat4d;
  function ProjMatrix:TMat4d;
  function ViewMatrix:TMat4d;
  function ObjMatrix:TMat4d;
  // Transform point using combined MVP matrix
  function Transform(source:TVec3d):TVec3d; overload;
  function Transform(source:TVec3):TVec3; overload;
  function ProjectPoint(source:TVec3):TVec3;
  function ViewDir(scrX,scrY:integer):TVec3; overload; // view direction vector
  function ViewDir(viewPos:TVec2):TVec3; overload; // viewPos in range of -1..1
  function ViewVec:TVec3; // camera front vector
  function RightVec:TVec3; // camera right (screen X+) vector
  function DownVec:TVec3;  // camera down (screen Y+) vector
  function ProjWidth:single; // screen projection width in camera view (xMax-xMin)
  function ProjHeight:single; // screen projection height in camera view (yMax-yMin)
  function CameraPos:TVec3; // get current camera position
  function Depth(pnt:TVec3):single; // get point depth (i.e. distance along camera view vector)
  function MinDepth:single; // get minimal depth value (zMin)
  function MaxDepth:single; // get maximal depth value (zMax)
 end;

 // Shaders-related API
 IShader=interface
  // Compile custom shader program from source
  function Build(vSrc,fSrc:String8;extra:String8=''):TShader;
  // Load and build shader from file(s)
  function Load(filename:String8;extra:String8=''):TShader;

  // Set custom shader (pass nil if it's already set or there is no object - because the engine should know)
  procedure UseCustom(shader:TShader);
  // Use customized shader: where just the pixel (fragment) color calculation is modified
  procedure UseCustomized(colorCalc:String8;numTextures:integer=1);
  // Switch back to the internal shader
  procedure Reset;
  // Set uniform value for the current shader
  procedure SetUniform(name:String8;value:integer); overload;
  procedure SetUniform(name:String8;value:single); overload;
  procedure SetUniform(name:String8;const value:TVec2); overload;
  procedure SetUniform(name:String8;const value:TVec3); overload;
  procedure SetUniform(name:String8;const value:TQuat); overload;
  procedure SetUniform(name:String8;const value:TMat4d); overload;
  procedure SetUniform(name:String8;const value:TMat4); overload;

  // Built-in shader settings
  // ----
  // Set custom texturing mode
  procedure TexMode(stage:byte;colorMode:TTexBlendingMode=tblModulate2X;alphaMode:TTexBlendingMode=tblModulate;
     filter:TTexFilter=fltUndefined;intFactor:single=0.0);
  // Restore default texturing mode: one stage with Modulate2X mode for color and Modulate mode for alpha
  procedure DefaultTexMode;
  // Upload texture to the Video RAM and make it active for the specified stage 0..15
  // (usually you don't need to call this manually unless you're using a custom shader)
  procedure UseTexture(tex:TTexture;stage:integer=0); overload;
  procedure UseTexture(tex:TTexture;uniformName:string8;stage:integer=0); overload; // use custom sampler name

  // Lighting and material
  // ----
  // Ambient color is added to any pixels (set 0 to disable), RGB value, alpha component ignored
  procedure AmbientLight(color:cardinal);
  // Set direction TO the light source (sun) (set power<=0 to disable)
  procedure DirectLight(direction:TVec3;power:single;color:cardinal=$FFFFFF);
  // Set point light source (set power<=0 to disable)
  procedure PointLight(position:TVec3d;power:single;color:cardinal=$FFFFFF);
  // Disable lighting
  procedure LightOff;
  // Bind a tangent-space normal map for subsequent GPU-mesh draw calls.
  // Active only when the mesh layout carries a Tangent attribute and lighting is on.
  // tex=nil is equivalent to NormalMapOff. strength=1.0 is full intensity.
  procedure NormalMap(tex:TTexture;strength:single=1.0);
  procedure NormalMapOff;
  // Define material properties
  procedure Material(color:cardinal;shininess:single);
  // Shadow mapping
  procedure Shadow(mode:TShadowMapMode;shadowMap:TTexture=nil;depthBias:single=0.002);

  // Apply shader configuration (build/set proper shader). Must be called after any mode changes before actual draw calls
  procedure Apply(vertexLayout:TVertexLayout);
  // R-19: select/build a stock shader for a GPU mesh layout (table-based attribute
  // locations). Coexists with Apply(TVertexLayout) used by the 2D painter path.
  procedure ApplyMeshLayout(layout:TGpuLayout);
 end;

 // Configuration
 IGraphicsSystemConfig=interface
  procedure ChoosePixelFormats(out trueColor,trueColorAlpha,rtTrueColor,rtTrueColorAlpha:TImagePixelFormat;
    economyMode:boolean=false);
  function SetVSyncDivider(n:integer):boolean; //< 0 - unlimited FPS, 1 - use monitor refresh rate
  // Query options
  function QueryMaxRTSize:integer; //< get max allowed dimension for RT textures
  function QueryMaxTextureSize:integer; //< get max allowed dimension for textures (GL_MAX_TEXTURE_SIZE)
  function ShouldUseTextureAsDefaultRT:boolean;
 end;

 // -------------------------------------------------------------------
 // ResourceManager - image manager (effectively, a texture memory manager)
 // -------------------------------------------------------------------
 IResourceManager=interface
  // Create an image (raises an exception on error)
  function AllocImage(width,height:integer;PixFmt:TImagePixelFormat;
     flags:cardinal;name:String8):TTexture; overload;
  function AllocImage(width,height,mipLevels:integer;PixFmt:TImagePixelFormat;
     flags:cardinal;name:String8):TTexture; overload;
  // Check if it is possible to allocate an image with given settings
  function QueryParams(width,height:integer;format:TImagePixelFormat;aiFlags:integer):boolean;
  // Free texture
  procedure FreeImage(var image:TTexture);

  // Change size of texture if it supports it (render target etc)
  procedure ResizeImage(var img:TTexture;newWidth,newHeight:integer);
  // Attach a depth buffer to a render-target texture. Specify nil to detach buffer.
  procedure AttachDepthBuffer(tex:TTexture;dBuf:TTexture);

  // Make image ready to use by GFX API (upload content to the VRAM, if required).
  // Binding for drawing is the job of IShader.UseTexture
  procedure MakeOnline(img:TTexture);

  // Vertex/Index buffers
  function AllocVertexBuffer(layout:TVertexLayout;numVertices:integer;
    usage:TBufferUsage=buStatic;flags:cardinal=0):TVertexBuffer;
  // Layout-less vertex buffer with explicit byte stride (R-19 TGpuMesh path).
  function AllocRawVertexBuffer(strideBytes,numVertices:integer;
    usage:TBufferUsage=buStatic;flags:cardinal=0):TVertexBuffer;
  function AllocIndexBuffer(indCount:integer;indSize:integer=2;
    usage:TBufferUsage=buStatic;flags:cardinal=0):TIndexBuffer;
  procedure FreeBuffer(buf:TEngineBuffer);
  // Set vb=nil to disable vertex buffer
  procedure UseVertexBuffer(vb:TVertexBuffer);
  // Set ib=nil to disable index buffer
  procedure UseIndexBuffer(ib:TIndexBuffer);

  // Build status lines
  function GetStatus(line:byte):string;
  // Create a dump of video memory usage and allocation
  procedure Dump(st:string='');
 end;

 // Particle atributes
 TParticle=record
  x,y,z:single;       // center position (z+ = forward direction)
  color:cardinal;
  scale,angle:single;
  index:integer;      // position in the texture atlas (use partXXX flags)
  custom:integer;     // custom data, not used
 end;
 PParticle=^TParticle;

 // Text character attributes
 TCharAttr=record
  font:cardinal;
  color:cardinal;
 end;
 PCharAttr=^TCharAttr;

 // Basic vertex format for regular primitives
 PVertex = Apus.VertexLayout.PVertex;
 TVertex = Apus.VertexLayout.TVertex;
 // Double texture coordinates
 PVertexDT = Apus.VertexLayout.PVertexDT;
 TVertexDT = Apus.VertexLayout.TVertexDT;
 // Vertex format with normal (for 3D lighting)
 PVertex3D = Apus.VertexLayout.PVertex3D;
 TVertex3D = Apus.VertexLayout.TVertex3D;

 // vertex and index arrays
 TVertices=array of TVertex;
 TVertices3D=array of TVertex3D;
 TIndices=Apus.Engine.Types.TIndices;
 TTexCoords=array of TVec2;

 TMesh=Apus.Engine.Mesh.TMesh;

 PMultiTexLayer=^TMultiTexLayer;
 TMultiTexLayer=record
  texture:TTexture;
  matrix:TMat32;  // texture coordinates transformation matrix
  next:PMultiTexLayer;
 end;

 // font handle structure: xxxxxxxx ssssssss yyyyyyyy 00ffffff (f - font object index, s - scale (percents), x - realtime effects, y - renderable effects and styles)
 TFontHandle=Apus.Engine.Types.TFontHandle;

 // Text output, fonts (text protocol 2011)
 ITextDrawer=interface
  // Load font data
  function LoadFont(fname:string;asName:string=''):string; overload; // Returns name of the loaded font
  function LoadRasterFont(const font:TBuffer;asName:string=''):string; overload; // Returns name of the loaded font
  function LoadVectorFont(const font:TBuffer;asName:string=''):string; overload; // Returns name of the loaded font
  // Global scale factor for GetFont
  procedure SetScale(scale:single);
  // Get font handle (size=0 - default font size).
  // size is multiplied by the SetScale factor (the UI scale) unless fsIgnoreScale is set; text is
  // drawn in render target pixels.
  // Vector (FreeType) fonts: em height in pixels = size*scale*16/9 (size is converted from points
  // to pixels twice, 4/3 each; kept for compatibility), e.g. size 9 at scale 1 -> em 16 px,
  // digit height about 0.72 em. size*scale above ~122 is clamped.
  // Raster fonts: scaled from the native size by size*scale/(header.width/10), up to 6.5x.
  function GetFont(name:string;size:single;flags:cardinal=0;effects:byte=0):TFontHandle;
  // Return handle for the same font enlarged scale times
  function ScaleFont(const font:TFontHandle;scale:single):TFontHandle;
  // Change option on a font handle
  procedure SetFontOption(handle:TFontHandle;option:cardinal;value:single);
  // Text output (use handle 0 for default font).
  // Alignment follows half-open bounds: left-aligned ink may start at x;
  // right-aligned ink must stay before x, so use rect.Right as an exclusive edge.
  procedure Write(font:TFontHandle;x,y:single;color:cardinal;st:String8;align:TTextAlignment=taLeft;
     options:cardinal=0;targetWidth:integer=0;query:cardinal=0);
  procedure WriteW(font:TFontHandle;x,y:single;color:cardinal;st:String32;align:TTextAlignment=taLeft;
     options:cardinal=0;targetWidth:integer=0;query:cardinal=0);
  // Right-aligned: x is the exclusive right edge.
  procedure WriteR(font:TFontHandle;x,y:single;color:cardinal;st:String8;options:cardinal=0);
  // Centered: x is the center
  procedure WriteC(font:TFontHandle;x,y:single;color:cardinal;st:String8;options:cardinal=0);
  // Two metrics of a text (unlike most text APIs, where "width" is the pen advance):
  // Width - the visible text: from the ink start of the first glyph to the ink edge of the
  //   last one. Not additive: Width(a+b)<>Width(a)+Width(b). Multi-line: the widest line.
  // Advance - the pen advance: where a next text would start. Additive up to the kerning at
  //   the junction. Multi-line: the widest line.
  // Neither translates the text: pass the text as it will be drawn.
  function Width(font:TFontHandle;st:String8):integer; // text width in pixels
  function WidthW(font:TFontHandle;st:String32):integer; // text width in pixels
  function Advance(font:TFontHandle;const st:String8):single;
  function AdvanceW(font:TFontHandle;const st:String32):single;
  // Pen position before each character of a single line: pos[i] for st[i], and
  // pos[length(st)] after the last one, pos[length]-pos[0]=AdvanceW(st). Relative to x of
  // Write (taLeft): the ink starts at x, so pos[0] is minus the bearing of the first glyph.
  // For a caret, a selection, hit-testing a click
  procedure PenPositions(font:TFontHandle;const st:String32;var pos:SingleArray);
  // Split a text into lines no wider than width (by Width). Breaks: explicit line breaks
  // (CR, LF, CRLF), then spaces; a word wider than width is broken between characters
  // (punctuation right after a word is a part of it: a line never starts with it).
  // Spaces at a break are dropped, empty lines kept; width<=0 - explicit breaks only.
  // widths - Width of each line
  function WrapText(font:TFontHandle;const st:String8;width:single):Strings8; overload;
  function WrapText(font:TFontHandle;const st:String8;width:single;out widths:SingleArray):Strings8; overload;
  // st if it fits width (by Width), otherwise st cut at a character boundary with ellipsis
  // at the cut (spaces at the cut dropped); '' if even the ellipsis doesn't fit. Without
  // ellipsis it is '…' (U+2026); '…' becomes '...' for a font without that glyph.
  // No default parameter value: FPC converts a non-ASCII default in the caller's source
  // codepage, so a caller unit without a BOM would get mangled bytes
  function FitText(font:TFontHandle;const st:String8;width:single;cut:TTextCut=TTextCut.atEnd):String8; overload;
  function FitText(font:TFontHandle;const st:String8;width:single;cut:TTextCut;const ellipsis:String8):String8; overload;
  function Height(font:TFontHandle):integer; // Height of capital letters (like 'A'..'Z','0'..'9') in pixels
  function MeasuredCnt:integer; // length of the measured rects array
  function MeasuredRect(idx:integer):TRect; // rect[idx] of text measurement command
  function MeasuredBounds:TRect; // bounding rect of the last measured text (relative to its pen position)
  function Measure(font:TFontHandle;st:String8;options:cardinal=0):TRect; // measure text extent (no drawing); supports '\n' and toComplexText
  // Hyperlinks
  procedure ClearLink; // Clear current link (call before text render)
  function Link:integer; // get hyperlink under mouse (filled during text render)
  function LinkRect:TRect; // get active hyperlink rect
  // Cache text output
  procedure BeginBlock(addOptions:cardinal=0); // optimize performance when drawing multiple text entries
  procedure EndBlock;   // finish buffering and perform actual render
  // Text render target
  procedure SetTarget(buf:pointer;pitch:integer); // set system memory target for text rendering (no clipping!)
 end;

 // Drawing interface
 IDrawer=interface
  // Basic primitives -----------------
  procedure Line(x1,y1,x2,y2:single;color:cardinal);
  procedure Line3D(x1,y1,z1,x2,y2,z2:single;color:cardinal); // line with explicit 3D coordinates
  procedure Triangle(p1,p2,p3:TVec3;color:cardinal); overload; // filled triangle, uniform color
  procedure Triangle(p1,p2,p3:TVec3;c1,c2,c3:cardinal); overload; // filled triangle, per-vertex color
  procedure Polyline(points:PVec2;cnt:integer;color:cardinal;closed:boolean=false);
  procedure Polygon(points:PVec2;cnt:integer;color:cardinal); overload;
  // a fill that vertex colors can't express goes through the shape shader (one program switch)
  procedure Polygon(points:PVec2;cnt:integer;const fill:TFill); overload;
  procedure BeginLines; // start batching line primitives
  procedure EndLines; // flush batched lines and stop batching
  procedure Rect(x1,y1,x2,y2:NativeInt;color:cardinal); overload;
  procedure Rect(x1,y1,x2,y2:single;color:cardinal); overload;
  procedure RRect(x1,y1,x2,y2:single;color:cardinal;r:single=2;steps:integer=0); overload; // geometry-based version
  procedure RRect(x1,y1,x2,y2:single;width,r:single;color:cardinal;steps:integer=0); overload; // geometry-based version
  // Rounded rectangle: a fill and a border with their own fills, antialiased edges.
  // x1..x2, y1..y2 - pixels included, as in FillRect. SDF shader on a tight mesh:
  // a frame with an invisible fill rasterizes only the band along the edge.
  // The fill lies inside the border; a border fkEdge spans its thickness (t=0 outside).
  procedure RoundRect(x1,y1,x2,y2:single;const radii:TCornerRadii;borderWidth:single;
    const border,fill:TFill); overload;
  procedure RoundRect(x1,y1,x2,y2:single;radius,borderWidth:single;const border,fill:TFill); overload;
  procedure RoundRect(x1,y1,x2,y2:single;radius,borderWidth:single;
    borderColor,fillColor:cardinal); overload; // solid shortcut; fillColor=0 - no fill
  procedure FillRect(x1,y1,x2,y2:NativeInt;color:cardinal); overload;
  procedure FillRect(x1,y1,x2,y2:single;color:cardinal); overload;
  // solid and 2-color linear fills - vertex colors in the standard program; others - the shape shader
  procedure FillRect(x1,y1,x2,y2:single;const fill:TFill); overload;
  procedure FillRRect(x1,y1,x2,y2:NativeInt;color:cardinal;r:single=2;steps:integer=0); overload;
  procedure FillRRect(x1,y1,x2,y2:single;color:cardinal;r:single=2;steps:integer=0); overload;
  procedure FillRRect(x1,y1,x2,y2:single;const fill:TFill;r:single=2); overload; // geometry edges, no AA
  procedure ShadedRect(x1,y1,x2,y2,depth:integer;light,dark:cardinal);
  procedure FillTriangle(x1,y1,x2,y2,x3,y3:single;color1,color2,color3:cardinal);
  procedure FillGradrect(x1,y1,x2,y2:integer;color1,color2:cardinal;vertical:boolean); // FillRect with TFill.Linear

  // Textured primitives ---------------
  // Coordinates specify the pixels that will be drawn (excluding the border)
  procedure Image(x_,y_:NativeInt;tex:TTexture;color:cardinal=clNeutral); overload;
  procedure Image(x,y,scale:single;tex:TTexture;color:cardinal=clNeutral;pivotX:single=0;pivotY:single=0); overload;
  procedure ImageFlipped(x_,y_:integer;tex:TTexture;flipHorizontal,flipVertical:boolean;color:cardinal=clNeutral);
  procedure Centered(x,y:NativeInt;tex:TTexture;color:cardinal=clNeutral); overload;
  procedure Centered(x,y,scale:single;tex:TTexture;color:cardinal=clNeutral); overload;
  procedure ImagePart(x_,y_:integer;tex:TTexture;color:cardinal;r:TRect);
  // Draw part of the image rotated ang times by 90 deg CW
  procedure ImagePart90(x_,y_:integer;tex:TTexture;color:cardinal;r:TRect;ang:integer);
  procedure TexturedRect(r:TRect;texture:TTexture;color:cardinal=clNeutral); overload;
  procedure TexturedRect(x1,y1,x2,y2:integer;texture:TTexture;u1,v1,u2,v2,u3,v3:single;color:cardinal=clNeutral); overload;
  procedure Scaled(x1,y1,x2,y2:single;image:TTexture;color:cardinal=clNeutral); overload;
  procedure Scaled(x,y,scale:single;image:TTexture;color:cardinal=clNeutral); overload;
  procedure RotScaled(x,y,scaleX,scaleY,angle:double;image:TTexture;color:cardinal=clNeutral;pivotX:single=0.5;pivotY:single=0.5);
  // Returns scale
  function Cover(x1,y1,x2,y2:integer;texture:TTexture;color:cardinal=clNeutral):single;
  function Inside(x1,y1,x2,y2:integer;texture:TTexture;color:cardinal=clNeutral):single;

  // Draw a billboard: place this texture at the specified 3D point toward camera
  // texelSize - size of one billboard texel in world CS
  procedure Billboard(pos:TVec3;texelSize:single;tex:TTexture;pivotX:single=0.5;pivotY:single=0.5;
      color:cardinal=clNeutral); overload;
  // screenScale - number of screen pixels per texel (so 2.0 results in tex upscaled 2x on screen)
  procedure Billboard(pos:TVec3;tex:TTexture;screenScale:single;pivotX:single=0.5;pivotY:single=0.5;
      color:cardinal=clNeutral); overload;

  // Meshes ------------------
  // Draw textured tri-mesh (tex=nil -> colored mode)
  procedure TrgList(vertices:PVertex;trgCount:integer;tex:TTexture); overload;
  procedure TrgList(vertices:pointer;layout:TVertexLayout;trgCount:integer;tex:TTexture); overload;
  procedure TrgList3D(vertices:PVertex3D;trgCount:integer;tex:TTexture); overload;
  // Draw indexed tri-mesh (tex=nil -> colored mode)
  procedure IndexedMesh(vertices:PVertex3D;indices:PWord;trgCount,vrtCount:integer;tex:TTexture); overload;
  procedure IndexedMesh(vertices:pointer;layout:TVertexLayout;indices:PWord;trgCount,vrtCount:integer;tex:TTexture); overload;
  procedure IndexedMesh(vb:TVertexBuffer;ib:TIndexBuffer;tex:TTexture); overload;


  // Multitexturing functions ------------------
  // Multitexturing mode must be configured beforehand with SetTexMode / SetTexInterpolationMode
  // and reset afterwards with SetTexMode(1,tblDisable)
  // Draw two images blended over each other in one pass (if the sizes differ, only the common part is visible)
  procedure DoubleTex(x,y:integer;image1,image2:TTexture;color:cardinal=clNeutral);
  // Draw two images (each with its own scale) rotated by the same angle. If the resulting sizes differ, only the common part is visible
  procedure DoubleRotScaled(x_,y_:single;scale1X,scale1Y,scale2X,scale2Y,angle:single;
      image1,image2:TTexture;color:cardinal=clNeutral);
  // Fill a rectangle (inclusive borders) with two images blended in one pass.
  // uv1/uv2 map normalized rectangle coordinates (0..1) to normalized coordinates (0..1) of each image,
  // cloned image parts included. Points mapped outside 0..1 sample neighbouring texels of the parent texture
  procedure DoubleTexturedRect(x1,y1,x2,y2:integer;image1:TTexture;const uv1:TMat32;
      image2:TTexture;const uv2:TMat32;color:cardinal=clNeutral);
  // Fill a rectangle with several textures (from a list)
  //procedure MultiTex(x1,y1,x2,y2:integer;layers:PMultiTexLayer;color:cardinal=clNeutral);

  // Particles ------------------------------------------
  procedure Particles(x,y:integer;data:PParticle;count:integer;tex:TTexture;gridSize:integer;zDist:single=0); overload; // 2D particles
  procedure Particles(x,y:integer;data:PParticle;stride:integer;count:integer;tex:TTexture;gridSize:integer;zDist:single=0); overload; // 2D particles
  procedure Particles(data:PParticle;count:integer;tex:TTexture;gridSize:integer); overload; // 3D particles
  procedure Particles(data:PParticle;stride:integer;count:integer;tex:TTexture;gridSize:integer;sort:boolean=true); overload; // 3D particles
  procedure Band(x,y:integer;data:PParticle;count:integer;tex:TTexture;r:TRect);
  // Make soft particles using specified depth texture (nil - get texture from game object)
  procedure EnableSoftParticles(depthRange:single;depthTex:TTexture=nil);
  procedure DisableSoftParticles;

  // Settings
  procedure SetZ(z:single=0.0); // Set Z coordinate for all 2D primitives
 end;

 // Interface to the graphics subsystem: OpenGL, Vulkan or Direct3D
 IGraphicsSystem=interface
  // Init subsystem and create all interface objects
  procedure Init(window:TWindow);
  // Explicit per-thread graphics bootstrap for current context-bound thread.
  // Must be called after shared-context activation in extra render threads.
  procedure InitThreadContext(window:TWindow);
  procedure Done;
  function GetVersion:single; // like 3.1 for OpenGL 3.1
  function GetName:string8; // get implementation class name

  // APIs
  function config:IGraphicsSystemConfig;
  function resman:IResourceManager;
  function target:IRenderTarget;
  function shader:IShader;
  function clip:IClipping;
  function transform:ITransformation;
  function draw:IDrawer;
  function txt:ITextDrawer;

  // Start drawing block using the specified render target (nil - use default target)
  procedure BeginPaint(target:TTexture=nil);
  // Finish drawing block
  procedure EndPaint;
  // Start of a frame: drop the paint state a failed frame could leave (nested BeginPaint,
  // saved render targets, masks and clipping rects) in the calling thread
  procedure ResetPaintState;
  // Set cull mode
  procedure SetCullMode(mode:TCullMode);

  // Get image from the current render surface: the backbuffer or the bound render target
  // (screenshot etc). srcX,srcY are REAL pixels of that surface with a top-left origin;
  // the image is filled top-down. Any image pitch works, negative included, so an image
  // can be read into repeatedly.
  // Canvas coordinates must be mapped first - see TWindow.CanvasToPixels/ReadFrameRect.
  procedure CopyFromBackbuffer(srcX,srcY:integer;image:TRawImage);
  // Get a single pixel value from the backbuffer (for debug/test purposes).
  // X,Y are real pixels of the backbuffer, top-left origin. Returns 0 when a
  // render target is bound.
  function GetPixelValue(X,Y:integer):cardinal;
  // Present backbuffer to the screen
  procedure PresentFrame;
  // Restore (invalidate) gfx settings
  procedure Restore;
  // show additional info
  procedure DrawDebugOverlay(idx:integer);
  // Do something meaningless (like glFlush) that can be detected by an external gfx debugger
  procedure Breakpoint;
 end;

 TGameScene = Apus.Engine.Scene.TGameScene;
 TSceneStatus = Apus.Engine.Scene.TSceneStatus;
 TSceneEffect = Apus.Engine.Scene.TSceneEffect;
 TSceneSwitcher = Apus.Engine.Scene.TSceneSwitcher;
 TUIScene = Apus.Engine.UIScene.TUIScene;

 // Enable built-in gamepad navigation with DPad and X/Y buttons
 TGamepadNavigationMode=(
   gnmDisabled,  // no gamepad navigation
   gnmCustom,    // enable navigation over manually specified points
   gnmAuto);     // enable navigation over manual points and clickable UI elements

 TDebugFeature=(
   dfShowFPS,                 // Display frame rate
   dfShowMagnifier,           // Magnifier (Alt+F3)
   dfShowGlyphCache,          // Display glyphs cache
   dfShowNavigationPoints     // Display gamepad navigation points
 );

 // Debug overlay hotkey presets as shiftState bitmasks.
 const
  dhAltFx      =sscAlt;
  dhCtrlAltFx  =sscAlt or sscCtrl;
  dhRAltFx     =sscAlt or sscRAlt;
  dhCtrlRAltFx =sscAlt or sscCtrl or sscRAlt;

 type
  TDebugHotkey=byte;

  // Main game interface (abstract class)
 TGameBase=class
  // Global state
  running:boolean;     // true when main loop is running
  terminated:boolean;   // true when main loop is finished
  renderingFrame:boolean; // true while RenderAndPresentFrame is on the stack (guards against re-entrant WM_PAINT redraw)
  screenWidth,screenHeight:integer; // real full screen size in pixels

  // Default (built-in) font handles (for debug overlays etc)
  smallFont,defaultFont,largerFont:TFontHandle; // font sizes are selected according to the screen DPI
  defaultLineHeight:integer; // line height (in pixels) for the default font
  screenScale:single; // screen scale factor (depends on DPI, rounded) like 1.0, 1.5 etc

  // Default checkers texture 32x32 with 8x8 blocks (for debug purposes)
  defaultTexture:TTexture;

  debugHotkey:TDebugHotkey; // shiftState mask for debug hotkeys (default - Alt+F1)

  gamepadNavigationMode:TGamepadNavigationMode; // used to enable gamepad (DPad) navigation over UI elements and user-defined objects

  globalTintColor:cardinal; // multiplier (2X) for whole backbuffer (clNeutral - neutral value)

  constructor Create(sysPlatform:ISystemPlatform;gfxSystem:IGraphicsSystem);

  // Settings
  procedure SetSettings(s:TGameSettings); virtual; abstract;
  function GetSettings:TGameSettings; virtual; abstract;

  // Start/stop game
  // ---------------
  procedure Run; virtual; abstract; // start the engine (create the window, switch the display mode etc.)
  procedure Stop; virtual; abstract; // stop and release all resources (Run is required to start again)
  // Change mode (Alt+Enter)
  procedure SwitchToAltSettings; virtual; abstract;

  // Frame events
  // ------------
  // Called before each frame. Returns true if something was changed and screen should be redrawn. False - nothing changed, no redraw.
  function OnFrame:boolean; virtual; abstract;
  // Renders frame to the backbuffer
  procedure RenderFrame; virtual; abstract;

  // Scenes
  // ------
  procedure AddScene(scene:TGameScene); virtual;
  procedure RemoveScene(scene:TGameScene); virtual;
  function TopmostVisibleScene(fullScreenOnly:boolean=false):TGameScene; virtual;
  function GetScene(name:string):TGameScene; virtual;

  procedure SwitchToScene(name:string); virtual; abstract; // switch to a fullscreen scene
  // Show a windowed scene. Returns at once, the show takes the time of the switcher's effect.
  // A scene that still hides is shown when the hide ends: its state (activation, modal stack,
  // focus) is not there right after the call
  procedure ShowWindowScene(name:string;modal:boolean=true); virtual; abstract;
  procedure HideWindowScene(name:string); virtual; abstract; // hide a windowed scene

  // Cursors
  // -------
  // Assign a cursor handle (system or cursom) to a cursor ID
  procedure RegisterCursor(CursorID,priority:integer;cursorHandle:TCursorHandle); virtual; abstract;
  // Get cursor handle assigned for given ID
  function GetCursorForID(cursorID:integer):TCursorHandle; virtual; abstract;
  // Toggle cursor on or off
  procedure ToggleCursor(CursorID:integer;state:boolean=true); virtual; abstract;
  // Toggle all cursors off
  procedure HideAllCursors; virtual; abstract;

  // Debug tools
  // -----------
  // Add a line to the "frame log" - an invisible log that is cleared every frame but can be saved in case of a crash
  procedure FLog(st:string); virtual; abstract;
  function GetStatus(n:integer):string; virtual; abstract;
  // Show message in engine-driven pop-up toast. severity: msgInfo/Success/Warning/Error.
  procedure FireMessage(st:String8;severity:integer=msgInfo); virtual; abstract;
  // Enable/disable debug overlays
  procedure DebugFeature(feature:TDebugFeature;enabled:boolean); virtual; abstract;

  // Synchronization (access to the internal critical section)
  // ---------------
  procedure Lock; virtual; abstract;
  procedure Unlock; virtual; abstract;

  // Screen capturing
  // ----------------
  // Set the flags requesting a screenshot (JPEG or TGA)
  procedure RequestScreenshot(saveAsJpeg:boolean=true); virtual; abstract;
  procedure RequestFrameCapture(obj:TObject=nil); virtual; abstract;

  // Utility functions
  // -----------------
  // Return interpolated color from color0 to color1 using AV sampled at the current frame time
  function ColorMix(var av:TAnimatedValue;color0,color1:cardinal):cardinal;
  // Multiply color's alpha by AV sampled at the current frame time
  function ColorAlpha(var av:TAnimatedValue;color:cardinal):cardinal;

  // Wait until pb^ is not false (not zero), toggle crWait cursor during waiting
  procedure WaitFor(pb:PBoolean;msg:string=''); virtual; abstract;

  // Keyboard events utility functions
  procedure SuppressKbdEvent; virtual; abstract; // Suppress handling of the related keyboard event(s)

  // Multi-window support
  // --------------------
  // Create an extra window with its own render thread, GL context (shared with main), and frame loop.
  // name - ASCII identifier of the window (TWindow.name); '' - an automatic one (Window1, Window2...)
  function AddWindow(settings:TGameSettings;const name:String8=''):TWindow; overload; virtual; abstract;
  // Simplified overload: windowed mode, full-size, no scaling, system cursor, vSync=1.
  function AddWindow(title:string;w,h:integer;const name:String8=''):TWindow; overload; virtual;
  // Stop the window's render thread, destroy GL context and native window.
  procedure RemoveWindow(wnd:TWindow); virtual; abstract;

  // Gamepad navigation
  // This should be called every frame for each point that should be available for navigation
  // during the next frame
  procedure DPadCustomPoint(x,y:single); virtual; abstract;
 end;

var
 // Global shortcuts to the key interfaces
 // ---------------------------------------
 // Ownership:
 // - systemPlatform/gfx are assigned by TGameBase during game creation
 // - shader/draw/txt/transform are assigned and cleared by graphics backend (TOpenGL.Init/Done)
 systemPlatform:ISystemPlatform;
 gfx:IGraphicsSystem;
 shader:IShader; //< shortcut for gfx.shader
 draw:IDrawer;    //< shortcut for gfx.draw
 txt:ITextDrawer; //< shortcut for gfx.txt
 transform:ITransformation; //< Shortcut for gfx.transform
 game:TGameBase;     // main program interface
 mainWindow:TWindow; // primary window instance (owned by the game runtime)

threadvar
 window:TWindow; // current window in the current runtime thread

var
 // Translate string using localization dictionary (UDict)
 Translate:function(s:String8):String8;
 Translate32:function(s:String32):String32;

 // Selected pixel formats for different tasks
 // Pixel formats in use (which formats to load graphics into)
 pfTrueColorAlpha:TImagePixelFormat; // format for loading true-color images with transparency
 pfTrueColor:TImagePixelFormat; // the same, without transparency
 pfTrueColorAlphaLow:TImagePixelFormat; // the same, for images whose quality can be sacrificed
 pfTrueColorLow:TImagePixelFormat; // the same, for images whose quality can be sacrificed
 // formats for rendering into a texture
 pfRenderTarget:TImagePixelFormat;       // regular image
 pfRenderTargetAlpha:TImagePixelFormat;  // variant with an alpha channel

 // Shortcuts to the most used functions
 // ------------------------------------

 // Load image from a file. In case of failure throws an exception!
 // fname is handled by Files.FixName()
 function LoadImageFromFile(fname:string;flags:cardinal=0;ForceFormat:TImagePixelFormat=ipfNone):TTexture;

 // (Re)load texture from an image file. defaultImagesDir is used if path is relative
 // Default flags can be used from defaultLoadImageFlags
 procedure LoadImage(var img:TTexture;fName:string;flags:cardinal=liffDefault);

 // Load a texture atlas.
 // Then if you try to load an image from a file - it is cloned from the atlas.
 // Not thread-safe! Don't load atlases in one thread and create images in other thread
 procedure LoadAtlas(fname:string;scale:single=1.0);

 // Load image from the specified file and create a Nine Patch object from it (image must be marked)
 // Set scale factor to 2 if image has double resolution
 function LoadNinePatch(fName:string;scale2x:boolean=false):TNinePatch;
 function CreateNinePatch(image:TTexture;scale2x:boolean=false):TNinePatch;

 // Create image from an in-memory source
 function CreateImageFrom(str:string8;padding:integer=0;flags:cardinal=0):TTexture;

 // Shortcuts to the texture manager
 function AllocImage(width,height:integer;pixFmt:TImagePixelFormat=ipfARGB;
                flags:integer=0;name:String8=''):TTexture; overload;
 function AllocImage(width,height,addMipLevels:integer;pixFmt:TImagePixelFormat=ipfARGB;
                flags:integer=0;name:String8=''):TTexture; overload;
 procedure FreeImage(var img:TTexture);

 // Lock the texture (if not yet locked) and set it as draw target for FastGFX unit (don't forget to unlock)
 procedure DrawToTexture(tex:TTexture;mipLevel:integer=0);

 // Process events/system messages and wait at least time ms
 procedure Delay(time:integer); inline;

 // Returns value of the Animated Value sampled at the current frame time
 function CurValue(var av:TAnimatedValue):single; inline;
 // Convert device-independent pixels (DIP, 96 DPI baseline) to canvas units of the
 // current window (a fixed canvas is scaled by itself, so its own DPI is used).
 function Dp(v:single):single; inline;

 // Utility functions
 function GetKeyEventScanCode(tag:TTag):cardinal; // Extract scancode (Scan.XXX) from KBD\KeyXXX event
 function GetKeyEventVirtualCode(tag:TTag):cardinal; // Extract virtual key code form KBD\KeyXXX event

 function GetKeyUniChar(keyCode:cardinal):cardinal;  // Extract unicode character for value from ReadKey
 function GetKeyCode(keyCode:cardinal):cardinal;     // Extract virtual key code for value from ReadKey
 function GetKeyScanCode(keyCode:cardinal):cardinal; // Extract scancode for value from ReadKey

 // Is mouse button pressed?
 function IsMouseBtn(btn:integer):boolean;
 // Key state of the current window by scancode - the key position (Scan.XXX), not its meaning.
 // Is the key down now?
 function IsKeyDown(scanCode:integer):boolean;
 // Did the key go down in this frame? (a press shorter than a frame is seen too)
 function IsKeyPressed(scanCode:integer):boolean;
 // Did the key go up in this frame?
 function IsKeyReleased(scanCode:integer):boolean;

 // Allow showing a system message box for critical errors. Disabled in exclusive
 // fullscreen, where a modal box cannot be shown.
 var allowCriticalPopup:boolean=true;

 // Report a critical error: log it at Error level and, when allowed, show a system
 // message box. Used by the engine's top-level exception handlers.
 procedure CriticalError(const msg:String8);

implementation
 uses SysUtils, Apus.Strings, Apus.Utils, Apus.Publics, Apus.Engine.ImageTools, Apus.Engine.Game,
   TypInfo, Apus.Engine.Tools, Apus.Engine.Graphics, Apus.FastGFX, Apus.Engine.NinePatch;

 var
  ninePatchHash:TObjectHash;

 procedure CriticalError(const msg:String8);
  begin
   Log.Error(msg);
   if allowCriticalPopup then SystemMessage(msg); // visible crash report (except exclusive fullscreen)
  end;

 function TranslateNoop8(s:String8):String8;
  begin result:=s; end;
 function TranslateNoop32(s:String32):String32;
  begin result:=s; end;

 function GetKeyEventScanCode(tag: TTag): cardinal;
  begin
   result:=(tag shr 16) and $FFFF;
  end;

 function GetKeyEventVirtualCode(tag: TTag): cardinal;
  begin
   result:=tag and $FFFF;
  end;

 function GetKeyUniChar(keyCode:cardinal):cardinal;
  begin
   result:=keyCode shr 16;
  end;

 function GetKeyCode(keyCode:cardinal):cardinal;
  begin
   result:=0;
   if (keyCode and $FFFF0000=0) then
    result:=keyCode and $FF
  end;

function GetKeyScanCode(keyCode:cardinal):cardinal;
  begin
   result:=(keyCode shr 8) and $FF;
  end;

constructor TGameBase.Create(sysPlatform:ISystemPlatform;gfxSystem:IGraphicsSystem);
  begin
   game:=self;
   systemPlatform:=sysPlatform;
   gfx:=gfxSystem;
   debugHotkey:=dhAltFx;
  end;

// The scene list belongs to the window and is guarded by its lock: taking the game lock
// here would nest game -> window against the window -> game order
procedure TGameBase.AddScene(scene:TGameScene);
 begin
  if scene=nil then raise EWarning.Create('Can''t add nil scene');
  mainWindow.AddScene(scene);
 end;

procedure TGameBase.RemoveScene(scene:TGameScene);
 begin
  mainWindow.RemoveScene(scene);
 end;

function TGameBase.TopmostVisibleScene(fullScreenOnly:boolean=false):TGameScene;
 begin
  result:=mainWindow.TopmostVisibleScene(fullScreenOnly);
 end;

function TGameBase.GetScene(name:string):TGameScene;
 begin
  Lock;
  try
   result:=TGameScene.FindByName(name) as TGameScene;
  finally
   Unlock;
  end;
  ASSERT(result<>nil,'Scene '+name+' not found!');
 end;

// Utils
function fGetFontHandle(params:string8;tag:integer;context:pointer;contextClass:TVarClassStruct):double;
 var
  sa:Strings8;
  style,effects:byte;
  size:double;
 begin
  if txt=nil then raise EWarning.Create('TextDrawer is not ready');
  sa:=params.Split(',');
  if length(sa)<2 then raise EWarning.Create('Invalid parameters');
  size:=EvalFloat(sa[1],nil,context,contextClass);
  style:=0; effects:=0;
  if length(sa)>2 then style:=round(EvalFloat(sa[2],nil,context,contextClass));
  if length(sa)>3 then effects:=round(EvalFloat(sa[3],nil,context,contextClass));
  result:=txt.GetFont(sa[0],size,style,effects);
 end;

function LoadImageFromFile(fname:string;flags:cardinal=0;ForceFormat:TImagePixelFormat=ipfNone):TTexture;
 begin
   result:=Apus.Engine.ImageTools.LoadImageFromFile(fname,flags,forceFormat);
 end;

procedure LoadImage(var img:TTexture;fName:string;flags:cardinal=liffDefault);
 begin
   Apus.Engine.ImageTools.LoadImage(img,fname,flags);
 end;

procedure LoadAtlas(fname:string;scale:single=1.0);
 begin
   Apus.Engine.ImageTools.LoadAtlas(fname,scale);
 end;

function CreateImageFrom(str:string8;padding:integer;flags:cardinal):TTexture;
 begin
  result:=Apus.Engine.ImageTools.CreateImageFromString(str,padding,flags);
 end;

function LoadNinePatch(fName:string;scale2x:boolean=false):TNinePatch;
 var
  img:TTexture;
 begin
  img:=LoadImageFromFile(fName,liffAllowChange);
  result:=CreateNinePatch(img,scale2x);
 end;

function CreateNinePatch(image:TTexture;scale2x:boolean=false):TNinePatch;
 begin
  result:=TCustomNinePatch.Create(image);
  if scale2x then result.scaleFactor:=0.5;
 end;

function AllocImage(width,height:integer;pixFmt:TImagePixelFormat=ipfARGB;
                flags:integer=0;name:String8=''):TTexture;
 begin
  result:=AllocImage(width,height,0,pixFmt,flags,name);
 end;

function AllocImage(width,height,addMipLevels:integer;pixFmt:TImagePixelFormat=ipfARGB;
                flags:integer=0;name:String8=''):TTexture;
 begin
  if gfx.resman<>nil then
   result:=gfx.resman.AllocImage(width,height,addMipLevels,pixFmt,flags,name)
  else
   raise EWarning.Create('Failed to alloc texture: no texture manager');
 end;

procedure FreeImage(var img:TTexture);
 begin
  if img<>nil then
   gfx.resman.FreeImage(img);
 end;

procedure Delay(time:integer);
 begin
  Apus.Engine.Game.Delay(time);
 end;

function CurValue(var av:TAnimatedValue):single;
 begin
  result:=av.ValueAt(window.frameStartMs);
 end;

function Dp(v:single):single;
 begin
  ASSERT(window<>nil);
  result:=v*window.canvasDPI/96;
 end;

function IsMouseBtn(btn:integer):boolean;
 begin
  ASSERT(window<>nil);
  result:=Bits.HasAll(window.mouseButtons,1 shl (btn-1));
 end;

function KeyStateBits(scanCode:integer):byte; inline;
 begin
  ASSERT(window<>nil);
  if (scanCode>0) and (scanCode<Scan.Count) then result:=window.keyState[scanCode]
   else result:=0;
 end;

function IsKeyDown(scanCode:integer):boolean;
 begin
  result:=KeyStateBits(scanCode) and 1<>0;
 end;

function IsKeyPressed(scanCode:integer):boolean;
 begin
  result:=KeyStateBits(scanCode) and 2<>0;
 end;

function IsKeyReleased(scanCode:integer):boolean;
 begin
  result:=KeyStateBits(scanCode) and 4<>0;
 end;

procedure DrawToTexture(tex:TTexture;mipLevel:integer=0);
 begin
  if not tex.IsLocked then tex.Lock(mipLevel);
  SetRenderTarget(tex.data,tex.pitch,tex.width shr mipLevel,tex.height shr mipLevel);
 end;

{ TNinePatch }

class function TNinePatch.ClassHash:pointer;
 begin
  result:=@ninePatchHash;
 end;

function TGameBase.ColorMix(var av:TAnimatedValue;color0,color1:cardinal):cardinal;
 begin
  result:=Apus.Colors.Color.Mix(color0,color1,Clamp(av.ValueAt(window.frameStartMs),0,1));
 end;

function TGameBase.ColorAlpha(var av:TAnimatedValue;color:cardinal):cardinal;
 begin
  result:=Apus.Colors.Color.Scale(color,Clamp(av.ValueAt(window.frameStartMs),0,1));
 end;

function TGameBase.AddWindow(title:string;w,h:integer;const name:String8=''):TWindow;
 var
  s:TGameSettings;
 begin
  Mem.Clear(s,sizeof(s));
  s.title:=title;
  s.width:=w;
  s.height:=h;
  s.mode:=Apus.Engine.Types.dmWindow;
  s.surface.Init; // tool windows use the full client area
  s.showSystemCursor:=true;
  s.vSync:=1;
  result:=AddWindow(s,name);
 end;


initialization
 Translate:=TranslateNoop8;
 Translate32:=TranslateNoop32;
 PublishFunction('GetFont',fGetFontHandle);
 TVertex.layoutTex.Init([vcPosition3d,vcColor,vcUV1]);
 TVertex.layoutTex.stride:=Sizeof(TVertex);
 TVertex.layoutNoTex.Init([vcPosition3d,vcColor]);
 TVertex.layoutNoTex.stride:=Sizeof(TVertex);
end.