# Graphics drawing

## Terminology
Texture - a set of bytes on the GPU, not directly accessible
Surface - a set of bytes in RAM, modifiable
rect - a rectangle of {x,y,width,height}
Image - combination of a texture and rect, where the rect defines the UV coordinates on the texture to draw

# Drawing, cameras, viewports, logical size, and so on

A camera is a view into the game world. A camera can be "rendered", which means it renders the world, and what it can see in the world. A camera may draw to a surface, or to the main window. Objects in the world will render so that if their position is equal to the camera position, that is in the center of the screen. HUD functions always render so [0,0] is the bottom left of the camera's view.

Cameras always draw to their own render target. Then, they draw that render target to the framebuffer.

# COORDINATES
Screen coordinates start in the upper left corner at [0,0] and extend to the bottom right, in pixels. Raw mouse coordinates are in these.

# RENDERING PIPELINE

In prosperon, you call graphics rendering functions at well defined hook points. These are interleaved as necessary with predefined created objects, like sprites, 3d world models, and so on.

The engine stores a command buffer. When you issue "draw" commands, they are recorded into the command buffer. These are batched as much as they can be; if there is no significant state change between, the draw commands can be coalesced into one. Then, for each camera, the draw commands are executed.

# RENDERING COMPONENTS
## MATERIALS
A material defines the inputs to a shader.

## PIPELINES
Pipelines are how the rendering engine is set up. Switching pipelines can be done for special effects.

## SPECIAL EFFECTS
Sometimes you want a special effect. While there are many objects in prosperon you can create and have the engine handle for you, a special effect typically requires a bit of code.

# LAYERS
All things that draw have a layer. If no layer is set, the implicit layer is "0". Even draw and hud functions have a layer. To draw a draw function on a specific layer, set that function's "layer". ie,

this.draw = function() { render.rect(); }
this.draw.layer = -5;

Now that layer will draw at the -5 layer.

# CAMERAS
Everything is drawn via cameras. Cameras can draw directly to the screen, or they can draw to an offscreen render target. By default, everything is drawn to all cameras. There will eventually be a tag that lets you filter what is drawn to specifc cameras.

Cameras have a resolution they draw at, "size".

## TEXTURES

Anatomy of rendpering an image render.image(path)
Path can be a file like "toad"
If this is a gif, this would display the entire range of the animation
It can be a frame of animation, like "frog.0"
If it's an aseprite, it can have multiple animations, like "frog.walk.0"
                                                          file^ frame^ idx

render.image("frog.walk.0",
game.image("frog.walk.0") ==> retrieve

  image = {
    texture: "spritesheet.png",
    rect: [x,y,w,h],
    time: 100 
  },

    frames: {
      toad: {
        x: 4,
        y: 5,
        w: 10,
        h: 10
      },
      frog: {
      
        walk: [
          { texture: spritesheet.png, x: 10, y:10, w:6,h:6, time: 100 },
          { texture: spritesheet.png, x:16,y:10,w:6,h:6,time:100}       <--- two frame walk animation
        ],
      },
    },
  }
  texture frog {
    texture: {"frog.png"}, <--- this is the actual thing to send to the gpu
    x:0,
    y:0,
    w:10,
    h:10
  },


## RENDER MODES
/* rendering modes
   ps1
     gouraud
     diffuse // 16 bit color, 5-5-5
     7 dynamic lights, 1 ambient
     textures are affine
     no vertex skinning
     256x256 texture max (generally 128x128)
     320x240, variable up to 640x480

   n64
     gouraud
     diffuse
     combiner // a secondary texture sometimes used to combine
     7 dynamic lights, 1 ambient
     320x240, or 640x480

   sega saturn
     gouraud
     diffuse
     320x240 or 640x480

   ps2
     phong
     diffuse
     combiner // second texture for modulation of diffuse
     combine_mode // int for how to combine

   dreamcast
     phong
     diffuse
     combiner // second texture; could be an environment map, or emboss bump mapping
     fog
     640x480
     640x448, special mode to 1280x1024

   gamecube
     phong
     diffuse
     +7 textures // wow!
     8 dynamic lights
     640x480

*/

/* meshes
   position (float3)
   color (rgba)
   uv
*/

/* materials, modern pbr
   any object can act as a "material". The engine expects some standardized things:
   diffuse - base color texture
   bump - a normal map for dot3 bump maping used in phong shading
   height - a grayscale heightmap
   occlusion - ambient occlusion texture
   emission - texture for where model emits light
   bump2 - a second normal map for detail
   metallic - a metal/smoothness map
   specular - specular map, alternative for the metallic workflow
*/
