Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
84 lines (56 loc) · 6.2 KB

CONTRIBUTING.md

File metadata and controls

84 lines (56 loc) · 6.2 KB

Contributing

If you use OpenGL.Net, and you're willing to improve the project, your contributions are welcome.

Create an issue

If you find something wrong during the development, you can open an issue to get help. The issue should specify all information that helps to identify the problem. The minimal information to be included should be:

  • OpenGL.Net version and configuration;
  • Operating system;
  • GPU device driver vendor, if correlated with the problem.

The common reasons for creating an issue:

  • Unexpected exceptions: if you get an unexpected exception from OpenGL.Net, the issue should specify the exception stack and message.
  • Missing OpenGL API: if you expect a GL command, a GL constant or an enumeration, but it is missing or wrong, you can create an issue about it; you can go further by checking the local gl.xml specification, and if it is reasonable, create an issue to the Khronos GitHub repository.
  • Toolkit integration: you can run OpenGL.Net with any toolkit on any(*) platform, just find the display and window handles. You can open an issue for requesting a support library for integrating some toolkit.
  • Missing feature: you can request any feature implementation, if it is related to the project target.

Project-specific notes

This repository contains both handwritten runtime code and generated OpenGL bindings. Before editing generated symbols, read the sections below.

Generated code and the generator

  • The OpenGL bindings (many Gl.*, Egl.*, Wgl.*, Glx.* files) are produced by the code generator in BindingsGen/. Generated files contain the comment "This file is automatically generated" near the top.
  • Do not manually edit files that contain the "This file is automatically generated" marker. Changes to generated output must be done by:
    1. Updating the generator (BindingsGen/) or its documentation handlers, or
    2. Updating the GL specification inputs (see next section).

GL specifications are a git submodule

  • The GL specification XML files used by the generator (GLSpecs/ such as gl.xml, egl.xml, wgl.xml, glx.xml) are included as a git submodule. They can no longer be modified directly in this repository as plain files.
  • To propose changes to a specification you must update the submodule reference or contribute upstream to the canonical Khronos repositories. Typical workflow:
    • Fork or contribute to the upstream Khronos XML repository where the spec originates.
    • Open a PR upstream if the change should be accepted by the spec maintainers.
    • In this repository update the GLSpecs submodule to point to the desired commit and open a PR that updates the submodule reference (and, if needed, the generated sources produced by BindingsGen).
  • If you are unsure whether a change belongs in the spec or in the generator, open an issue first and describe the proposed modification.

How to regenerate API sources

Preferred full rebuild in Visual Studio 2022 is described in the repo docs. For command-line / VS Code users, use the provided tasks (see below):

  1. Run the Restore task to restore NuGet packages (dotnet restore OpenGL.Net.sln).
  2. Run the Build or MSBuild (VS 2022) task. BindingsGen is a .NET Framework (net48) app and must be built with the Visual Studio 2022 build environment; the Build task calls vcvars64.bat and MSBuild for this purpose.
  3. Run the Generate APIs task. This executes BindingsGen.exe from BindingsGen/bin/Release/ and writes generated C# files into OpenGL.Net/.

Tip: the workspace contains ready-to-run VS Code tasks: Restore, Build, and Generate APIs. Use them in sequence to regenerate bindings.

Build environment requirements

  • BindingsGen targets .NET Framework and requires MSBuild and the Visual Studio 2022 build tools (the vcvars64 environment). On CI, prefer a Windows build agent with Visual Studio installed.
  • Many project files use AllowUnsafeBlocks and platform-specific settings. Follow platform-targeting settings in the .csproj files when running samples or tests.

Pull request guidelines

  • Create an issue first for non-trivial changes unless the change is a simple typo or documentation fix.
  • Use a feature branch named branch_<short-description> or similar; keep commits focused and documented.
  • For changes that affect generated code, include the generator changes or updated GLSpecs submodule reference and regenerated outputs in the same PR. Clearly state the regeneration steps in the PR description.
  • Add or update tests where appropriate. Unit tests are present in OpenGL.Net.*.Test projects.
  • Ensure the solution builds in Release configuration with the usual vcvars64/MSBuild environment. CI may run different targets; include platform/bitness notes if relevant.
  • Follow the existing code style and conventions: generated API code uses partial classes and many small files grouped by extension/feature; handwritten libraries follow the repository's prevailing naming and layout.

Coding conventions

  • Respect the generated code structure; add new generator output using the same partial-class splitting and directory layout used by the generator.
  • Avoid introducing breaking changes to public APIs without discussion.
  • If you add any native interop or unsafe code, make sure the corresponding project allows unsafe blocks (AllowUnsafeBlocks in the .csproj).

Tests and samples

  • There are multiple test projects (OpenGL.Net.Test, OpenGL.Net.Objects.Test, etc.). Run tests after making changes.
  • Samples may depend on native dependencies and specific platform bitness. Check Prefer32Bit and PlatformTarget in sample project files when running locally.

Pull request checklist

  • The change implements or documents the requested feature/bugfix.
  • Tests were added or updated if relevant.
  • The solution builds in Release configuration using Visual Studio 2022 / MSBuild.
  • Generated files were not edited by hand; generator or GLSpecs submodule was updated instead if needed.

Donate

If you like the project, or if it has saved you time, or you just want to offer a free beer to me, you can Donate.