
# Architecture

## Minnie
  - "setup helper"
  - create (sub-)paths, set renderstate, draw paths
  - parse .MIB
  - generate vertex buffer (VidRAM)
  - generate draw list (SysRAM)
  - used by MinnieVG API class

## ShaderVG
  o stores render state
     + transformation matrix
     + fill color
     + stroke width
     + stroke color
  o API methods and render classes/shaders for
     o draw op 0x01: filled flat triangles float32
     o draw op 0x02: filled flat triangles fix14:2
     o draw op 0x03: filled gouraud triangles float32
     o draw op 0x04: filled gouraud triangles fix14:2
     o draw op 0x05: filled flat edgeAA triangles float32
     o draw op 0x06: filled flat edgeAA triangles fix14:2
     o draw op 0x07: filled gouraud edgeAA triangles float32
     o draw op 0x08: filled gouraud edgeAA triangles fix14:2
     o draw op 0x09: filled (concave) flat n-polygons (stencil) float32
     o draw op 0x0A: filled (concave) flat n-polygons (stencil) fix14:2
     o draw op 0x0B: filled (concave) gouraud n-polygons (stencil) float32
     o draw op 0x0C: filled (concave) gouraud n-polygons (stencil) fix14:2
     + draw op 0x0D: filled rectangles
     + draw op 0x0E: stroked rectangles
     + draw op 0x0F: filled and stroked rectangles
     + draw op 0x10: filled ellipses
     + draw op 0x11: stroked ellipses
     + draw op 0x12: filled and stroked ellipses
     + draw op 0x13: filled round rectangles
     + draw op 0x14: stroked round rectangles
     + draw op 0x15: filled and stroked round rectangles
     ? blit  (vertex+uv array)
     ? blit global alpha
     ? colorblit global alpha
     - points
        - point shape  (round, diamond, rect, tri)

## MinnieDrawable
  + stores vertex buffer (VidRAM)
  + stores draw-list buffer (SysRAM)
  - stores 4x4 transformation matrix
  + draw() method parses draw-list and calls ShaderVG API

## MinnieVG
  - main API class
  - manage scratch buffer(s)
  - internal: create Minnie setup helper
  - convert Minnie setup to MinnieDrawable


# Draw List
- write render draw-list (to sysRAM)
   - setDrawListExportOFS(YAC_Object *_ofs)
   - draw-list ops
      - 0x00: end of draw-list
      - 0x01: draw triangles
          u32 vb_start_offset
          u32 num_triangles
          - combine successive triangle render commands
      - 0x02: draw concave triangles via stencil buffer
          u32 vb_start_offset
          u32 num_vertices
      - 0x03: draw triangles edgeAA
          u32 vb_start_offset
          u32 num_triangles
          - combine successive triangle render commands
      - 0x08: begin FB
          u32 gl_fb_id
          u16 w
          u16 h
      - 0x09: end FB
         - linear resolve blit
         ? u16 w
         ? u16 h
      - 0x20: set shadervg stroke w
      - 0x21: set shadervg stroke color
      - 0x22: set shadervg fill color
      - 0x23: set shadervg texture
          u32 gl_texture_id
      - 0x24: set texture matrix 2x3
          ! row major
      - 0x25: set texture matrix 4x4
          ! row major
      - 0x30: draw shadervg ellipsefill
      - 0x31: draw shadervg ellipsefillstroke
      - 0x32: draw shadervg ellipsestroke
      - 0x33: draw shadervg roundrectfill
      - 0x34: draw shadervg roundrectfillstroke
      - 0x35: draw shadervg roundrectstroke

------------------------------------------------------------------------------------

* TODO rect/ellipse/roundrect fill+stroke should (also/preferably) be merged in minnie compiler
   ! 30Aug2025
   ! currently only done in runtime

* DONE texture decal tests (test_api)
   ! 01Sep2025

* DONE beginPathImmediate() tests
   ! 01Sep2025
   ! C:02Sep2025
   + roundrect
   + rect
   + ellipse

* DONE add stroke width threshold option and auto-disable line joins
   ! 03Sep2025
   + setStrokeWLineJoinThreshold()

* DONE may later need to update Minnie C++ class to use static members and functions to reduce call overhead
   ! 03Sep2025
   ! C:04Sep2025
   ! C:05Sep2025
   ! C:06Sep2025
   ! which would make this a single-threaded / single-context API
      ! won't be able to setup multiple Drawables at once. but that's most likely not a use-case, anyway.
   ! e.g.
        int pid = d.beginPath();
        d.seg(64);
        d.moveTo(400, 300);
        d.ellipse(sx*0.5, sy*0.5);
        d.endPath(true/*bClosed*/);

        d.color(#ffffffff);
        d.strokeWidth(sin(anim_3)*2+3);
        d.joinBevel();
        d.drawPath(pid);
      =>
        int pid = minBeginPath();
        minSeg(64);
        minMoveTo(400, 300);
        minEllipse(sx*0.5, sy*0.5);
        minEndPath(true/*bClosed*/);

        minColor(#ffffffff);
        minStrokeWidth(sin(anim_3)*2+3);
        minJoinBevel();
        minDrawPath(pid);
   + maybe better to change this sooner than later

* DONE rename PathHoles => PathEvenOdd
   ! 04Sep2025

* TEST tkminnie_shared.h/.cpp
   ! 11Sep2025
   ! similar to OpenGL
   ! export minnie+shadervg functions to other plugins (e.g. tksampleedit)

* DONT polygon_fill_gouraud: use vertex attrib divisor for color
   ! 24Sep2025
   ! set to #numVerts (i.e. once per polygon)
   - remove this entirely and use polygon_fill_flat instead

* DONT minLinePattern(short _pattern, float _patternScale)
   ! 26Sep2025

* DONE minLinePatternOffset(float _patternOffset)
   ! 26Sep2025
   ! C:24Mar2026
   + add to draw-list

* DONE minLinePatternScale(float _patternScale)
   ! 26Sep2025
   ! C:24Mar2026
   + add to draw-list

* DONT minSolidPaint()
   ! 26Sep2025
   ? minPaintSolid()
      ! it's also called 'sdvg_PaintSolid()'
   ! ==> minPaintSolid()

* DONT minGradientStopsToTexture(Texture _targetTex, IntArray _gradientStops)
   ! 26Sep2025
   ! C:28Sep2025
   - adapt from Graph gradients
      ! normalize gradient stop positions
      ! lerp between colors and store in Texture
   + ==> 28Sep2025: add sdvg_GradientToTexture()

* DONT minLinearGradientPaint(Texture gradientColors, float _startX, float _startY, float _endX, float _endY)
   ! 26Sep2025
   ! https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/linear-gradient
   ? minPaintLinear() ?
   ! ==> minPaintLinear()

* DONT minRadialGradientPaint(Texture gradientColors, float _centerX, float _centerY, float _radiusX, float _radiusY)
   ! 26Sep2025
   ! https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/radial-gradient
   - add TrianglesFillLinearGradient32
   - add PolygonFillLinearGradient32
   + ==> minPaintRadial()

* DONT minConicGradientPaint(Texture gradientColors, float _centerX, float _centerY, float _radiusX, float _radiusY, float _rotation)
   ! 26Sep2025
   ! https://developer.mozilla.org/en-US/docs/Web/CSS/gradient/conic-gradient
   - add TrianglesFillConicGradient32
   - add PolygonFillConicGradient32
   + ==> minPaintConic()

* DONE non-zero polygons
   ! 26Sep2025
   + tks-examples/tksdl/stencil_polygons.tks

* TODO minQuadricTo
   ! 26Sep2025

* TODO minQuadricMirrorTo
   ! 26Sep2025

* DONE add native 'test_mib.c' test case
   ! 26Nov2025
   ! C:21Feb2026
   ! (note) MinnieDrawable already supports native build

* DONE add C wrapper for MinnieDrawable
   ! 26Nov2025
   ! C:20Feb2026

* DONE add native 'test_min.cpp' test case
   ! 26Nov2025
   ! C:21Feb2026

* IDEA add optional support for TLS in native build
   ! 26Nov2025
   - prefix local vars
   - for multithreaded creation of MinnieDrawables

* DONE add minDrawList(gl_buf_id, YAC_Buffer *_drawBuf)
   ! 04Dec2025
   - move from MinnieDrawable utility class to C API
   + minnie_exec.h: minExecDrawListEx(), minExecDrawList()

* IDEA MinnieDrawable.h/.cpp: write to mapped buffer (instead of copying system RAM)
   ! 19Feb2026

* DONE b_force_evenodd_concave: join sub paths / split stencil fill and bbox color fill
   ! 21Feb2026
   ! i.e. render all subpaths to stencil, then fill color buffer
   ! need new draw-op
      ! ==> MINNIE_DRAWOP_POLYGON_FILL_FLAT_UNIFORM_*_BEGIN/SUB/END

* DONE support sdvg miter line strips
   ! 23Feb2026
   ! C:27Feb2026
   ! C:28Feb2026
   + add new draw ops
   ! stroke_w_line_strip_threshold
   ! beginDrawListOpLineStrip()
   ! drawPathLineStrip(), drawPathLineStripClipPre(), drawPathLineStripTransform2d(), drawPathLineStripTransform2dClipPre()

* DONE round line joins (via round points)
   ! 27Feb2026

* ACTV draw line caps
   ! 27Feb2026
   ! C:25Mar2026
   ! C:27Mar2026
   + when line strip is not closed
   + round: draw two round points
   o square: draw linewidth/2 rectaa
      + tesselated
      - shadervg
         ? draw line-strip ?
   + line patterns

* DONE fix open polylines (bevel+miter joins)
   ! 28Feb2026

* TEST set both fill and stroke color in draw op when paint mode is DECAL
   ! 15Mar2026
   + problem: Minnie API currently only has single minColor()
      ! used as fill or stroke depending on draw op

* DONE MINNIE_DRAWOP_TRIANGLES_TEX_UV_FLAT_DECAL_32 is missing stroke color
   ! 15Mar2026

* DONE add minColorFill(), minColorStroke()
   ! 15Mar2026

* DONE add extra vertex to linestrip-antialiased polygon (for bevel line joints)
   ! 17Mar2026
   ! C:20Mar2026

* DONE add minAARange()
   ! 18Mar2026
   + remove aa_range from other draw ops

* DONE rename minPaintBegin() to minPaintCreate()
   ! 18Mar2026

* DONE add minPaintUpdate()
   ! 18Mar2026

* IDEA use polygons for drawing wide lines / arcs
   ! 18Mar2026
   ! e.g. min test 26
   ! open polylines: could also tesselate tris and draw outline

* DONE test_min: add benchmark mode
   ! 18Mar2026
   + skip clear
   + draw 'n' iterations per frame

* DONE test_min TC27: count mpix/sec
   ! 18Mar2026
   ! => 0.23 mpix in first frame

* TODO apply Dsdvg_pixel_scl to roundrect/.. prims
   ! 20Mar2026
   ? same for sdvg_SetStrokeScale() ?

* ACTV add/use paint points shaders for line joins and caps
   ! 21Mar2026
   + PointsRoundAA*<paint>
   - square caps

* DONE support line patterns
   ! 21Mar2026
   ! C:24Mar2026
   ! use LineStripPatternBevelAA*32 shaders
   + minLinePattern(sUI _patternBits, sUI _patternLen)
      + use fixed pattern size 112 ?
      + patternLen: 7,8,14,16,28,32   (0=>16)
      ? add texture cache (8 entries?)
   + minLinePatternScale(sF32 _scale)
      + sdvg_SetLinePatternScale(1.0f/(_scale * pattern_size))
   + minLinePatternOffset(sF32 _offset)
      ! post scale
      ! 0..1
   + test cases (min 32+33)

* DONE add minFillRuleNonZero(); minFillRuleEvenOdd()
   ! 21Mar2026
   + add draw ops

* DONE add fillrule op to MIB format
   ! 21Mar2026
   ! C:22Mar2026
   x add 'pn' (non-zero) path type ?
   + 0x0F eo=0 / nz=1

* DONE support anti-aliased convex polygons (b_polygon_aa)
   ! 21Mar2026
   ! C:22Mar2026
   + redirect convex to concave
   + mib test 61_man: half of the points disappears (when redirected)
      ! #drawops also increases from 620 to 1650 in case of error
      ! ok:
         [trc] minExecDrawList: [ 619] draw-list off=14237 op=2
         [trc] minExecDrawList: draw-triangles-fill-flat-uniform<s14.2>-paint: vbOff=30452 numVerts=68079
      ! nok
         [trc] minExecDrawList: [1647] draw-list off=32741 op=14
         [trc] minExecDrawList: draw-polygon-fill-flat-aa<s14.2>: vbOff=88020 numVerts=14 c32Fill=#ff000000
         [trc] minExecDrawList: [1648] draw-list off=32759 op=14
         [trc] minExecDrawList: draw-polygon-fill-flat-aa<s14.2>: vbOff=88076 numVerts=0 c32Fill=#00000000
         [trc] minExecDrawList: [1649] draw-list off=32765 op=14
         [trc] minExecDrawList: draw-polygon-fill-flat-aa<s14.2>: vbOff=0 numVerts=0 c32Fill=#00000000
      + ==> displaylist buffer was too small

* DONE add YAC_NATIVE_WARN_BUFFER_OOB build option
   ! 22Mar2026

* TODO recreate line pattern tex in onOpen() (minnie_exec)
   ! 24Mar2026

* DONE line pattern decal mode
   ! 24Mar2026
   ! C:27Mar2026
   + add "bDecal" arg to minLinePattern()
      + add to flags (MINNIE_DRAWOP_LINE_STRIP_FLAG_DECAL)
   + extend drawops for
      + LineStripPatternDecalAA32
      + LineStripPatternDecalAA14_2
      + LineStripPatternDecalBevelAA32
      + LineStripPatternDecalBevelAA14_2
   + add PointsRoundPatternDecalAA32
   + add PointsRoundPatternDecalAA14_2
   + tests 34+35

* DONE line pattern round caps and joints
   ! 24Mar2026
   ! C:26Mar2026
   + caps: need direction
      + plane: orthogonal to line direction. point on plane: line start / end
         + untransformed
         + pass current+next vertex
            x need two vboOff params (prev/next is swapped for first vertex)
               + OR: add extra vertices to VBO (after last)
                  + calc delta between 1st and 2nd vertex and unitScale by stroke radius
   x joints: need two direction (lerp?)

* DONE must render open round line caps in line_strip_bevel mode to fix occasional gap before end cap
   ! 27Mar2026

* TEST optimize stroked polygon fill
   ! 29Mar2026
   ! no need to draw AA outline around polygon when stroke is rendered on top
   ? how to detect/solve this ?
      ! stroke settings (pattern, paint, ..) and whether there's a stroked path to begin with, is unknown when path is filled
      x solution 1) address this in application (it may have its own Path class with filled+stroked flags)
      x solution 2) add minDrawPathNoAA(int pathId)
      x solution 3) postpone fill calls until next draw call (or minEnd())
         - remember active_dl_paint_id
         - remember active_dl_c32_fill
      + solution 4) fix up draw-list
         + remember last polygon AA path id (last_polygon_aa_path_id)
         + remember location of last polygon AA draw call (last_polygon_aa_dl_offset)
         + AA draw-op must follow non-AA draw-op (re-enumerate)
         + change AA draw-op to non-AA draw-op when stroke draw refers to same path and no line-pattern is used
         + invalidate last_polygon_aa_path_id when path is redefined / freed

* DONE add minFreePath(int pathId)
   ! 29Mar2026
   + call path->free()
   + allow path to be reallocated (newPath / minBeginPath*())
   + fix path enumeration (Path::path_idx 2..n => Path::path_id (1..n))

* TEST drawable.drawTinted(int _tint32Fill, int _tint32Stroke)
   ! 05Apr2026
   ! e.g. test_37

* ACTV tesselated stroke uses fill color
   ! 05Apr2026
   + should use stroke color in draw-list (and be tinted by tint32Stroke)
   + add DRAWOP_TRIANGLES_STROKE_FLAT_UNIFORM_*
   - also make this work with vertex colors
      - tint color in vertex shader

* TODO SW-tesselated lines have tie breaking issues
   ! 05Apr2026
   ! see test_37

* NOTE ffmpeg -framerate 30 -i frame_%05d.png -c:v libx264 -r 30 -pix_fmt yuv420p -preset slow -crf 17 output.mp4
   ! 05Apr2026

* NOTE ffmpeg -i input.mp4 -c:v libvpx-vp9 -quality best -crf 30 -b:v 0 output.webm
   ! 07Apr2026
