stgsharp/tools/StgSharp.GenerateGL/README.md

StgSharp.GenerateGL

StgSharp.GenerateGL generates the StgSharp desktop OpenGL C# bindings from the Khronos gl.xml registry.

The current target is OpenGL 4.6 Core. The generator does not emit OpenGL ES or mix extension entry points into the core API. gl.xml is the authoritative generation input; the retained gl.h is reference material only.

Usage

Start the interactive CLI:

dotnet run --project tools/StgSharp.GenerateGL/StgSharp.GenerateGL.csproj

Common commands:

summary
find glBindBuffer
show command glBindBuffer
target summary
families list Vertex
families show VertexAttributeP
generate all
list files
preview OpenGLFunction.v4_1.g.cs

Generate directly into an existing directory:

dotnet run --project tools/StgSharp.GenerateGL/StgSharp.GenerateGL.csproj -- generate all src/StgSharp.Graphics/OpenGL/Generated

Generation targets are explicit:

generate api [output-directory]   # function tables and managed forwarding APIs
generate enum [output-directory]  # glConst and strongly typed enum groups
generate all [output-directory]   # both sets

The API files reference the generated enum types. Use generate all for a clean output directory; use generate api when refreshing an output tree that already contains the enum files.

Without a directory, generate retains its output in the current CLI session. With a directory:

• the directory must already exist and be writable;
• each file is staged in the destination directory before replacing its target;
• an existing file is replaced only when its first line is // <auto-generated>;
• unrelated and obsolete generated files are not deleted.

Use a directory dedicated to generated source files.

Pipeline

gl.xml
  -> lossless XML and registry models
  -> desktop OpenGL 4.6 Core projection
  -> GLenum/GLbitfield semantic group projection
  -> function-family and scalar/vector relation analysis
  -> managed API filters
  -> C# naming and signature validation
  -> in-memory generated file set
  -> preview or directory output

The target projection removes GLES and ARB/NV/EXT extension entry points. It retains only commands and constants present in the target Core Profile.

Generated files:

• glconst.cs: core constants;
• GlEnums.g.cs: strongly typed enum groups referenced by Core Profile parameters and return values;
• OpenglContext.g.cs: the function-pointer table with native names and ABI types;
• glContextShadow.g.cs: an identically ordered nint table used while loading native entry points;
• OpenGLFunction.Base.g.cs: APIs introduced through OpenGL 3.2 and retained in the target profile;
• OpenGLFunction.v3_3.g.cs through OpenGLFunction.v4_6.g.cs: APIs introduced by each later core version.

OpenglContext intentionally remains close to the C ABI. Overloads, Span<T>, GlHandle, and managed naming exist only in the OpenGLFunction layer.

Overload rules

The generator merges a family only when it can validate the resulting signatures. Every managed method retains a reference to its original gl* command.

Native C API	Generated API
glUniform1f through glUniform4f	Scalar Uniform(...) overloads
glUniform*i, glUniform*ui, and glUniform*d	Merged into Uniform(...) by C# parameter type
glProgramUniform*	Merged into ProgramUniform(...) by the same rules
glUniform1*v	Uniform(..., ReadOnlySpan<T>)
glUniform4*v	Uniform(..., ReadOnlySpan<Vec4<T>>)
glUniform2*v and glUniform3*v	Omitted because Vec2 and Vec3 storage is not a tightly packed C array
glUniformMatrix4fv	Uniform(..., GraphicsMatrix) and matrix-span overloads
Other matrix sizes and double matrices	Omitted because only the graphics-oriented 4x4 float layout is defined
glGetBooleanv, glGetFloatv, glGetIntegerv, and related queries	GetValue(..., Span<T>)
glVertexAttrib1f/2f/3f/4f and equivalent scalar forms	VertexAttribute(...); component count is expressed by the parameter list
glVertexAttrib*fv/*iv/... with a scalar equivalent	Omitted instead of exposing a duplicate C-style pointer entry point
glVertexAttrib4N*	VertexAttributeNormalized(...)
glVertexAttribI*	VertexAttributeInteger(...)
glVertexAttribL*	VertexAttributeDouble(...); L does not mean C# long
glVertexAttribP1ui through P4ui	VertexAttributePacked1(...) through Packed4(...); the width prevents signature collisions
glGetVertexAttribI* and L*	GetVertexAttributeInteger(...) and GetVertexAttributeDouble(...)
glScissorIndexed and glScissorIndexedv	ScissorIndexed(...) overloads

Function families are inferred from common name prefixes, shape suffixes, type suffixes, and vector forms. Candidates are checked against:

• the gl.xml <vecequiv> relation;
• parameter len, kind, and native types;
• scalar T versus const T* relationships;
• uniqueness of the final C# signature.

If incomplete type mapping causes two methods to collapse to the same C# signature, the generator conservatively restores their normalized native names instead of emitting uncompilable overloads.

Renaming rules

Safe lexical normalization applies to all public methods:

OpenGL spelling	C# spelling
Framebuffer / framebuffer	FrameBuffer / frameBuffer
Renderbuffer / renderbuffer	RenderBuffer / renderBuffer
Internalformat / internalformat	InternalFormat / internalFormat
Attrib / attrib	Attribute / attribute
Frag	Fragment
attribindex	attributeIndex
bindingindex	bindingIndex
relativeoffset	relativeOffset
pname	pName
xoffset / yoffset / zoffset	xOffset / yOffset / zOffset
vaobj	vertexArray

Families that represent distinct semantics receive explicit names:

Native family	Managed family
TexParameter*	TextureParameter(...)
DSA TextureParameter*	NamedTextureParameter(...)
TexParameterI*	TextureParameterInteger(...)
DSA TextureParameterI*	NamedTextureParameterInteger(...)
SamplerParameterI*	SamplerParameterInteger(...)
GetnUniform*	Merged into GetUniform(...) when signatures permit
VertexAttribI/L/P/N	Expanded to Integer/Double/Packed/Normalized

Renaming never changes the native target. For example, VertexAttributeInteger(...) still calls __context->glVertexAttribI*.

Type rules

• gl.xml typedefs map to equivalent C# ABI types; the generator does not emit separate type aliases;
• GLenum and GLbitfield declarations with one unambiguous registry group use the generated enum type in public APIs;
• enum pointers preserve their pointer shape (for example, GLenum* becomes DebugSource*) and are cast back to the native uint* representation at the forwarding boundary;
• enum return values are converted from the native uint representation before being returned;
• declarations with missing or conflicting enum group metadata remain on their ABI type;
• a GLuint is converted to GlHandle only when object class and parameter semantics identify it as an object handle;
• handle arrays use Span<GlHandle> or ReadOnlySpan<GlHandle>;
• OpenGLFunction stores an OpenglContext* and forwards through __context->glFunction(...);
• unknown-length arrays, complex outputs, multiple indirection, and void* remain pointers.

A T* alone does not determine whether a managed API should use Span<T>, ReadOnlySpan<T>, out T, or a return value. Future pointer improvements should be implemented as family-specific filters validated with len, parameter direction, and OpenGL state semantics.

Raw managed forwards are omitted when a safer handwritten public API owns the command. In particular, glShaderSource remains in OpenglContext for ABI loading, while OpenGLFunction exposes the handwritten ReadOnlySpan<byte> and string overloads instead of a generated byte** signature.

Documentation comments

Every generated public method contains:

• its original C API declaration;
• a <seealso> link to the corresponding docs.gl OpenGL 4 page or family page.

The generator does not emit <param> or <returns> elements and does not copy docs.gl content.

Source layout

• Registry/: the gl.xml object model and Core Profile projection;
• Analysis/: function families, name shapes, and scalar/vector relations;
• Generation/: type mapping, API filters, signature planning, and file generation;
• Naming/: C# identifier and semantic-family naming policies;
• XmlCli.cs, RegistryCli.cs, and FunctionFamilyCli.cs: interactive inspection;
• GenerateCli.cs: in-memory preview and protected directory output.