@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/khronos/pipeline.ts

@@ -0,0 +1,337 @@
+import { sanitizeIdentifier, sortStrings, sortStringsBy } from "@gtkx/utils";
+import { type GlEnum, loadGlRegistry } from "./model.js";
+import { renderCommandsModule, renderEnumsModule, renderTypesModule } from "./modules.js";
+import { paramPairAt } from "./param-pair.js";
+import {
+    type CommandPlan,
+    type GlExclusionReason,
+    type GlPlanPolicy,
+    type GlScalar,
+    type ParamPlan,
+    planCommand,
+} from "./plan.js";
+import { deriveDeleteSingular, deriveGenSingular, renderCommand, type RenderedCommand } from "./render.js";
+import { type GlSelection, resolveEnum, selectSubset } from "./select.js";
+
+type GlExclusion = {
+    command: string;
+    reason: GlExclusionReason;
+};
+
+type GlGenerationReport = {
+    selection: GlSelection;
+    selectedCommands: number;
+    emittedCommands: number;
+    derivedSingulars: number;
+    exclusions: GlExclusion[];
+};
+
+type GlGenerationResult = {
+    files: Map<string, string>;
+    report: GlGenerationReport;
+};
+
+type GroupBearingParamPlan = Extract<ParamPlan, { kind: "scalar" | "array-in" | "ref-out" }>;
+
+type GlGenerationOptions = {
+    registryPath: string;
+    overrideExports: Set<string>;
+};
+
+type OkPlan = CommandPlan & { ok: true };
+
+type PlannedSelection = {
+    okPlans: OkPlan[];
+    planFeatures: Map<string, string>;
+    exclusions: GlExclusion[];
+};
+
+type EnumRow = {
+    token: GlEnum;
+    exportName: string;
+    literal: string;
+    feature: string;
+};
+
+const BYTE_OFFSET_PARAMS: Set<string> = new Set([
+    "glVertexAttribPointer:pointer",
+    "glVertexAttribIPointer:pointer",
+    "glVertexAttribLPointer:pointer",
+    "glDrawElements:indices",
+    "glDrawRangeElements:indices",
+    "glDrawElementsBaseVertex:indices",
+    "glDrawRangeElementsBaseVertex:indices",
+    "glDrawElementsInstanced:indices",
+    "glDrawElementsInstancedBaseVertex:indices",
+    "glDrawElementsInstancedBaseInstance:indices",
+    "glDrawElementsInstancedBaseVertexBaseInstance:indices",
+    "glMultiDrawElements:indices",
+    "glMultiDrawElementsBaseVertex:indices",
+    "glDrawArraysIndirect:indirect",
+    "glDrawElementsIndirect:indirect",
+    "glMultiDrawArraysIndirect:indirect",
+    "glMultiDrawElementsIndirect:indirect",
+]);
+
+const SINGLE_VALUED_QUERIES: Set<string> = new Set([
+    "glGetShaderiv",
+    "glGetProgramiv",
+    "glGetProgramPipelineiv",
+    "glGetBufferParameteriv",
+    "glGetBufferParameteri64v",
+    "glGetRenderbufferParameteriv",
+    "glGetFramebufferParameteriv",
+    "glGetFramebufferAttachmentParameteriv",
+    "glGetQueryiv",
+    "glGetQueryObjectiv",
+    "glGetQueryObjectuiv",
+    "glGetQueryObjecti64v",
+    "glGetQueryObjectui64v",
+    "glGetTransformFeedbackiv",
+    "glGetVertexArrayiv",
+]);
+
+const OVERRIDE_OWNED: Set<string> = new Set([
+    "glGetShaderInfoLog",
+    "glGetProgramInfoLog",
+    "glGetProgramPipelineInfoLog",
+]);
+
+const PLAN_POLICY: GlPlanPolicy = {
+    byteOffsetParams: BYTE_OFFSET_PARAMS,
+    singleValuedQueries: SINGLE_VALUED_QUERIES,
+};
+
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+const GROUP_BEARING_PARAM_KINDS: Set<ParamPlan["kind"]> = new Set(["scalar", "array-in", "ref-out"]);
+const GL_SELECTION: GlSelection = { api: "gl", version: 4.6, profile: "core" };
+
+const enumExportName = (name: string): string =>
+    sanitizeIdentifier((name.startsWith("GL_") ? name.slice(3) : name).toUpperCase());
+
+const enumLiteral = (token: GlEnum): string | undefined => {
+    const text = token.value.trim();
+    let value: bigint;
+
+    try {
+        value = BigInt(text);
+    } catch {
+        return undefined;
+    }
+
+    if (value > MAX_SAFE) {
+        return undefined;
+    }
+
+    if (/^0[xX]/.test(text)) {
+        return `0x${text.slice(2).toLowerCase()}`;
+    }
+
+    return text;
+};
+
+const groupAliasValue = (existing: string | undefined, scalarAlias: string): string => {
+    if (scalarAlias === "GLbitfield") {
+        return "GLbitfield";
+    }
+
+    return existing ?? "GLenum";
+};
+
+const mergeGroupAlias = (aliases: Map<string, string>, scalar: GlScalar, group: string | undefined): void => {
+    if (group === undefined) {
+        return;
+    }
+
+    if (scalar.groupBearing !== true) {
+        return;
+    }
+
+    const existing = aliases.get(group);
+
+    if (existing === "GLbitfield") {
+        return;
+    }
+
+    aliases.set(group, groupAliasValue(existing, scalar.tsAlias));
+};
+
+const isGroupBearingParam = (paramPlan: ParamPlan): paramPlan is GroupBearingParamPlan =>
+    GROUP_BEARING_PARAM_KINDS.has(paramPlan.kind);
+
+const considerParamGroup = (aliases: Map<string, string>, plan: OkPlan, index: number): void => {
+    const { paramPlan, param } = paramPairAt(plan, index);
+
+    if (paramPlan === undefined || param === undefined) {
+        return;
+    }
+
+    if (isGroupBearingParam(paramPlan)) {
+        mergeGroupAlias(aliases, paramPlan.scalar, param.group);
+    }
+};
+
+const collectPlanGroups = (aliases: Map<string, string>, plan: OkPlan): void => {
+    for (let index = 0; index < plan.params.length; index++) {
+        considerParamGroup(aliases, plan, index);
+    }
+
+    if (plan.returnPlan.kind === "scalar") {
+        mergeGroupAlias(aliases, plan.returnPlan.scalar, plan.command.returnGroup);
+    }
+};
+
+const collectGroupAliases = (plans: OkPlan[]): Map<string, string> => {
+    const aliases: Map<string, string> = new Map();
+
+    for (const plan of plans) {
+        collectPlanGroups(aliases, plan);
+    }
+
+    return aliases;
+};
+
+const planSelectedCommand = (registry: ReturnType<typeof loadGlRegistry>, name: string): OkPlan | GlExclusion => {
+    const command = registry.commands.get(name);
+
+    if (command === undefined) {
+        throw new Error(`Selected command ${name} is not defined in the registry`);
+    }
+
+    if (OVERRIDE_OWNED.has(name)) {
+        return { command: name, reason: "override-owned" };
+    }
+
+    const plan = planCommand(command, PLAN_POLICY);
+
+    if (!plan.ok) {
+        return { command: name, reason: plan.reason };
+    }
+
+    return plan;
+};
+
+const planSelectedCommands = (
+    registry: ReturnType<typeof loadGlRegistry>,
+    commandNames: Map<string, string>,
+): PlannedSelection => {
+    const exclusions: GlExclusion[] = [];
+    const okPlans: OkPlan[] = [];
+    const planFeatures: Map<string, string> = new Map();
+    const sortedCommands = sortStringsBy(commandNames.entries(), ([key]) => key);
+
+    for (const [name, feature] of sortedCommands) {
+        const result = planSelectedCommand(registry, name);
+
+        if ("ok" in result) {
+            okPlans.push(result);
+            planFeatures.set(name, feature);
+        } else {
+            exclusions.push(result);
+        }
+    }
+
+    return { okPlans, planFeatures, exclusions };
+};
+
+const buildEnumRows = (registry: ReturnType<typeof loadGlRegistry>, enumNames: Map<string, string>): EnumRow[] => {
+    const enumRows: EnumRow[] = [];
+    const sortedEnums = sortStringsBy(enumNames.entries(), ([key]) => key);
+
+    for (const [name, feature] of sortedEnums) {
+        const token = resolveEnum(registry, name);
+        const literal = enumLiteral(token);
+
+        if (literal === undefined) {
+            continue;
+        }
+
+        enumRows.push({ token, exportName: enumExportName(name), literal, feature });
+    }
+
+    return enumRows;
+};
+
+const claimExportName = (exportNames: Map<string, string>, name: string, owner: string): void => {
+    const existing = exportNames.get(name);
+
+    if (existing !== undefined) {
+        throw new Error(`Generated export name collision: ${name} (${existing} vs ${owner})`);
+    }
+
+    exportNames.set(name, owner);
+};
+
+const assertExportNamesDisjoint = (
+    rendered: RenderedCommand[],
+    singulars: RenderedCommand[],
+    enumRows: EnumRow[],
+    overrideExports: Set<string>,
+): void => {
+    const exportNames: Map<string, string> = new Map();
+
+    for (const command of rendered) {
+        claimExportName(exportNames, command.exportName, "command");
+    }
+
+    for (const singular of singulars) {
+        claimExportName(exportNames, singular.exportName, "derived singular");
+    }
+
+    for (const row of enumRows) {
+        claimExportName(exportNames, row.exportName, "enum constant");
+    }
+
+    const overrideCollisions = exportNames
+        .keys()
+        .filter((name) => overrideExports.has(name))
+        .toArray();
+
+    if (overrideCollisions.length > 0) {
+        throw new Error(
+            `Override module exports collide with generated exports: ${sortStrings(overrideCollisions).join(", ")}`,
+        );
+    }
+};
+
+const generateGlModules = (options: GlGenerationOptions): GlGenerationResult => {
+    const selection = GL_SELECTION;
+    const registry = loadGlRegistry(options.registryPath);
+    const subset = selectSubset(registry, selection);
+    const { okPlans, planFeatures, exclusions } = planSelectedCommands(registry, subset.commands);
+    const usedTypes: Set<string> = new Set();
+    const rendered: RenderedCommand[] = [];
+    const singulars: RenderedCommand[] = [];
+
+    for (const plan of okPlans) {
+        const feature = planFeatures.get(plan.command.name) ?? "unknown feature";
+        rendered.push(renderCommand(plan, feature, usedTypes));
+        const singular = deriveGenSingular(plan, feature, usedTypes) ?? deriveDeleteSingular(plan, feature, usedTypes);
+
+        if (singular !== undefined) {
+            singulars.push(singular);
+        }
+    }
+
+    const enumRows = buildEnumRows(registry, subset.enums);
+    assertExportNamesDisjoint(rendered, singulars, enumRows, options.overrideExports);
+
+    const files: Map<string, string> = new Map([
+        ["types.ts", renderTypesModule(collectGroupAliases(okPlans))],
+        ["enums.ts", renderEnumsModule(enumRows)],
+        ["commands.ts", renderCommandsModule(rendered, singulars, usedTypes)],
+    ]);
+
+    return {
+        files,
+        report: {
+            selection,
+            selectedCommands: subset.commands.size,
+            emittedCommands: rendered.length,
+            derivedSingulars: singulars.length,
+            exclusions,
+        },
+    };
+};
+
+export { generateGlModules, type GlGenerationReport, type GlGenerationResult };

package/src/khronos/plan.ts

@@ -0,0 +1,340 @@
+import type { GlCommand, GlParam } from "./model.js";
+import { tScalar } from "../analysis/descriptor.js";
+
+type GlScalar = {
+    descriptor: string;
+    tsAlias: string;
+    viewType?: string;
+    groupBearing?: boolean;
+};
+
+type ParsedCType = {
+    base: string;
+    pointers: number;
+    constData: boolean;
+};
+
+type ParamPlan =
+    | { kind: "scalar"; scalar: GlScalar } |
+    { kind: "boolean" } |
+    { kind: "sync" } |
+    { kind: "string-in" } |
+    { kind: "string-array-in" } |
+    { kind: "array-in"; scalar: GlScalar } |
+    { kind: "ref-out"; scalar: GlScalar } |
+    { kind: "ref-array-out"; scalar: GlScalar; lenParamName: string } |
+    { kind: "ref-fixed-out"; scalar: GlScalar; length: number } |
+    { kind: "string-out"; lenParamName: string } |
+    { kind: "buffer" } |
+    { kind: "byte-offset" } |
+    { kind: "byte-offset-array" };
+
+type ReturnPlan =
+    | { kind: "void" } |
+    { kind: "scalar"; scalar: GlScalar } |
+    { kind: "boolean" } |
+    { kind: "string" } |
+    { kind: "sync" } |
+    { kind: "opaque-pointer" };
+
+type GlExclusionReason =
+    | "callback-parameter" |
+    "compsize-output" |
+    "computed-output-length" |
+    "unsupported-shape" |
+    "override-owned";
+
+type GlPlanPolicy = {
+    byteOffsetParams: Set<string>;
+    singleValuedQueries: Set<string>;
+};
+
+type CommandPlan =
+    | {
+        ok: true;
+        command: GlCommand;
+        params: ParamPlan[];
+        returnPlan: ReturnPlan;
+    } |
+    { ok: false; command: GlCommand; reason: GlExclusionReason };
+
+type ParamOutcome = { plan: ParamPlan } | { reason: GlExclusionReason };
+
+const GL_SCALARS: Map<string, GlScalar> = new Map([
+    ["GLenum", { descriptor: tScalar("uint32"), tsAlias: "GLenum", viewType: "Uint32Array", groupBearing: true }],
+    [
+        "GLbitfield",
+        { descriptor: tScalar("uint32"), tsAlias: "GLbitfield", viewType: "Uint32Array", groupBearing: true },
+    ],
+    ["GLuint", { descriptor: tScalar("uint32"), tsAlias: "GLuint", viewType: "Uint32Array" }],
+    ["GLint", { descriptor: tScalar("int32"), tsAlias: "GLint", viewType: "Int32Array" }],
+    ["GLsizei", { descriptor: tScalar("int32"), tsAlias: "GLsizei", viewType: "Int32Array" }],
+    ["GLbyte", { descriptor: tScalar("int8"), tsAlias: "GLbyte", viewType: "Int8Array" }],
+    ["GLubyte", { descriptor: tScalar("uint8"), tsAlias: "GLubyte", viewType: "Uint8Array" }],
+    ["GLshort", { descriptor: tScalar("int16"), tsAlias: "GLshort", viewType: "Int16Array" }],
+    ["GLushort", { descriptor: tScalar("uint16"), tsAlias: "GLushort", viewType: "Uint16Array" }],
+    ["GLfloat", { descriptor: tScalar("float32"), tsAlias: "GLfloat", viewType: "Float32Array" }],
+    ["GLdouble", { descriptor: tScalar("float64"), tsAlias: "GLdouble", viewType: "Float64Array" }],
+    ["GLint64", { descriptor: tScalar("int64"), tsAlias: "GLint64" }],
+    ["GLuint64", { descriptor: tScalar("uint64"), tsAlias: "GLuint64" }],
+    ["GLintptr", { descriptor: tScalar("int64"), tsAlias: "GLintptr" }],
+    ["GLsizeiptr", { descriptor: tScalar("int64"), tsAlias: "GLsizeiptr" }],
+]);
+
+const GL_BOOLEAN = "GLboolean";
+const GL_CHAR = "GLchar";
+const GL_SYNC = "GLsync";
+const CALLBACK_BASES: Set<string> = new Set(["GLDEBUGPROC", "GLDEBUGPROCARB", "GLDEBUGPROCKHR", "GLVULKANPROCNV"]);
+
+const parseCType = (cType: string): ParsedCType => {
+    const pointers = (cType.match(/\*/g) ?? []).length;
+    const isConstData = /(^|\s)const(\s|\*)/.test(` ${cType} `) && pointers > 0;
+
+    const base = cType
+        .replaceAll("*", " ")
+        .split(/\s+/)
+        .filter((token) => token.length > 0 && token !== "const" && token !== "struct")
+        .join(" ");
+
+    return { base, pointers, constData: isConstData };
+};
+
+const isCompsize = (len: string): boolean => len.includes("COMPSIZE(");
+
+const planCompsizeOut = (command: GlCommand, scalar: GlScalar, policy: GlPlanPolicy): ParamOutcome => {
+    if (policy.singleValuedQueries.has(command.name)) {
+        return { plan: { kind: "ref-out", scalar } };
+    }
+
+    return { reason: "compsize-output" };
+};
+
+const planPointerOut = (command: GlCommand, param: GlParam, scalar: GlScalar, policy: GlPlanPolicy): ParamOutcome => {
+    const len = param.len;
+
+    if (len === undefined || len === "1") {
+        return { plan: { kind: "ref-out", scalar } };
+    }
+
+    if (isCompsize(len)) {
+        return planCompsizeOut(command, scalar, policy);
+    }
+
+    if (/^\d+$/.test(len)) {
+        return { plan: { kind: "ref-fixed-out", scalar, length: Number(len) } };
+    }
+
+    if (command.params.some((other) => other.name === len)) {
+        return { plan: { kind: "ref-array-out", scalar, lenParamName: len } };
+    }
+
+    return { reason: "computed-output-length" };
+};
+
+const planByteOffsetParam = (parsed: ParsedCType): ParamOutcome => {
+    if (parsed.pointers === 1) {
+        return { plan: { kind: "byte-offset" } };
+    }
+
+    if (parsed.pointers === 2) {
+        return { plan: { kind: "byte-offset-array" } };
+    }
+
+    return { reason: "unsupported-shape" };
+};
+
+const charStringOutLen = (command: GlCommand, param: GlParam, parsed: ParsedCType): string | undefined => {
+    if (parsed.pointers !== 1) {
+        return undefined;
+    }
+
+    const len = param.len;
+
+    if (len === undefined) {
+        return undefined;
+    }
+
+    return command.params.some((other) => other.name === len) ? len : undefined;
+};
+
+const planCharParam = (command: GlCommand, param: GlParam, parsed: ParsedCType): ParamOutcome => {
+    if (parsed.pointers === 1 && parsed.constData) {
+        return { plan: { kind: "string-in" } };
+    }
+
+    if (parsed.pointers === 2 && parsed.constData) {
+        return { plan: { kind: "string-array-in" } };
+    }
+
+    const lenParamName = charStringOutLen(command, param, parsed);
+
+    if (lenParamName !== undefined) {
+        return { plan: { kind: "string-out", lenParamName } };
+    }
+
+    return { reason: "unsupported-shape" };
+};
+
+const planScalarParam = (
+    command: GlCommand,
+    param: GlParam,
+    parsed: ParsedCType,
+    policy: GlPlanPolicy,
+): ParamOutcome => {
+    const scalar = GL_SCALARS.get(parsed.base);
+
+    if (scalar === undefined) {
+        throw new Error(`Unmapped C base type "${parsed.base}" on ${command.name}(${param.name}: ${param.cType})`);
+    }
+
+    if (parsed.pointers === 0) {
+        return { plan: { kind: "scalar", scalar } };
+    }
+
+    if (parsed.pointers === 1 && parsed.constData) {
+        return { plan: { kind: "array-in", scalar } };
+    }
+
+    if (parsed.pointers === 1) {
+        return planPointerOut(command, param, scalar, policy);
+    }
+
+    return { reason: "unsupported-shape" };
+};
+
+const planVoidParam = (parsed: ParsedCType): ParamOutcome => {
+    if (parsed.pointers === 1) {
+        return { plan: { kind: "buffer" } };
+    }
+
+    return { reason: "unsupported-shape" };
+};
+
+const planBooleanParam = (parsed: ParsedCType): ParamOutcome => {
+    if (parsed.pointers === 0) {
+        return { plan: { kind: "boolean" } };
+    }
+
+    return { reason: "unsupported-shape" };
+};
+
+const planCharOrBoolean = (command: GlCommand, param: GlParam, parsed: ParsedCType): ParamOutcome | undefined => {
+    if (parsed.base === GL_CHAR || parsed.base === "GLcharARB") {
+        return planCharParam(command, param, parsed);
+    }
+
+    if (parsed.base === GL_BOOLEAN) {
+        return planBooleanParam(parsed);
+    }
+
+    return undefined;
+};
+
+const planByBase = (command: GlCommand, param: GlParam, parsed: ParsedCType, policy: GlPlanPolicy): ParamOutcome => {
+    const { base, pointers } = parsed;
+
+    if (base === GL_SYNC && pointers === 0) {
+        return { plan: { kind: "sync" } };
+    }
+
+    if (base === "void") {
+        return planVoidParam(parsed);
+    }
+
+    return planCharOrBoolean(command, param, parsed) ?? planScalarParam(command, param, parsed, policy);
+};
+
+const planParam = (command: GlCommand, param: GlParam, policy: GlPlanPolicy): ParamOutcome => {
+    const parsed = parseCType(param.cType);
+    const { base } = parsed;
+
+    if (CALLBACK_BASES.has(base) || base.startsWith("_cl_")) {
+        return { reason: "callback-parameter" };
+    }
+
+    if (policy.byteOffsetParams.has(`${command.name}:${param.name}`)) {
+        return planByteOffsetParam(parsed);
+    }
+
+    return planByBase(command, param, parsed, policy);
+};
+
+const planScalarReturn = (base: string): ReturnPlan | undefined => {
+    if (base === "void") {
+        return { kind: "void" };
+    }
+
+    if (base === GL_SYNC) {
+        return { kind: "sync" };
+    }
+
+    if (base === GL_BOOLEAN) {
+        return { kind: "boolean" };
+    }
+
+    const scalar = GL_SCALARS.get(base);
+
+    if (scalar !== undefined) {
+        return { kind: "scalar", scalar };
+    }
+
+    return undefined;
+};
+
+const planPointerReturn = (base: string): ReturnPlan | undefined => {
+    if (base === "void") {
+        return { kind: "opaque-pointer" };
+    }
+
+    if (base === "GLubyte" || base === GL_CHAR) {
+        return { kind: "string" };
+    }
+
+    return undefined;
+};
+
+const planReturn = (command: GlCommand): ReturnPlan => {
+    const { base, pointers } = parseCType(command.returnCType);
+    let plan: ReturnPlan | undefined;
+
+    if (pointers === 0) {
+        plan = planScalarReturn(base);
+    } else if (pointers === 1) {
+        plan = planPointerReturn(base);
+    }
+
+    if (plan !== undefined) {
+        return plan;
+    }
+
+    throw new Error(`Unmapped return type "${command.returnCType}" on ${command.name}`);
+};
+
+const planCommand = (command: GlCommand, policy: GlPlanPolicy): CommandPlan => {
+    const params: ParamPlan[] = [];
+
+    for (const param of command.params) {
+        const outcome = planParam(command, param, policy);
+
+        if ("reason" in outcome) {
+            return { ok: false, command, reason: outcome.reason };
+        }
+
+        params.push(outcome.plan);
+    }
+
+    return { ok: true, command, params, returnPlan: planReturn(command) };
+};
+
+export {
+    GL_SCALARS,
+    parseCType,
+    planCommand,
+    type GlScalar,
+    type ParsedCType,
+    type ParamPlan,
+    type ReturnPlan,
+    type GlExclusionReason,
+    type GlPlanPolicy,
+    type CommandPlan,
+};