g3d¶

the C wireframe-3D library (//#use g3d)
NAME
    g3d - the C wireframe-3D library (//#use g3d)

SYNOPSIS
    //#use gfx
    //#use g3d          in that order (g3d draws through gfx)

DESCRIPTION
    Wireframe 3D: describe a world as edges between 16-bit (x,y,z) points,
    choose a window (what you look at) and a viewport (where on screen it
    lands), and render. World axes: x right, y UP, z into the screen,
    camera at the origin looking down +z. Keep coordinates within about
    +/-16000. Black and white: the render erases its viewport to black and
    draws white lines.

    The SAME program runs two ways, fastest fitted path chosen at
    runtime: all in software, or with the MDU (the hardware multiply-
    divide unit) accelerating the arithmetic. For hardware-rendered 3D
    the machine now speaks a GRAPHICS LANGUAGE instead -- man gl.

BUILDING AND RENDERING A WORLD
    g3clear()                        empty the record pool
    g3color(c)                       pool pen: records added after this
                                     carry colour c (white by default)
    g3line(x0,y0,z0, x1,y1,z1)       add one coloured edge
    g3tri(p, fill)                   add a triangle: p = int[9], three
                                     x,y,z corners; fill 0/1 (an N-gon
                                     is a fan of these)
    g3window(wx0,wy0,wx1,wy1)        view-plane rectangle to look at
    g3view(vx0,vy0,vx1,vy1)          screen rectangle to draw into --
                                     also a true CLIP rectangle, so
                                     viewports can sit side by side
    g3persp(d)                       focal length; 0 = orthographic
                                     (d=256: a point at z=256 maps 1:1)
    g3render()                       erase the viewport, draw the pool
                                     (the software walk).

THE HARDWARE PATH (stage 10: the GL engine)
    The record engine this section once described (g3up/g3mat/g3go and
    the $FF40 registers) is RETIRED: g3probe() now finds nothing and
    g3render() always walks in software. The hardware 3D path is the
    GRAPHICS LANGUAGE -- a PGC-style command port at $FF50 that holds
    the matrices, windows, clips, projects and draws in fabric. See
    man gl for the port and the verbs; tri and page already speak it.

    muldiv(a,b,c)         the library's arithmetic core, usable directly:
                          (a*b)/c signed via a 32-bit intermediate,
                          truncated toward zero, saturating at +/-32767.
                          Routed through the MDU when one is fitted.

EXAMPLE (draw a triangle)
    //#use gfx
    //#use g3d
    ... build pool with g3line/g3tri, set window/view/persp ...
    g3render();                      /* erase + software walk */

NOTES
    Sources: /lib/lib_g3d.c on this disk. The design and the measured
    numbers live in the repo: fpga/tang-nano-20k/sdram/STAGE7-DESIGN.md,
    STAGE8-DESIGN.md and STAGE8B-DESIGN.md. `cube` is the worked example.

SEE ALSO
    gfx, cube, basic