Siege Engine Client
Version 0.9.0

The Siege Engine is a game engine written in the Rust Language and targeting
the Vulkan API on both Linux and Microsoft Windows operating systems.

The current engine:
1) Renders stars and milkyway, as seen from Earth.
2) Renders 2 suns (and other heavenly bodies) based on an n-body simulation.
3) Renders a blue horizon (not yet ocean-like)
4) Renders simple terrain: 512 meters x 512 meters as grass (diffuse, normal,
   ambient occlusion, cavity and roughness maps) using full mipmap levels and
   anisotrophy; Current technique is too slow for larger terrain.
5) Renders 3 cubes. If a cube is not visible, its draw calls are not submitted
   (using view frustum culling).
6) Shades all geometry (deferred shading technique) using improved Blinn-Phong.
7) Blooms over-bright pixels. Tonemaps using one of several user-selectable
   tonemappers. Adjusts the white-level / exposure based on daytime/nighttime.
8) Lets the user operate the camera to move around the terrain, rotate, strafe,
   and pitch up/down. Stays clamped to 2m above terrain underfoot.
9) Renders multiple lines of text of different font/size/color/outline. Renders
   performance timing measurements, updated every 60 frames.
10) Connects over the network to a server, synchronizes time and n-body simulation,
    and ping-pongs heartbeat messages.

Enjoy!


Running:
--------

Simply run the executable (from the directory it is in - it looks for "assets/"
in its current directory).

If you pass an argument to the executable, it will look for a file of that
name and use it for it's configuration file. Such file must be in TOML format.
A default configuration file is provided called `siege.toml.default`.


Vulkan Support:
---------------

This program requires a rather new (circa 2016) graphics API called Vulkan,
although this API has been backported to older cards.  If you get an error
message mentioning Vulkan (e.g. vulkan is not supported, or vulkan-1.dll could
not be found, or similar), then you may need to update your graphics drivers
and/or install vulkan support packages for your computer. Vulkan version
required is nothing more than 1.0.3.

For help getting vulkan support, refer to your OS vendor or to the website for
your graphics card manufacturer:

  * ATI: https://www.amd.com/en/technologies/vulkan
  * ARM (Mali): https://developer.arm.com/graphics/vulkan
  * ImgTec: https://community.imgtec.com/developers/powervr/vulkan/
  * Intel: https://www.intel.com/content/www/us/en/support/products/80939/graphics-drivers.html
  * NVidia: https://developer.nvidia.com/vulkan-driver
  * Qualcomm (Adreno): https://developer.qualcomm.com/software/adreno-gpu-sdk/gpu


----------------------------------------------------------------------------
History
-------

As each feature is introduced, we consider it thereafter an "invariant": every
subsequent release must also fully support that feature.  If this is not the
case, a subsequent version must boldly indicate the reversion of the feature.

0.9:
  * Accurate GPU timing now measures how many milliseconds each pass takes, and compares
    against fence time (to compute overhead), and loop time (to compute FPS).
  * Statistics including GPU timing, lighting data, network data, and virtual world
    dates are rendered to screen and kept updated (all to upper right, except date which
    is in the upper left).
    * Virtual date is in a very provisional format that will be changing.
    * `svr sync` is essentially the fastest server ping time so far.
  * LICENSE files of all libraries we depend on are now included.
  * Geometry (not terrain yet) which is entirely offscreen is no longer sent to the GPU.
    This is done via "view frustum culling" and "bounding volumes".
  * Improved lighting level curves (dusk is no longer so bright).
  * Minor changes, bug fixes, and internal refactors:
    * Chat window is now black
    * Alpha blending is consistent now, and not dependent on render target sRGB mode.
    * Outputs fewer terminal messages
    * Program reliably exits on panic, instead of potentially freezing.
    * vsync config is retired; output is always done on vertical refresh using the most
      recently rendered frame whenever possible. If MAILBOX mode is not available, there
      is a possibility of screen tearing in situations where the FPS drops below 60, but
      we present immediately in those cases to avoid stuttering, which we feel is worse
      than tearing. Note: Tearing in x-windows is not something we can fix - it happens
      after the vulkan presentation layer.
    * Setup is faster as orbit simulation is synced with the server prior to being
      maintained locally (less catch-up lag).
    * Fixed the spark in your head's shadow.
    * Improved network code

0.8
  * Signed-distance field font rendering:
    * Fonts textures are pregenerated and have low memory requirements
    * Fonts have a strikingly good detail at any scale, even with small source textures.
    * Subpixel rendering alpha-blends the edges to give a smooth result.
    * Text is specified as unicode strings (but fonts themselves have limited glyph support).
    * A single vertex buffer handles up to 5000 characters and is rebuilt (but not reallocated)
      every time any text changes.
  * Text line management
    * Lines of text are specified along with screen position, pixel offset, line height,
      font (4 choices), color (8 choices), optional outline color, and alpha mask.
    * Submitted lines of text can later be updated or deleted.
    * This will move into the UI once UI structures are built.

0.7
  * Ambient light level and exposure/white-point change slowly, simulating dusk and
    the dark of night, and transition well.
  * Force exposure config option (can set to night even during the day!)
  * Star pixelation config parameter (for sharp single-pixel stars)
  * Subpixel stars
  * Back to normal speed
  * Less frequent server heartbeats
  * Synchronizes orbit positions on server connection
  * Turf texture includes 'cavity' and 'roughness' now.
  * F9/F10 adjust bloom strength, F11/F12 adjust general blur
  * Many fixes including
    * Lighting level fixes and tweaks
    * Bloom fixes and tweaks
    * Star and galaxy fixes and tweaks
    * Alpha blending fix
    * Horizon reshaded

0.6
  * Terrain:
    * 512m x 512m patch of terrain
    * Triplanar texturing (doesn't stretch as terrain gets tall)
    * Textured with grass (using diffuse, normal, and ambient occlusion
      maps), using texture mipmap levels, sampling with anisotrophic
      filtering.
    * Geometry rendered as a single triangle strip
  * Horizon: blue like the ocean, but not meant to be ocean, more of a safety
    layer.
  * Grayboxes changed to 3: one each at +1x, +1y and +1z
  * Camera stays at 2m above the terrain level it is at.
  * Arrow keys work for movement.
  * Input sampled at 60fps (was 20)
  * Tonemapper is now selectable in the config file (Clamp, Reinhard,
    Exposure, HybridLogGamma or FalseColor).
  * Code changes:
    * siege-render is separate library.
    * renderer now uses a deferred shading strategy.
    * Multiple fixes and improvements
    * Ambient color rendering has been fixed
    * View and Projection matrices were both wrong, but cancelled out. This
      required fixing now as we are starting to use view space.

0.5
  * RETIRED/REVERTED FEATURES FROM 0.4:
    * Render modes retired
    * White point adjustment (F1/F2) gone, it is now dynamic.
  * Multipass rendering, enabling:
    * Early-Z pass for performance
    * Blooming of overbright pixels (blur)
    * Post processing: tone mapping
    * UI compositing at the very end
  * Support added for 4K UHD resolution
  * White point is now dynamic
  * Fixed frame timing calculation
  * Anisotropic sampling

0.4
  * Mutiple grayboxes
  * Milkyway galaxy rendered along with (and aligned with) the stars.
  * Numerous values fixed: world tip, sun irradiances, widths of suns,
    speed of simulation, rotation speed of camera, etc.
  * Sun irradiance (for lighting purposes) dims as it drops below the horizon
    based on the area of the solar disk showing.
  * White point (exposure) is now adjustable (F1/F2).
  * Zoom is now adjustable (F3/F4).
  * Frame timing calculations added.
  * Numerous bug fixes and code improvements.


0.3
  * RETIRED/REVERTED FEATURES FROM 0.2:
    * Simple 'Triangle' rendering is now removed.
  * Demonstration UI rectangles with high alpha transparency are drawn.
  * Orbit Simulation:
    * Two suns, two planets, and a moon are being numerically simulated using
      gravity calculations. The orbits have been tested to remain stable for at
      least 20 years of real-world time. Planet orbits red dwarf, which orbits
      main sequence star. Second planet also orbits red dwarf closer in. Moon
      orbits main planet.
    * Some orbit settings are temporary for testing only:
      * The simulation is running extremely fast (1:6000 rather than the
        intended 1:60)
      * The world rotation angle is perpendicular to the direction of the main
        sequence star, rather than it's normal 29 degrees.
      * The camera is representing a person standing on the North pole, rather
        than at about 10-40 degrees latitude as it would during a game.
    * The stars are now rotating with accurate orientation and motion. This is
      due to the spin of the planet.
    * Two suns are being rendered as white squares. The other planet and the
      moon are not yet being rendered. The color, size, and shape are all
      inaccurate placeholders, but the location is correct.
  * One graybox renders in space, with metallic settings, showing off the
    Blinn-Phong shading (see below).
  * Rendering
    * Color and Luminance Accuracy: Physically-based color and brightness
      implemented including CIE 1931 color spaces, accurate sRGB, irradiance
      values in lumens per square meter, contrast ratio mapping with white and
      black points (exposure / saturation), star magnitude and blackbody
      radiation calculations.
    * Physically-improved Blinn-Phong shading is implemented for grayboxes.
      The lighting used for this shading, currently from the two suns, uses the
      physically correct color and intensity based on the star catalog data.
    * Fixes
      * Depth buffer now float (reversed-z is pointless without this)
      * Verify graphics card capabilities better
      * Memory writes are now flushed where memory is coherent
      * View matrix fixed - full pitch-up/pitch-down working now.
    * Performance
      * Memory deallocation works
      * Buffers and Images are copied into device memory, instead of running
        out of slower shared host memory.
      * Graphics loop performance better
      * Choose device resources better (queue families for transfer)
      * Fewer pipeline rebuilds and command buffer recording operations (dynamic
        states)
    * Meshes are loaded from files now.
    * Multiple objects share the same buffers if they are using the same mesh or
      texture.
    * Texture code in well progressed but not in use yet by rendered objects.
      DDS texture files are supported, with BC compression, and files are using
      fast lossless zstd compression.
  * Math
    * Quaternions and Angles implemented.
    * Many other improvements among vectors, directions, points and matrices.

0.2
  * RETIRED/REVERTED FEATURES FROM 0.1:
    * max_fps throttle is now configurable, and defaults to 120 (was fixed at
      60)
    * Triangle rendering has changed (but we still render a couple small
      triangles in the lower left)
  * Network connection to a server:
    * Optional, via configuration
    * UDP packet based
    * Packets have magic number and version number, to detect incorrect clients
    * Packets are encrypted and authenticated
    * Server is authenticated via a well known public key
    * Init/Ack, Heartbeat/Ack, UpgradeRequired packets currently supported
    * Clock synchronization between client and server
  * Better thread and error handling
  * Camera
    * Perspective projection
  * Input event handling
    * <LOGO>-ESC quits
    * Camera motion with WASD, QE and PgUp/PgDn
  * Graphics
    * Better graphics device setup
    * Better CPU utilization
    * Resource manager
    * Render Modes (only one can be used per frame, generally only one is ever
      used)
    * GPU memory allocation
    * Drawables as pipelines:
      * Triangle
      * Stars
        * Renders a database of stars from the perspective of Earth
        * Renders stars using up to 9 pixel GL_POINTs with faded edges
        * Uses actual star color temperature and magnitude to compute star area
          (brightness) and color.
    * Depth buffer
      * Reversed-z coordinate for better precision at the far plane

0.1
  * Memory and multi-thread safety via the Rust language
  * Full OS support for
    * Linux (x86_64)
    * Microsoft Windows (win64)
  * Window support for multiple platforms:
    * Linux X Windows via XLib
    * Windows via HWND
    * Android Window (even though Android is not fully supported yet)
    * MacOS via NSWindow (even though MacOS is not fully supported yet)
  * Window handles damage events, and can be resized and moved dynamically
    with rendered content remaining visible
  * Window can be fullscreen
  * Vulkan 3D graphics support
    * Rendering of a triangle (temporary, will be reverted)
    * Vulkan layer support
  * Throttled to 60fps so that it does not hog CPU resources
  * Configuration via a configuration file.
  * Logging which is configurable
  * Shuts down cleanly
