New src directory layout

[carlos-lopez-garces]

The current src directory tree is rather flat. We might want to give it more structure to, among other things:

• convey more clearly the role of files by grouping related ones together under a directory name that conveys that role; this helps with forming a sharper mental model of the code and with navigating the code base for the 1st time; and

• take a first step towards a future code refactor; a directory layout with more structure could help us see what a formal (Javascript) object model could look like. For example, sometimes a directory structure models a hierarchy of objects of different levels of abstraction and hints at the boundaries that must not be crossed to keep loose coupling.

The repos of mature graphics libraries and renderers like Three.js, pbrt, and Machete have a structured directory layout. HOVER's ray tracing renderer was open-sourced when it reached a certain level of maturity in terms of features and performance. A structured directory layout is not a feature, but it's yet another way to display that maturity.

What follows is a suggested directory layout for src. It is heavily influenced by the src directories of Three.js and pbrt, because we could say that one is the parent project and the other is the theoretical inspiration of the renderer (no?).

Besides the obvious file grouping based on role, the following ideas are encoded in it:

• File extensions that reveal the real contents of a file. For example, .glsl.js for shader programs assembled by Javascript, .png.js for image strings. This convention is used by Three.js.
• Consistent capitalization of file and directory names.

Three.js, pbrt, and Machete all have a src/core directory. From what I can see in them and from experience , core directories either contain a) a minimal set of files that implement a minimal version of the software (other directories may be seen as extensions, alternatives, and advanced use cases) or b) the set of core abstractions. I feel like neither applies to HOVER's renderer and so I don't include a src/core directory.

2 other things we might want to explore are: 1) avoiding the use of many utils files, which are typically miscellaneous bags of functions; we might want to take a closer look at their contents and see if the functions can be classified into separate files and directories; and 2) stick to nouns for file names, as opposed to actions like mergeMeshesToGeometry (this is highly idiosyncratic, though, and may not be a big deal).

Please let me know what you think.

New directory tree:

src
├── cameras (like three.js/src/cameras; maybe also like pbrt-v3/src/cameras) 
|   └── LensCamera.js
├── Constants.js (formerly src/constants.js)
├── lights (like three.js/src/lights; maybe also like pbrt-v3/src/lights)
|   ├── EnvironmentLight.js
|   └── SoftDirectionalLight.js
├── main.js (unchanged)
├── materials (like three.js/src/materials; maybe also like pbrt-v3/src/materials)
|   └── RayTracingMaterial.js
└── renderer (already like three.js/src/renderers)
    ├── accelerators (like pbrt-v3/src/accelerators)
    |   ├── BVHAccelerator.js (formerly src/renderer/bvhAccel.js)
    |   └── BVHUtil.js (formerly src/renderer/bvhUtil.js)
    ├── assets
    │   ├── noise.png (formerly src/renderer/texture/HDR_L_0.png)
    │   ├── noise.png.js (formerly src/renderer/texture/noise.js)
    │   └── README.md (formerly src/renderer/texture/readme.txt)
    ├── GL.js (formerly src/renderer/glUtil.js)
    ├── RenderingPipeline.js
    ├── samplers (like pbrt-v3/src/samplers)
    │   ├── StratifiedSampler.js
    │   └── StratifiedSamplerCombined.js
    ├── shaders (like three.js/src/renderers/shaders)
    │   ├── glsl
    │   │   ├── chunks (nicer than three.js/src/renderers/shaders/ShaderChunk)
    │   │   │   ├── bsdf.glsl.js (Three.js's suffix and extension convention: .glsl.js)
    │   │   │   ├── envmap.glsl.js
    │   │   │   ├── intersect.glsl.js
    │   │   │   ├── random.glsl.js
    │   │   │   ├── sample.glsl.js
    │   │   │   ├── sampleGlassMicrofacet.glsl.js
    │   │   │   ├── sampleGlassSpecular.glsl.js
    │   │   │   ├── sampleMaterial.glsl.js
    │   │   │   ├── sampleShadowCatcher.glsl.js
    │   │   │   └── textureLinear.glsl.js
    │   │   ├── fullscreenQuad.vert.js (optionally use three.js's suffix and ext convention: _vertex.glsl.js, _fragment.glsl.js)
    │   │   ├── rayTrace.frag.js
    │   │   ├── reproject.frag.js
    │   │   └── toneMap.frag.js
    │   ├── FullscreenQuadShader.js (formerly src/renderer/FullscreenQuad.js)
    │   ├── GLSL.js (formerly src/renderer/glslUtil.js)
    │   ├── RayTracingShader.js
    │   ├── ReprojectShader.js
    │   └── ToneMapShader.js
    ├── textures (i.e. GPU buffers)
    |   ├── FrameBuffer.js (formerly src/renderer/Framebuffer.js)
    |   ├── Texture.js
    |   ├── TextureAllocator.js
    |   └── RenderTargets.js
    ├── maps (i.e. texture mapping)
    |   ├── EnvironmentMap.js (formerly src/renderer/envMapCreation.js)
    |   ├── EnvironmentMapDistribution.js (formerly src/renderer/envmapDistribution.js)
    |   └── Maps.js (formerly src/renderer/uploadBuffers.js)
    └── Util.js (src/renderer/util.js)
    .
    .
    . (need to study these more closely to classify them properly)
    . mergeMeshesToGeometry.js
    . rgbeToFloat.js
    . texturesFromMaterials
    . TileRender.js

For your reference, this is the current src directory tree:

src
├── EnvironmentLight.js
├── LensCamera.js
├── RayTracingMaterial.js
├── RayTracingRenderer.js
├── SoftDirectionalLight.js
├── constants.js
├── main.js
└── renderer
    ├── Framebuffer.js
    ├── FullscreenQuad.js
    ├── RayTracingShader.js
    ├── RenderTargets.js
    ├── RenderingPipeline.js
    ├── ReprojectShader.js
    ├── StratifiedSampler.js
    ├── StratifiedSamplerCombined.js
    ├── Texture.js
    ├── TextureAllocator.js
    ├── TileRender.js
    ├── ToneMapShader.js
    ├── bvhAccel.js
    ├── bvhUtil.js
    ├── envMapCreation.js
    ├── envmapDistribution.js
    ├── glUtil.js
    ├── glsl
    │   ├── chunks
    │   │   ├── bsdf.glsl
    │   │   ├── envmap.glsl
    │   │   ├── intersect.glsl
    │   │   ├── random.glsl
    │   │   ├── sample.glsl
    │   │   ├── sampleGlassMicrofacet.glsl
    │   │   ├── sampleGlassSpecular.glsl
    │   │   ├── sampleMaterial.glsl
    │   │   ├── sampleShadowCatcher.glsl
    │   │   └── textureLinear.glsl
    │   ├── fullscreenQuad.vert
    │   ├── rayTrace.frag
    │   ├── reproject.frag
    │   └── toneMap.frag
    ├── glslUtil.js
    ├── mergeMeshesToGeometry.js
    ├── rgbeToFloat.js
    ├── texture
    │   ├── HDR_L_0.png
    │   ├── noise.js
    │   └── readme.txt
    ├── texturesFromMaterials.js
    ├── uploadBuffers.js
    └── util.js