goff/README.md

# Goff Film Scanner Software

Goff is software application to work with the Nikon Coolscan line of scanners,
specifically (Coolscan IV LS-40ED, Coolscan LS-4000 ED, Coolscan LS-5000 ED /
Coolscan LS-50 ED, Coolscan LS-8000 ED, Coolscan LS-9000 ED). Its sole purpose
is to be a modern equivalent of the now discontinued NikonScan software.

The primary plan for now is to be feature complete with NikonScan, with emphasis
on taking advantage of modern hardware capabilities to improve speed, and better
user experience compared to the OG NikonScan.

## Guarantees
This application guarantees the following:
 - x86-64 architecture support
 - Support for Windows 10 and above.
 - Complete support for the following Coolscan scanners:
   - Coolscan IV LS-40ED
   - Coolscan LS-4000 ED
   - Coolscan LS-5000 ED / Coolscan LS-50 ED
   - Coolscan LS-8000 ED
   - Coolscan LS-9000 ED

## Status
Goff is currently in the Pre-Alpha stage, meaning things it is not anywhere near
a useable product and things are  expected to break and change without any notice.


## Development Setup Instructions

**Note: Only x64 Windows development is supported.**

### 1. Installing the Required Tools (MSVC & Windows SDK)

In order to work with the codebase, you'll need the [Microsoft C/C++ Build Tools
v15 (2017) or later](https://aka.ms/vs/17/release/vs_BuildTools.exe), for both
the Windows SDK and the MSVC compiler and linker.

If the Windows SDK is installed (e.g. via installation of the Microsoft C/C++
Build Tools). At this time, support for other compilers like clang is not
supported.

### 2. Build Environment Setup

Building the codebase can be done in a terminal which is equipped with the
ability to call MSVC  from command line.

This is generally done by calling `vcvarsall.bat x64`, which is included in the
Microsoft C/C++ Build Tools. This script is automatically called by the `x64
Native Tools Command Prompt for VS <year>` variant of the vanilla `cmd.exe`. If
you've installed the build tools, this command prompt may be easily located by
searching for `Native` from the Windows Start Menu search. Alternatively you
could run the following command in your preferred console emulator on windows

```
"C:\Program Files\Microsoft Visual Studio\<year>\Community\VC\Auxiliary\Build\vcvars64.bat"
```

You can ensure that the MSVC compiler is accessible from your command line by
running:

```
cl
```

If everything is set up correctly, you should have output very similar to the
following:

```
Microsoft (R) C/C++ Optimizing Compiler Version 19.40.33811 for x64
Copyright (C) Microsoft Corporation.  All rights reserved.

usage: cl [ option... ] filename... [ /link linkoption... ]
```

### 3. Building

Within this terminal, `cd` to the root directory of the codebase, and just run
the `build.bat` script:

```
build
```

You should see the following output:
```
[debug mode]
[msvc compile]
[default mode, assuming `goff` build]
goff_main.c
```

If everything worked as it should, the executable will be in the `run_tree` folder
in the root of the codebase, and it will contain a freshly-builth `Goff Scan.exe`

## Top-Level Directory Descriptions
- `run_tree`: This directory contains everything that is needed for a debug build
   of the application to run.
- `run_tree/data` Contains small binary files (i.e. .rc files, logo, fonts, etc)
   used when building, to embed or package with the application.
- `src`: All the source code.


## Codebase Introduction

The codebase is organized into *layers*. Layers are separated either to isolate
certain problems, and to allow inclusion into various builds without needing to
pull everything in the codebase into a build. Layers correspond with folders
inside of the `src` directory. Sometimes, one folder inside of the `src`
directory will include multiple sub-layers, but the structure is intended to be
fairly flat.

Layers correspond roughly 1-to-1 with *namespaces*. The term "namespaces" in
this context does not refer to specific namespace language features, but rather
a naming convention for C-style namespaces, which are written in the codebase as
a short prefix, usually 1-3 characters, followed by an underscore. These
namespaces are used such that the layer to which certain code belongs may be
quickly understood by glancing at code. The namespaces are generally quite short
to ensure that they aren't much of a hassle to write. Sometimes, multiple sub-
layers will share a namespace. A few layers do not have a namespace, but most
do. Namespaces are either all-caps or lowercase depending on the context in
which they're used. For structs, enum values, and some macros, they are
capitalized. For functions and global variables, they are lowercase.

Layers depend on other layers, but circular dependencies would break the
separability and isolation utility of layers (in effect, forming one big layer),
so in other words, layers are arranged into a directed acyclic graph.

A list of layers in the codebase and their associated namespaces are below:
- `base` (no namespace): Universal, codebase-wide constructs. It contains
  strings, math, memory allocators, threading, and logging.
  It depends on no other codebase layers.
- `es/core` (`ES_`): Short for Engine Subsystem. Implements the 
- `es/gfx` (`ES_`): Engine Subsystem graphical frontend. Builds on top of
   `es/core` to provide graphical features such as windows, panels, and all
   interfaces needed for using the scanner. It is the main user of `os/gfx`.
- `os/core` (`OS_`): An abstraction layer that provides core, non-graphical
  functionality from the operating sytem under a general use abstraction API.
  This is implemented per supported operating system.
- `os/gfx` (`OS_`): This layer builds on top of `os/core`, it provides
   graphical operating functionalities under a general use abstraction API.
- `ui` (`UI_`): For building graphical user interfaces. Provides a core
  immediate mode hierarchical user interface data structure building API, and
  has helper layers for building higher level widgets.