XChart 图表框架落地(P0–P17):格线单一作者、面板一行状态、矢量场

此前整个 XChart 特性一直没有提交(分期 P0–P12 的代码与素材都还在工作区里)。这一批一并入库,
并含本轮 P13–P17 的改动(规范 Documentation/XChart-RenderFramework.md 新增 §22–§25):

- P13:格线只剩一个作者——线框工具不再有"画格线 / 发布格线插槽"的代码路径;BG Cube Grid(原 MeshBg)
  是唯一作者,且"画上去的线=发布给轴线的那份比例数组";插槽板新增 Unpublish(说得出"这里不再有线",
  否则掩码筛掉的面会把上一轮的值留着被消费者吸走);渲染参数搬进元素表
  (DeclareDefaultElements / AddDefaultElement + XChartElementTable 按类型去重,只在第一次读到表时补);
  图上「立方体外观」那组字段删除、公共属性转发到元素表;面板逐行点名脚本注册的工具。
- P14 / P15:数据窗口文案收敛(行末 `-`、标题 `X [0]`、长说明退回 tooltip、范围页三行不再被压扁);
  元素块收成一行状态 `▼ 名称 √ R… D… [↑][↓][-]`;**注册序由类型定死、只显示不给输入控件,
  绘制序与元素在表里的位置绑定**(§24.5,他 2026-10-25 澄清);默认元素让删也让关;
  EnsureSpace 改成每次重建后都跑(删掉"空间"不再等于整张图空掉)。
- P17:矢量场——维数不够时不再静默不画(元素配置报需求,面板与报表同时印"需求/现有");
  相对/绝对两种读法收进纯算术 XChartVectorFieldMath;连续绘制(互斥显示把"相对/绝对"藏起来);
  颜色维(色相走 0..256 色环,饱和/明度/不透明 0..1,不透明度不算硬需求);新增螺旋矢量场测试数据。
  数据口径按他澄清修正为:前三维=坐标、一支箭头=相邻两条记录、第 4~7 维是颜色(§25、CHANGELOG 修正行)。

判据:编译门三臂 + 3 支对照绿;离线探针 436 项 0 失败;p4_control 55 支臂各红在自己点名的断言上;
p2_control / pool_family / generator_gate / hierarchy_gate 在同一棵交付树上复跑。
(证据脚本与日志在包外的 .ximage-gate/,未入本仓库。)
This commit is contained in:
2026-10-25 20:21:28 +08:00
parent 216d157472
commit c51ab7a3c8
105 changed files with 13062 additions and 812 deletions
@@ -0,0 +1,38 @@
namespace XericUI.XChart.Pools
{
/// <summary>
/// 槽位工厂。<b>池的调度器只认这一个接口</b>,所以调度算法是纯托管的,能在离线探针里
/// 用假工厂跑(规范 <c>Documentation/XChart-RenderFramework.md</c> §5.3)。
///
/// <para><c>host</c> 对调度器是透明引用,只有实现认识它(运行时里是标签宿主 RectTransform)。
/// 把 host 交给 <see cref="Assign"/> 与 <see cref="IsUsable"/>,是为了让"挂在哪"成为有效性判据
/// 的一部分:父节点不对就是被人挪走了(或者宿主节点随域重载没了),必须丢弃重补,
/// 而不是继续画在一个来历不明的位置。</para>
/// </summary>
public interface IXChartSlotFactory<TSlot>
{
/// <summary>
/// 取一个可用槽位:工厂自己的空闲表里有就复用,没有就新建(新建件的 hideFlags 由实现负责)。
/// 给不出来就返回 null——调度器会保持该 owner 为脏,下一帧再试,不会静默少画。
/// </summary>
TSlot Acquire();
/// <summary>
/// 真正归还:停用并放回工厂的空闲表。
/// <b>只在顺位复用之后还有剩余时调用</b>——抽出来的槽位默认先在本帧回收队列里等别人认领。
/// </summary>
void Release(TSlot slot);
/// <summary>发落给某个 owner:挂到 host 下并置为激活</summary>
void Assign(TSlot slot, object host);
/// <summary>§5.3 的合取判据:任一条件不满足就返回 false(调度器随即丢弃它并补新的)</summary>
bool IsUsable(TSlot slot, object host);
/// <summary>
/// 硬销毁池的一切(<c>chart.RebuildAll()</c> 与调试菜单走这一条)。
/// 调度器只管列表,只有实现知道"件"是什么、池根挂在哪——所以销毁也归它。
/// </summary>
void DestroyAll();
}
}
@@ -0,0 +1,11 @@
fileFormatVersion: 2
guid: 3deb2549fc4a3a34c82df3712c373398
MonoImporter:
externalObjects: {}
serializedVersion: 2
defaultReferences: []
executionOrder: 0
icon: {instanceID: 0}
userData:
assetBundleName:
assetBundleVariant:
+247
View File
@@ -0,0 +1,247 @@
using System.Collections.Generic;
namespace XericUI.XChart.Pools
{
/// <summary>
/// 槽位池调度器(规范 §5.1/§5.2/§5.3)。
///
/// <para><b>纯托管、不引用 UnityEngine</b>:调度是唯一一份实现,判据靠假工厂在离线探针里跑,
/// 不需要编辑器在场也能证明"先释放、顺位优先、池兜底"这套顺序真的在生效。</para>
///
/// <para>申请单位是<b>一批</b>:<see cref="Request"/> 只把 owner 标脏,分配一律推迟到
/// <see cref="Dispatch"/>。每个 owner 的列表被<b>整份换回</b>(换新列表实例,不原地改长度),
/// 所以调用方拿到的旧引用不会被人悄悄改短。</para>
/// </summary>
public sealed class XChartSlotPool<TSlot>
{
private sealed class OwnerRecord
{
public int Index;
public object Host;
public int Requested;
public bool Dirty;
public List<TSlot> Slots = new List<TSlot>();
}
private readonly IXChartSlotFactory<TSlot> m_Factory;
/// <summary>注册顺序就是次级排序键:申请数相同时先注册者顺位在前,调度可重放</summary>
private readonly List<OwnerRecord> m_Order = new List<OwnerRecord>();
private readonly Dictionary<object, OwnerRecord> m_Lookup = new Dictionary<object, OwnerRecord>();
private readonly List<OwnerRecord> m_Round = new List<OwnerRecord>();
private readonly List<TSlot> m_Recycle = new List<TSlot>();
private static readonly IReadOnlyList<TSlot> k_Empty = new TSlot[0];
private int m_DirtyCount;
// ── 计数器:都是累计值,探针取两次快照的差来判决 ──────────────
public int DispatchCount { get; private set; }
/// <summary>从本帧回收队列里顺位取用的次数(不是向工厂要的)</summary>
public int ReuseCount { get; private set; }
/// <summary>向工厂 Acquire 的次数(池兜底 + 新建)</summary>
public int AcquireCount { get; private set; }
/// <summary>真正归还工厂的次数(只等于回收队列的剩余)</summary>
public int ReleaseCount { get; private set; }
/// <summary>§5.3 校验丢弃的槽位数(域重载、宿主重建都会在这里露头)</summary>
public int DroppedCount { get; private set; }
public int OwnerCount => m_Order.Count;
/// <summary>调度收敛了没有:为 false 说明还有 owner 在等件(工厂给不出或宿主没就绪)</summary>
public bool IsIdle => m_DirtyCount == 0;
public XChartSlotPool(IXChartSlotFactory<TSlot> factory)
{
m_Factory = factory;
}
/// <summary>
/// 登记一批需求(<paramref name="count"/> 是本帧要用的总数,不是增量)。只置脏,不分配。
/// <paramref name="host"/> 变了也要重排——域重载后宿主是新实例,旧槽位的父节点就对不上了。
/// </summary>
public void Request(object owner, object host, int count)
{
if (owner == null) return;
if (count < 0) count = 0;
OwnerRecord record;
if (!m_Lookup.TryGetValue(owner, out record))
{
record = new OwnerRecord { Index = m_Order.Count };
m_Lookup[owner] = record;
m_Order.Add(record);
}
if (record.Requested == count && ReferenceEquals(record.Host, host) && !record.Dirty) return;
record.Requested = count;
record.Host = host;
MarkDirty(record);
}
public void Forget(object owner)
{
if (owner == null) return;
OwnerRecord record;
if (!m_Lookup.TryGetValue(owner, out record)) return;
m_Lookup.Remove(owner);
m_Order.Remove(record);
// 它手上的件全数归还池,不然这些实例就没人认领了
for (int i = 0; i < record.Slots.Count; i++)
{
m_Factory.Release(record.Slots[i]);
ReleaseCount++;
}
record.Slots.Clear();
if (record.Dirty)
{
record.Dirty = false;
m_DirtyCount--;
}
}
/// <summary>owner 当前持有的槽位(长度就是已发落的数量,申请数看 <see cref="RequestedCount"/>)</summary>
public IReadOnlyList<TSlot> SlotsOf(object owner)
{
OwnerRecord record;
return m_Lookup.TryGetValue(owner, out record) ? record.Slots : k_Empty;
}
public int RequestedCount(object owner)
{
OwnerRecord record;
return m_Lookup.TryGetValue(owner, out record) ? record.Requested : 0;
}
public int HeldCount(object owner)
{
OwnerRecord record;
return m_Lookup.TryGetValue(owner, out record) ? record.Slots.Count : 0;
}
/// <summary>
/// 一次调度:校验 → 排序 → 先释放 → 再补充(顺位优先,池兜底)→ 盈余才归还 → 换回列表。
/// 返回本次是否真的动过(没脏也没丢弃时是 O(槽位总数) 的一次校验而已)。
/// </summary>
public bool Dispatch()
{
DispatchCount++;
// 0) 有效性校验:每次调度都做,不只对脏 owner(§5.3)
for (int i = 0; i < m_Order.Count; i++)
{
OwnerRecord record = m_Order[i];
int held = record.Slots.Count;
if (held == 0) continue;
int kept = 0;
for (int s = 0; s < held; s++)
{
TSlot slot = record.Slots[s];
if (m_Factory.IsUsable(slot, record.Host)) record.Slots[kept++] = slot;
else DroppedCount++;
}
if (kept == held) continue;
record.Slots.RemoveRange(kept, held - kept);
MarkDirty(record);
}
// 1) 脏 owner 按申请数从大到小排序,让先申请者顺位拿到回收件
m_Round.Clear();
for (int i = 0; i < m_Order.Count; i++)
{
OwnerRecord record = m_Order[i];
if (!record.Dirty) continue;
// 宿主还没就绪又要点件:这轮整个跳过,脏着下一帧再试(不然会反复造出无主的件)
if (record.Host == null && record.Requested > 0) continue;
m_Round.Add(record);
}
if (m_Round.Count == 0) return false;
m_Round.Sort(CompareByRequestDescending);
// 2) 先处理释放:多出来的抽进本帧回收队列——这一步还不还池
m_Recycle.Clear();
for (int i = 0; i < m_Round.Count; i++)
{
OwnerRecord record = m_Round[i];
int keep = record.Requested;
if (record.Slots.Count <= keep) continue;
for (int s = keep; s < record.Slots.Count; s++) m_Recycle.Add(record.Slots[s]);
record.Slots.RemoveRange(keep, record.Slots.Count - keep);
}
// 3) 再补充:先吃回收队列(顺位复用),队列空了才向工厂要
for (int i = 0; i < m_Round.Count; i++)
{
OwnerRecord record = m_Round[i];
var next = new List<TSlot>(record.Slots);
while (next.Count < record.Requested)
{
TSlot slot;
if (m_Recycle.Count > 0)
{
slot = m_Recycle[m_Recycle.Count - 1];
m_Recycle.RemoveAt(m_Recycle.Count - 1);
ReuseCount++;
}
else
{
slot = m_Factory.Acquire();
AcquireCount++;
}
if (slot == null) break;
m_Factory.Assign(slot, record.Host);
next.Add(slot);
}
record.Slots = next;
ClearDirty(record);
// 工厂给不出(宿主没了、创建被挡)就保持脏,下一帧重试——不静默少画
if (next.Count < record.Requested) MarkDirty(record);
}
// 4) 回收队列的剩余才是真正归还
for (int i = 0; i < m_Recycle.Count; i++)
{
m_Factory.Release(m_Recycle[i]);
ReleaseCount++;
}
m_Recycle.Clear();
return true;
}
/// <summary>
/// 拆池:清空全部 owner 记录,再把"件"的销毁交给工厂。
/// <b>列表在这里没意义</b>——件是别人(GameObject)造的,只有实现知道怎么硬销毁。
/// </summary>
public void Dispose()
{
m_Lookup.Clear();
m_Order.Clear();
m_Round.Clear();
m_Recycle.Clear();
m_DirtyCount = 0;
m_Factory.DestroyAll();
}
private int CompareByRequestDescending(OwnerRecord a, OwnerRecord b)
{
if (a.Requested != b.Requested) return b.Requested.CompareTo(a.Requested);
return a.Index.CompareTo(b.Index);
}
private void MarkDirty(OwnerRecord record)
{
if (record.Dirty) return;
record.Dirty = true;
m_DirtyCount++;
}
private void ClearDirty(OwnerRecord record)
{
if (!record.Dirty) return;
record.Dirty = false;
m_DirtyCount--;
}
}
}
@@ -0,0 +1,11 @@
fileFormatVersion: 2
guid: c7aa7a7cc2823a149a9778eb4f0b07ae
MonoImporter:
externalObjects: {}
serializedVersion: 2
defaultReferences: []
executionOrder: 0
icon: {instanceID: 0}
userData:
assetBundleName:
assetBundleVariant:
@@ -0,0 +1,136 @@
using System.Collections.Generic;
using TMPro;
using UnityEngine;
namespace XericUI.XChart.Pools
{
/// <summary>
/// 文本槽位工厂:运行时里<b>唯一</b>造 TMP 标签的地方(规范 §5)。
///
/// <para>空闲的槽位停在池根(chart 根下的 <c>GeneratedTextPool</c> 节点)上并停用;
/// 发落出去时挂到该 owner 自己的宿主节点。"父节点必须等于宿主"是有效性判据的一部分——
/// 域重载后宿主是新实例,旧标签还挂在旧父节点上,这种必须丢弃重补,
/// 不能让它带着上一轮的父子关系继续画。</para>
///
/// <para>池根整块没了(chart 被销毁又重建)不抛异常:<see cref="EnsurePoolRoot"/> 直接重建。</para>
/// </summary>
public sealed class XChartTextSlotFactory : IXChartSlotFactory<TMP_Text>
{
/// <summary>池根节点名。chart 的回收校验和调试报表都按这个名字找它,所以只此一份。</summary>
public const string PoolRootName = "GeneratedTextPool";
private readonly RectTransform m_ChartRoot;
private readonly Stack<TMP_Text> m_Free = new Stack<TMP_Text>();
private RectTransform m_PoolRoot;
private int m_SlotIndex;
public XChartTextSlotFactory(RectTransform chartRoot)
{
m_ChartRoot = chartRoot;
}
/// <summary>池里闲置的槽位数(调试判据用:调度收敛后应当等于"曾经发落过又还回来的")</summary>
public int FreeCount => m_Free.Count;
public TMP_Text Acquire()
{
var poolRoot = EnsurePoolRoot();
if (poolRoot == null) return null;
while (m_Free.Count > 0)
{
TMP_Text slot = m_Free.Pop();
// 空闲表里也可能有域重载留下的僵尸件:验不过就当场销毁,别发出去
if (!IsAlive(slot)) { DestroySlot(slot); continue; }
slot.gameObject.SetActive(true);
return slot;
}
var go = new GameObject("TextSlot_" + m_SlotIndex, typeof(RectTransform));
m_SlotIndex++;
go.transform.SetParent(poolRoot, false);
go.hideFlags = XChartBase.CurrentFlags;
var tmp = go.AddComponent<TextMeshProUGUI>();
tmp.text = string.Empty;
tmp.enableWordWrapping = false;
tmp.alignment = TextAlignmentOptions.Center;
var rect = tmp.rectTransform;
rect.anchorMin = new Vector2(0.5f, 0.5f);
rect.anchorMax = new Vector2(0.5f, 0.5f);
rect.pivot = new Vector2(0.5f, 0.5f);
return tmp;
}
public void Release(TMP_Text slot)
{
if (!IsAlive(slot)) return;
slot.text = string.Empty;
slot.gameObject.SetActive(false);
var poolRoot = EnsurePoolRoot();
if (poolRoot != null) slot.transform.SetParent(poolRoot, false);
m_Free.Push(slot);
}
public void Assign(TMP_Text slot, object host)
{
if (!IsAlive(slot)) return;
var parent = host as RectTransform;
if (parent == null) return;
slot.transform.SetParent(parent, false);
slot.gameObject.SetActive(true);
}
public bool IsUsable(TMP_Text slot, object host)
{
var parent = host as RectTransform;
if (parent == null) return false;
if (!IsAlive(slot)) return false;
return slot.transform.parent == parent && slot.gameObject.activeSelf;
}
/// <summary>
/// 存在性合取判据(§5.3 的前半):件还在、GameObject 还在、保存位仍然带 DontSave。
/// 父节点与激活状态因 owner 而异,交给 <see cref="IsUsable"/>。
/// </summary>
private static bool IsAlive(TMP_Text slot)
{
if (slot == null) return false;
if (slot.gameObject == null) return false;
return (slot.hideFlags & HideFlags.DontSave) != 0;
}
private static void DestroySlot(TMP_Text slot)
{
if (slot == null) return;
if (slot.gameObject == null) return;
UnityEngine.Object.DestroyImmediate(slot.gameObject);
}
/// <summary>
/// 拆池:把池根连同池内件一起硬销毁。<b>必须有这一步</b>——池根挂在 chart 自己下面而
/// 工具清理只拆 <c>[XChartTools]</c>,不拆它就等于每回收重建一次漏一个池根在场景里。
/// 已经发落出去的件不归这里:它们在各工具的宿主下,随工具根一起销毁。
/// </summary>
public void DestroyAll()
{
m_Free.Clear();
if (m_PoolRoot == null) return;
var rootObject = m_PoolRoot.gameObject;
m_PoolRoot = null;
if (rootObject != null) UnityEngine.Object.DestroyImmediate(rootObject);
}
private RectTransform EnsurePoolRoot()
{
if (m_PoolRoot != null) return m_PoolRoot;
if (m_ChartRoot == null) return null;
var go = new GameObject(PoolRootName, typeof(RectTransform));
go.transform.SetParent(m_ChartRoot, false);
go.hideFlags = XChartBase.CurrentFlags;
m_PoolRoot = go.GetComponent<RectTransform>();
return m_PoolRoot;
}
}
}
@@ -0,0 +1,11 @@
fileFormatVersion: 2
guid: 0dcf25011e8767243943bb98474d15b6
MonoImporter:
externalObjects: {}
serializedVersion: 2
defaultReferences: []
executionOrder: 0
icon: {instanceID: 0}
userData:
assetBundleName:
assetBundleVariant: