{"id":16145612,"url":"https://github.com/falsepattern/jwin32","last_synced_at":"2025-10-23T23:30:38.600Z","repository":{"id":45279368,"uuid":"416739319","full_name":"FalsePattern/jwin32","owner":"FalsePattern","description":"Win32 and DirectX mappings for java using Project Panama. Ignore the C# tag, it's just reference code used for decompilation","archived":true,"fork":false,"pushed_at":"2022-12-16T21:31:47.000Z","size":380,"stargazers_count":11,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-27T19:56:28.003Z","etag":null,"topics":["directx","directx-11","directx11","experimental","ffi","ffi-bindings","ffi-wrapper","java","java-17","java-panama","mapping","panama","tutorial","win32","win32-api","win32api","windows","wrapper"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FalsePattern.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-10-13T12:45:46.000Z","updated_at":"2024-04-26T13:47:19.000Z","dependencies_parsed_at":"2023-01-29T16:01:42.282Z","dependency_job_id":null,"html_url":"https://github.com/FalsePattern/jwin32","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalsePattern%2Fjwin32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalsePattern%2Fjwin32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalsePattern%2Fjwin32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FalsePattern%2Fjwin32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FalsePattern","download_url":"https://codeload.github.com/FalsePattern/jwin32/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237893773,"owners_count":19383107,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["directx","directx-11","directx11","experimental","ffi","ffi-bindings","ffi-wrapper","java","java-17","java-panama","mapping","panama","tutorial","win32","win32-api","win32api","windows","wrapper"],"created_at":"2024-10-10T00:16:59.717Z","updated_at":"2025-10-23T23:30:38.144Z","avatar_url":"https://github.com/FalsePattern.png","language":"C#","readme":"# JWin32\nA Project Panama-based mapping + wrapper generator for win32 headers.\n\n## IMPORTANT NOTICE\n- I have migrated to GNU/Linux, and can no longer keep this project maintained. If anyone is willing to carry the torch, just open an issue and i will put a link to the fork at the top of this readme.\n- This project only works on the incubator release of Panama on java 17. Java 19 has different classes for panama, so the project DOES NOT COMPILE ON JDK 19!\n\n## IMPORTANT\n* ### As of 0.5.0, no prebuilt jars will be provided. You must generate the mappings yourself.\n  This is due to the new modular header system, which makes it impractical to include prebuilt jars for every combination.\n\n\n* Now accepting pull requests for implementing function macros. Jextract cannot extract these, so it requires manual\n  labor. See the [Macros file](https://github.com/FalsePattern/jwin32/blob/master/src/main/java/com/falsepattern/jwin32/Macros.java)\n  for examples.\n\n## Table of Contents\n0. [Disclaimer](#0-disclaimer)\n1. [What is Project Panama](#1-what-is-project-panama)\n2. [Dependencies](#2-dependencies)\n3. [Selecting libraries](#3-selecting-libraries-to-be-made-available-in-java)\n4. [Generating mappings, wrappers and jar](#4-generating-mappings-wrappers-and-jar)\n5. [Running code with panama](#5-running-code-with-panama)\n6. [Linking libraries](#6-linking-libraries)\n7. [What next?](#7-what-next)\n8. [Inspiration](#8-inspiration)\n9. [Detailed description of the postprocessor](#9-detailed-description-of-the-postprocessor)\n10. [Changelog](#10-changelog)\n\n## 0. Disclaimer\nThis project is not endorsed by nor affiliated with either Microsoft, Oracle, nor the OpenJDK project.\n\nMSVC, Windows.h, d3d11.h and the Windows SDK are owned by Microsoft, and due to licensing issues, are not included as a\npart of this source code.\n\nThe project source code does not include generated and mapped files because there's a lot of files (more than 10k after\nevery class is generated)\n\nLibraries with builtin support:\n* windows.h and most of the stuff it pulls in\n* direct3d 9-12\n* dxgi\n\nI'm considering adding more libraries as \"supported by default\", such as DirectAudio, Direct2D, etc (basically the entire DirectX collection),\nas well as later expanding into non-win32 space, such as GLFW and OpenGL (only planned once panama comes out of incubator\nand becomes an experimental/stable feature usable in mainline releases). During the incubator phase, this project will be limited to\nwindows libraries.\n\nAny other libraries are currently unverified and may break. The built-in COM support is only verified with Direct3D\nCOM objects, and may break when used with the actual COM system. More precisely, RuntimeClass GUIDs and Interface GUIDs\ncannot be retrieved during runtime, and MUST be specified either using #define constants, or using the GUID_J class.\nThere's no way around this limitation at this time.\n\n## 1. What is Project Panama\nJava's project panama is an incubating feature of java, only accessible on a specific branch, is a brand-new solution\nthat gets rid of writing JNI or JNA wrappers for native libraries, and instead almost completely automates the process,\nor hides it behind neat and efficient wrapper classes.\n* Project Panama: https://openjdk.java.net/projects/panama/\n* Project Panama Builds: https://jdk.java.net/panama/\n\nImportant reading before experimenting:\n* handling native memory: https://github.com/openjdk/panama-foreign/blob/foreign-jextract/doc/panama_memaccess.md\n* handling native functions: https://github.com/openjdk/panama-foreign/blob/foreign-jextract/doc/panama_ffi.md\n\n## 2. Dependencies\n0. ### (Optional) Installing the Windows developer VM.\n   There's a possibility of jextract failing due to a nonstandard system setup. In this case, you need to do the\n   jextract phase inside the Windows 10 developer VM, or if you don't want to install the Windows sdk on your host OS.\n   You still need the panama jdk on your host to run the rest of the steps.\n   1. You need either VMWare, Hyper-V, VirtualBox, or Parallels. If you haven't installed one of those yet, VirtualBox\n      is the recommended option, as it was the only one tested with this project: https://www.virtualbox.org/wiki/Downloads\n   2. Download the Windows 10 developer VM image for you virtual machine: https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/\n   3. (VirtualBox only) Extract the WinDev....Eval.ova file from the archive you downloaded, inside VirtualBox, click on `Import`,\n      select the ova file in the `File` box, click `next`, then `Import`. After that, virtualbox will begin importing the image.\n   4. Start the developer virtual machine, download this repository inside it, then proceed with the following steps.\n   \n1. ### Project Panama\n   If you're using the VM, you still need to install this both on the host and the VM.\n   1. Download and extract JDK-panama from this URL: https://jdk.java.net/panama\n\n       (The latest version at the time of writing is `17-panama+3-167`)\n   2. Next, you have to replace your currently installed java with Panama in the PATH and JAVA_HOME system variables:\n     \n       Inside PATH, replace your current java path with, or, if you don't have one, add: `\u003cDirectory where you extracted panama\u003e\\jdk-17-panama\\bin`\n     \n       Set JAVA_HOME to: `\u003cDirectory where you extracted panama\u003e\\jdk-17-panama`\n   3. To verify that panama has been added to PATH properly, open a command prompt, and type `java - version`. \n   The first output line should start with `openjdk version \"17-panama\"`.\n   4. Also enter `jextract -version`into the same command prompt. If the output starts with\n      `WARNING: Using incubator modules: jdk.incubator.foreign, jdk.incubator.jextract`, panama is correctly\n      installed.\n2. ### Maven (optional if your IDE doesn't have it, or you don't use and IDE)\n   Note: You only need this on your host system, not inside the VM.\n\n   1. Download and extract maven from this URL: https://maven.apache.org/download.cgi\n   2. Add the maven bin directory to your PATH: `\u003cDirectory where you extracted maven\u003e\\bin`\n   3. To verify that maven has been added to PATH properly, open a command prompt, and type `mvn -version`.\n   4. If the output starts with `Apache Maven`, maven is correctly installed.\n4. ### Windows SDK\n   After you've installed project panama, you also need the header files that are then passed to jextract.\n   If you're using the VM for the jextract step, you don't need the SDK on your host system, only on the VM.\n\n\n   If you already have Visual Studio installed with Windows SDK (default if you checked `Desktop development with C++`\nwhen installing VS), you can skip this dependency.\n\n\n   Otherwise, you either have to install Visual Studio with the `Desktop development with C++` workload.\n\n   If you don't have VS installed yet:\n   1. Go to https://visualstudio.microsoft.com/downloads/\n   2. Scroll down to Visual Studio 2019\n   3. Under Community, click the `Free download` button.\n   4. Start the installer, and follow the instructions until you reach the workload selection screen.\n\n   If you already have VS installed, just type visual studio installer in the start menu search and launch it. Then,\n   click Modify to enter the workload selection menu.\n\n   The following steps are the same for both:\n   1. Select the `Desktop development with C++` workload\n   2. Click install and wait until it finishes (Approximately 2 GB download size, 8 GB on disk. Less if visual studio\n      is already installed)\n\n   ### At this point, restart your system to make sure that every program has the correct system variables available. (when running the VM, only restart the VM).\n\n## 3. Selecting libraries to be made available in java\nFirst off, go into the `c` directory, and open the `native.h` file. In this file you can configure what you want to include.\n\nCurrently, you can select the following:\n* Windows.h configurations using `#define NO...` defines.\n* Direct3D version. You can choose any combination of directx 9, 10, 11, or 12. You can also choose none of them.\n* DXGI\n\n## 4. Generating mappings, wrappers and jar\nAfter 0.5.0, the build script was unified, and the entire process is now done in one go.\n\nThe `build_install.bat` script installs the compiled jar files into the local maven repository.\n\nThe `build_package.bat` script outputs the compiled jar files into the `target` directory.\n\nYou can safely ignore errors that match one of these examples:\n* `WARNING: Using incubator modules: jdk.incubator.jextract, jdk.incubator.foreign`\n* `WARNING: Layout size not available for ...`\n* `WARNING: skipping ... because of unsupported type usage: long ...`\n\nYou can check the full list of all known non-issue warnings in `JEXTRACT_WARNINGS.txt`   \n\nIf you see any other kinds of errors, go back to the dependency setup step, download the Windows 10 developer virtual\nmachine, and redo the setup inside it. If it fails in the virtual machine too, only then should you create a new\nissue concerning this step.\n\nThe wrapper classes simplify interaction with structs and COM objects, and also turn many `#define`s\ninto `public static final` variables, which can then be used in switch statements\n(`jextract` puts `#define`s into getter methods, which cannot be used with switch statements).\n\nTo do this, simply run one of the `build_` batch files and wait until it finishes.\n\nWrapper classes are just the original struct/COM interface name with a `_J` suffix.\n\nWrapper code is placed in the `win32.mapped` package, more precisely, structs get put in `win32.mapped.struct`,\nCOM interfaces in `win32.mapped.com`, and `#define`d constants in the `win32.mapped.constants.Constants` class.\n\n## 5. Running code with panama\nBy default, foreign (native) access, even in Project Panama, is blocked. To solve this, you have to provide the\nfollowing command line arguments to java when running programs that contain panama code:\n`-Dforeign.restricted=permit --enable-native-access=ALL-UNNAMED --add-modules jdk.incubator.foreign`\n\nYou can inspect this project's pom.xml to see how to do that with maven. \n\n## 6. Linking libraries\nPanama does NOT link code by default, so for any external libraries that you want to use, you first need to load the\nappropriate libraries.\n\nFor that you need to use java's built-in `System.loadLibrary(...);` call. In short: You either have to have the dll/so\nfile in PATH, or in the working directory, and invoke `System.loadLibrary(\u003clibrary\u003e);`, where `\u003clibrary\u003e` is the\nlibrary's filename without the .so/.dll extension.\n\nWin32 specific info:\n\nTo figure out which libraries you need for win32 functions, look up the function on MSDN (msdn is well indexed by most\nweb search engines, it's enough if you type `msdn FunctionName` in your preferred search engine, and the first search\nresult will usually get you there), scroll to the bottom, and under the `Requirements` header, you can find the library\nin the `DLL` row.\n\nWith panama there are no function-style defines, so you need to use either the narrow (A) or wide(W) character-based\nfunctions. I recommend the narrow versions, as they map nicely to UTF-8 strings.\n\nCommon example: You want to create a win32 window. For that you need the `WNDCLASSEXA` struct (library independent),\nretrieved with `GetModuleHandleA`, and the `CreateWindowExA` function. These two functions are implemented in:\n\n`GetModuleHandleA`: `Kernel32.dll`\n\n`CreateWindowExA`: `User32.dll`\n\nSo, before calling any of these, preferably right at the start of your main function, or better yet, in a `static{}`\nblock in your startup class, you would load those libraries like this:\n\n```\nSystem.loadLibrary(\"Kernel32\");\nSystem.loadLibrary(\"User32\");\n```\nNote the lack of file extensions.\n\n## 7. What next?\nOver the course of the next few months I will continue polishing the generator code and add more quality of life wrappers.\n\nGoals:\n- [x] Create wrapper code for structs inside structs\n- [ ] Create wrapper code for arrays inside structs\n- [x] Create wrapper classes for constant defines\n\n## 8. Inspiration\nI originally came up with this idea after having a small spike of interest in direct3D, but found C++ programming to\nnot be my cup of tea.\nI wanted to do direct3d stuff in java, but no matter how much I looked, I couldn't find _any_ up-to-date wrapper for\ndirect3d and win32, other than the basic win32 mappings inside LWJGL, which, not surprisingly, don't contain D3D stuff.\n\nThen, I stumbled Project Panama, and after studying it and a few weeks of experiments, I decided to take matters into\nmy own hands.\n\nA bit of lore between MS and Java, I found while researching:\n\nWhile scouting the web for COM implementations in java, i stumbled upon an article mentioning an abandoned programming\nlanguage called J++, and lawsuit between Sun Microsystems and Microsoft, which eventually lead to the creation of the\n.NET framework and the C# programming language.\n\n## 9. Detailed description of the postprocessor\nThe heart of this project, where most of the magic is done, resides in com/falsepattern.jwin32.internal.\n\nThe classes inside this package and it's subpackages are responsible for analyzing the raw jextract mappings, generating COM and struct wrappers, generating special behaviour for specific types, and so on.\n\nThe following paragraphs describe the inner workings of the postprocessor, and how it transforms an obtuse harder-than-C API into a semi-usable, Java style mapping.\n\nThe first step is file retrieval and filtering.\nFiltering is required, because some classes have unstable mappings, which immediately crash the JVM when the class is loaded.\n\nNext, the first pass of the conversion is run. This generates the primitive implementations for COM objects, and also finds all of the structs.\n\nLogically identical structs (with the exact same memory layout and naming scheme) get turned into subclasses of an existing root implementation. This avoids duplicate code, and makes these types interoperable through typecasting.\n\nAfter that, the file list is scanned a second time for any remaining duplicate structs.\n\nWith these passes completed, the converter generates getters for nested structs, and at this point, the main code generation step is finished.\n\nAt this point, the generated structs and COM objects are complete, and are written to the filesystem.\n\nNext up, the code scans through the file list again, and extracts all primitive constants from the mappings into `static final` fields, allowing their use in switch statements.\n\nThe files are scanned one last time, and any GUID references are replaced with static initializers, if available. This avoids runtime linking errors, as most of these GUIDs are stored in static C libraries and cannot be retrieved with `System.loadLibrary()`.\n\nFinally, the module info for the project is generated, hiding the internal code from the public side.\n\n\n## 10. Changelog\n### [0.5.1] - 2021-12-24\n#### Changed\n* GUID getters. This should resolve issues with unresolved symbols when retrieving most (but not all) IID_... MemorySegments.\n* Rewrote build script to do everything in one go through maven\n\n### [0.5.0] - 2021-12-24\n#### Added\n* String and pointer constant extraction\n* Internal code encapsulation using project jigsaw's module-info.java system\n* Bat files for the compile step\n* Static wrapper methods for MemoryUtil singleton's MemoryAllocator\n* Copyright notices to all source files and build scripts\n* Some basic win32 macros.\n* Special logic for GUIDs, for simpler creation of GUID structs used in COM.\n* Added DXGI to the config file\n\n#### Changed\n* C headers are now modularized, and can be configured by the user before jextract-ing.\n* Reworked guide to make the jextract step reproducible in a vm.\n* Moved banned classes list to external file for better editing.\n* Separated the cleanup script from the generator.\n\n#### Removed\n* Maven distribution management\n* Security vulnerability caused by unicode file encoding. ASCII is now the default.\n\n### [0.4.2] - 2021-10-17\n#### Added\n* Additional Direct3D headers based on the [api docs](https://github.com/MicrosoftDocs/sdk-api/blob/docs/sdk-api-src/content/_direct3d11/index.md).\n  \n  Note: this does not include the C++ interoperability header, as jextract only translates C headers.\n  * d3d11_1.h\n  * d3d11_2.h\n  * d3d11_3.h\n  * d3d11_4.h\n  * d3d11sdklayers.h\n  * d3d11shader.h\n  * d3d11shadertracing.h\n  * d3dcommon.h\n  * d3dcsx.h\n* Constant extractor now extracts byte, short, int, long, float, and double constants. String constants are not extracted for now.\n#### Changed\n* Constant extractor now also removes the respective getter methods from Win32.java and its superclasses to fix some potential confusion.\n### [0.4.1] - 2021-10-16\n#### Added\n* Javadoc to the memory manipulation classes\n#### Changed\n* Fixed some broken logic in `MemoryUtil`\n#### Removed\n* Testing code in `MemoryStack`\n### [0.4.0] - 2021-10-15\n#### Added\n* Memory manipulation helper classes inside `com.falsepattern.jwin32.memory`\n#### Changed\n* Moved code generation stuff into \"internal\" class to signal to developers to not use those\n* Reworked COM wrappers to use MemoryAddress instead of MemorySegment in the constructor argument, saving some client-side conversion\n### [0.3.1] - 2021-10-15\n#### Changed\n* Now generates less whitespace into wrapper classes\n### [0.3.0] - 2021-10-15\n#### Added\n* Extraction of constants (WM_..., CS_..., etc.)\n  * They were already available through the pure mappings, however, they were hidden behind getter functions, and thus,\n    you couldn't use them in switch statements. Now you can. \n  * There's about 27k of them, extracted to `win32.mapped.Constants`\n  \n### [0.2.0] - 2021-10-14\n#### Added\n* Automatic fixing for known issues in:\n  * ID3DInclude\n  * XMLDOMDocumentEvents\n#### Changed\n* Reimplemented struct generator. Nested structs are now supported.\n#### Removed\n* The following win32 structs will not have wrappers generated, due to alignment incompatibility:\n  * _MMIOINFO\n  * DRVCONFIGINFOEX\n  * IMAGE_AUX_SYMBOL_TOKEN_DEF\n  * tagDRVCONFIGINFO\n  * midihdr_tag\n  * tagMCI_ANIM_OPEN_PARMSA\n  * tagMCI_ANIM_OPEN_PARMSW\n  * tagMCI_ANIM_WINDOW_PARMSA\n  * tagMCI_ANIM_WINDOW_PARMSW\n  * tagMCI_BREAK_PARMS\n  * tagMCI_OPEN_PARMSA\n  * tagMCI_OPEN_PARMSW\n  * tagMCI_OVLY_OPEN_PARMSA\n  * tagMCI_OVLY_OPEN_PARMSW\n  * tagMCI_OVLY_WINDOW_PARMSA\n  * tagMCI_OVLY_WINDOW_PARMSW\n  * tagMCI_WAVE_OPEN_PARMSA\n  * tagMCI_WAVE_OPEN_PARMSW\n  * tagMETAHEADER\n  * tagMIXERLINEA\n  * tagMIXERLINECONTROLSA\n  * tagMIXERLINECONTROLSW\n  * tagMIXERLINEW\n  * tagBITMAPFILEHEADER\n  * tMIXERCONTROLDETAILS\n\n    including all structs derived from these.\n  \n    If a struct contains one of these as a sub-struct, that sub-struct will not receive a wrapper field.\n\n### [0.0.0-0.1.1]\n* Extremely early code, no change tracking was done\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalsepattern%2Fjwin32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffalsepattern%2Fjwin32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffalsepattern%2Fjwin32/lists"}