From c35fc21f345ac9ecf9017115c4481a1147d05206 Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Wed, 4 Nov 2026 21:35:44 +0100
Subject: Chams: real additive material, addref cached materials

Testing on :99 showed ADDITIVE on debugtranslucentsinglecolor did nothing and
alpha lost the colour, because that VMT has no $translucent and the engine
bound an unreferenced material. Use debug/debugtranslucentmodelhulls (VMT has
$additive 1 + $color) for Additive/Fullbright, and addref every preloaded
material so the engine stops warning "bad reference count 0" and applies
$color/ColorModulate. Verified: Solid is flat blue, Additive is a translucent
coloured glow, Fullbright is a white additive glow, White is opaque white.

Also drop the viewmodel additive base (the solid material is opaque, so it
made an opaque blob) and never call FindMaterial inside DrawModelExecute.
Document that the alpha control is stored but has no effect until a custom
$translucent model VMT is added.
---
 CONTEXT.md | 41 ++++++++++++++++++++++++-----------------
 1 file changed, 24 insertions(+), 17 deletions(-)

(limited to 'CONTEXT.md')

diff --git a/CONTEXT.md b/CONTEXT.md
index bfb0d8e..5b96c33 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -294,31 +294,38 @@ vocabulary / decisions.
   alpha only. The through-wall pass uses `MATERIAL_VAR_IGNOREZ` (1 << 15)
   through `IMaterial::SetMaterialVarFlag` (slot 29); colours use
   `$color`/`$color2` (IMaterialVar slot 11, SetVecValue 3-float slot 11) and
-  `ColorModulate` (slot 28). Alpha uses `$alpha` (IMaterialVar slot 3,
-  SetFloatValue) and `MATERIAL_VAR_TRANSLUCENT` (1 << 21) when alpha < 255.
-  Shared materials are restored after each draw.
+  `ColorModulate` (slot 28). `$alpha` is set through IMaterialVar slot 3
+  (SetFloatValue). Shared materials are restored after each draw.
 - The GUI colour picker (`add_color_alpha`) has an alpha bar, checkerboard
   preview and `#RRGGBBAA` readout; plain `add_color` keeps the old opaque
   three-component behaviour. Chams colours are four ints (r, g, b, a).
-- Styles are built from `debug/debugtranslucentsinglecolor` (UnlitGeneric,
-  `$color`) and material flags:
-  0 Flat (solid + FLAT), 1 Wireframe (`debug/debugwireframe`), 2 Additive
-  (+ ADDITIVE), 3 Solid, 4 White (colour forced white), 5 Fullbright
-  (ADDITIVE|SELFILLUM, colour forced white so it reads as a white-hot glow
-  instead of matching Solid), 6 Glow outline
-  (solid plus a `debug/debugwireframe` contour pass drawn with ZNEARER
-  (1 << 10) and a brightened colour so the base cannot bury it).
+- **Alpha is stored but has no visual effect yet.** The usable model
+  materials are opaque: `debug/debugtranslucentsinglecolor` has no
+  `$translucent`, and toggling `MATERIAL_VAR_TRANSLUCENT` (1 << 21) or
+  rebuilding the state snapshot does not change the static shader combo.
+  `debug/debugtranslucentvertexcolor`/`debug/debughitbox` are translucent but
+  need vertex colours and render nothing on skinned models. A custom VMT with
+  `$model 1` + `$translucent 1` (or a white basetexture) is needed to make the
+  alpha control real.
+- Styles: 0 Flat (`debug/debugtranslucentsinglecolor` + FLAT), 1 Wireframe
+  (`debug/debugwireframe`), 2 Additive
+  (`debug/debugtranslucentmodelhulls`, whose VMT has `$additive 1` + `$color`;
+  the ADDITIVE flag on the solid material did nothing), 3 Solid, 4 White
+  (solid, colour forced white), 5 Fullbright (the additive material, colour
+  forced white, giving a white-hot glow), 6 Glow outline (solid plus a
+  `debug/debugwireframe` contour pass drawn with ZNEARER (1 << 10) and a
+  brightened colour so the base cannot bury it).
   `vgui/white` is vertex-colour based and has no `$model`/`$basetexture`, so it
   is never used for chams; `models/debug/debugwhite` is EP2-only and the old
   VGUI additive material was invisible on NPCs.
 - Style materials are preloaded from `outer_draw` (throttled) and cached; the
   render hook never calls FindMaterial itself. A missing style uses solid.
-- Viewmodels are collated by the engine as `RENDER_GROUP_VIEW_MODEL_OPAQUE`,
-  so an additive forced material can wash out against a bright sky or wall
-  (and the engine may not treat the draw as translucent). Additive styles on
-  the viewmodel therefore draw a faint translucent base (alpha/8) first, then
-  the additive pass, so the model keeps a silhouette on bright backgrounds
-  without becoming an opaque blob.
+  `FindMaterial` can return an unreferenced material, so each cached material
+  is addref'd (`IncrementReferenceCount`, IMaterial slot 12); without this the
+  engine warns "bad reference count 0 when being bound" and the material's
+  `$color`/`ColorModulate` changes are ignored.
+- Additive styles still wash out against a bright sky or wall (inherent to
+  additive blending).
 - Feature is off by default. Config sections: `[chams]` (active/bind),
   `[chams_hostile|neutral|friendly]` (`vis`, `vis_mat`, `vis_r/g/b/a`, `inv`,
   `inv_mat`, `inv_r/g/b/a`) and `[chams_vm]` (`on`, `mat`, `r/g/b/a`). The GUI
-- 
cgit v1.2.3