Writing
HomeWritingDocumentation

Ascii3D


Version: 1.0Published: 14th February, 2020by Morgan

Introduction

Ascii3D is a text-based 3D rendering library for JavaScript. It borrows concepts from OpenGL, such as vertex buffers, index buffers, and the programmable shader pipeline.

Table of contents:


  1. Demo
  2. Using the library
  3. Render Buffer
  4. Vertex Buffer and Index Buffer
  5. Vertex Shader and Fragment Shader
  6. Draw Call
  7. Rendering to a 2D canvas
  8. Configuration
  9. Attribution
  10. Downloads

1. Demo



2. Using the library


Initialisation

The full library is contained within a single JavaScript file. To use it in your document, define a <script> element and refer to its URL in the "src" attribute.
  e.g. <script src="exampleDirectory/ascii-3d-v1.js"></script>

The library will initialisation automatically when the script is loaded.

Notes

The variable ascii3D will be declared globally.

3. Render Buffer


A render buffer is a Float32Array of character-codes, RGBA, and depth values. They also contain metadata like width and height. Data is rendered to a render buffer when making a draw call.
A render buffer can be returned by the ascii3D.createRenderBuffer function. For example: const width = 30, height = 30; const renderBuffer = ascii3D.createRenderBuffer(width,height);

4. Vertex Buffer and Index Buffer


A vertex buffer is an array of vertex attributes. Vertex attributes can contain arbitrary data, such as spacial information. In the example below, each vertex is composed of spacial data (X, Y), colour data (R, G, B), and a character code (CharCode). // Four vertices for a square const vertexBuffer = [ // X Y R G B CharCode -.5, -.5, 1.0, 1.0, 0.0, "#".charCodeAt(0), -.5, 0.5, 0.0, 1.0, 1.0, "#".charCodeAt(0), 0.5, 0.5, 1.0, 0.0, 1.0, "#".charCodeAt(0), 0.5, -.5, 1.0, 1.0, 0.0, "#".charCodeAt(0) ]
The renderer draws vertices in pairs of 3 (a triangle). An index buffer allows us to reuse vertices without storing repeated data in the vertex buffer. It does this by storing the index of vertices instead. const indexBuffer = [ 0,1,2, // triangle 1 0,2,3 // triangle 2 ]

5. Vertex Shader and Fragment Shader


The vertex shader converts vertex attributes to clip-space positions. The renderer invokes the shader for each vertex with its attributes as the function-parameter. The shader should output the clip-space position through ascii3D.position as a 4-component vector, and data for the fragment-shader through the return-statement. function vertexShader(Vertex) { let [X,Y,R,G,B,CharCode] = Vertex; // set position ascii3D.position = [X,Y,0,1]; // data to be outputted to fragment shader (interpolated) return [CharCode,R,G,B,1]; }
The fragment shader sets the character code and colour for each pixel based on interpolated data outputted by the vertex shader. The output should be a 5-component array with character code and RGBA values. function fragmentShader(In) { // output the input directly return In; }

6. Draw Call


To make a draw call, use the ascii3D.drawArray function. For example: ascii3D.drawArray( renderBuffer, // render buffer to write to ascii3D.triangle, // draw mode (only ascii3D.triangle supported at the moment) vertexShader, // vertex shader fragmentShader, // fragment shader vertices, // vertex buffer 6 // size of vertex (6 in our case for X,Y,R,G,B,CharCode) ); Alternatively, use ascii3D.drawElements when using an index buffer. For example: ascii3D.drawElements( renderBuffer, // render buffer to write to ascii3D.triangle, // draw mode (only ascii3D.triangle supported at the moment) vertexShader, // vertex shader fragmentShader, // fragment shader vertices, // vertex buffer indices, // index buffer 6 // size of vertex (6 in our case for X,Y,R,G,B,CharCode) );

7. Rendering to a 2D canvas


One way to display the render buffer is through an HTML canvas element. Ascii3D provides a function for this. ascii3D.renderToCanvas( ctx, // rendering context renderBuffer, // renderBuffer 16, // letter spacing 0, 0 // optional: start position (starting from bottom left) );

8. Configuration


Set ascii3D.doDepthTesting to true in order to enable depth testing.

9. Attribution


Special thanks to:

10. Downloads


License

All downloadable files can be used for commerical or non-commerical purposes. Do not resell. Attribution is appreciated but not due.

Files

Complete Library: ascii-3d-v1.js
Demo 1: demo1.html
Demo 2: demo2.html



All possible and potential rights reserved. Should you have any concerns, feel free to contact me at Heledron@gmail.com.
Heledron