From 5bee4b4957fcbee12fbf2cc702b563f04699d48b Mon Sep 17 00:00:00 2001 From: Kouji Matsui Date: Wed, 15 Nov 2023 14:07:13 +0900 Subject: [PATCH] Updated readme. --- FlashCap.V4L2Generator/dumper.sh | 2 +- README.md | 101 +++++++++++++++++++++++++++++++ README_ja.md | 96 +++++++++++++++++++++++++++++ 3 files changed, 198 insertions(+), 1 deletion(-) diff --git a/FlashCap.V4L2Generator/dumper.sh b/FlashCap.V4L2Generator/dumper.sh index dab004f..4632f41 100755 --- a/FlashCap.V4L2Generator/dumper.sh +++ b/FlashCap.V4L2Generator/dumper.sh @@ -13,7 +13,7 @@ gcc -o videodev2.dumper videodev2.dumper.cpp ./videodev2.dumper > videodev2.h.members.json echo "Step 4: Generate interop code." -mono FlashCap.V4L2Generator.exe 2 videodev2.h.members.json ../../../../FlashCap/Internal/V4L2/ +mono FlashCap.V4L2Generator.exe 2 videodev2.h.members.json ../../../../FlashCap.Core/Internal/V4L2/ echo "Step 5: Generate base interop code." mono FlashCap.V4L2Generator.exe 3 videodev2.h.members.json . diff --git a/README.md b/README.md index 7b9b222..9c7397c 100644 --- a/README.md +++ b/README.md @@ -694,6 +694,107 @@ we assume Windows as the development environment. Pull requests are welcome! Development is on the `develop` branch and merged into the `main` branch at release time. Therefore, if you make a pull request, please make new your topic branch from the `develop` branch. +### Porting V4L2 to unsupported platforms + +V4L2 is the Linux image capture standard API. +FlashCap supports V4L2 API, which allows it to run on a variety of Linux platforms. +The supported platforms are listed below: + +* i686, x86_64 +* aarch64, armv7l +* mipsel + +The supported platforms listed here are simply those that I have been able to verify work, +I have real hardware and have successfully captured the camera using FlashCap. + +If you ask me if it works on other platforms, such as mips64, riscv64, or loongarch64, it will not work. +The reasons are as follows: + +* I cannot confirm that it works: + I don't have real hardware and/or SBC (Single Board Computer) component, + so I can't physically check. +* .NET runtime or mono has not been ported, or there is no stable port. + +.NET runtime, time may solve the problem. +So, if you intend to port FlashCap to an unsupported Linux platform, +please refer to the following for a porting overview: + +* `FlashCap.V4L2Generator` is a generator to automatically generate the interoperable source code needed to port to V4L2. + This project is using the AST JSON files output by [Clang](https://clang.llvm.org/), + generate C# interoperability definition source code from V4L2 header files with the correct ABI structure strictly applied. +* Therefore, you will first need Clang for the target Linux ABI. + For this reason, it cannot be ported into an environment where a stable ABI has not been established. +* Similarly, to run `FlashCap.V4L2Generator`, you need mono or .NET runtime running on the target Linux. +* If the target Linux is a Debian-type port, these may be available from the `apt` package, for example: + `sudo apt install build-essential clang mono-devel`, etc., it is more likely. + +First, you need to build `FlashCap.V4L2Generator`. +When .NET SDK is not available in the target Linux environment, +we provide a `build-mono.sh` that compiles the code using mono `mcs` compiler. + +Then, the rough procedure is shown in the script `dumper.sh`. +Customize the script to suit your target environment. + +The source code generated by `FlashCap.V4L2Generator` is placed into `FlashCap.Core/Internal/V4L2/`. +To use it, in the `switch` statement of the type initializer in `NativeMethods_V4L2.cs`, +Add a new platform branch. + +```csharp +switch (buf.machine) +{ + case "x86_64": + case "amd64": + Interop = new NativeMethods_V4L2_Interop_x86_64(); + break; + case "i686": + case "i586": + case "i486": + case "i386": + Interop = new NativeMethods_V4L2_Interop_i686(); + break; + case "aarch64": + Interop = new NativeMethods_V4L2_Interop_aarch64(); + break; + case "armv9l": + case "armv8l": + case "armv7l": + case "armv6l": + Interop = new NativeMethods_V4L2_Interop_armv7l(); + break; + case "mips": + case "mipsel": + Interop = new NativeMethods_V4L2_Interop_mips(); + break; + + // (Insert your cool platform ported interop...) + + default: + throw new InvalidOperationException( + $"FlashCap: Architecture '{buf.machine}' is not supported."); +} +``` + +And pray to God for the rest :) +You may want to use the Avalonia sample code to verify this. +If your environment does not run Avalonia, after trying with the OneShot sample code, +You can also extend this to save a continuous bitmap and check it. + +If this is successful, PRs are welcome. + +Because the code generated by this process can be said to be nearly identical to the code on other platforms, +I have not been able to verify it directly on my stock hardware, but I can probably accept the PR. +Please also provide the following information (This will be noted in the documentation): + +* Target physical machine product name. +* Capture unit or camera product name. +* These connection methods (e.g., USB, PCIe connection, embedded cam etc.) +* Specific source if not available from a typical retailer. +* Explanation of any limitations that could not be resolved (e.g., certain video characteristics do not work) + +TIPS: The reason why V4L2Generator is needed is that the various defaults assumed +by the .NET interoperability feature are optimized +for the Windows environment and are not compatible with the variation for target ABI. + ---- diff --git a/README_ja.md b/README_ja.md index f9cd862..2460003 100644 --- a/README_ja.md +++ b/README_ja.md @@ -633,6 +633,102 @@ FlashCapは、ビルド環境をクリーンに保っています。 プルリクエストを歓迎します! 開発は`develop`ブランチ上で行って、リリース時に`main`ブランチにマージしています。 そのため、プルリクエストを作る場合は、`develop`ブランチからあなたのトピックブランチを切って下さい。 +### V4L2を未対応のプラットフォームに移植する + +V4L2はLinuxのイメージキャプチャ標準APIです。 +FlashCapはV4L2に対応していて、これによりLinuxの様々なプラットフォームで動作します。以下に対応プラットフォームを挙げます: + +* i686, x86_64 +* aarch64, armv7l +* mipsel + +ここに挙げた対応プラットフォームは、単に私が動作確認出来た、つまり現実のハードウェアを持ち合わせていて、 +FlashCapを使って実際にカメラのキャプチャに成功したものです。 + +それでは、他のプラットフォーム、例えばmips64,riscv64,loongarch64で動作するか言えば、動作しません。 +理由は、以下の通りです: + +* 私が動作確認できない: 実際のハードウェアやSBC (Single Board Computer) コンポーネントを持ち合わせていないので、物理的な確認が出来ない。 +* .NETランタイム、又はmonoが移植されていない。またはstableな移植が存在しない。 + +.NETランタイムの問題については、時間が解決する可能性はあります。 +そこで、もしFlashCapを未対応のLinuxプラットフォームに移植するつもりがあるのであれば、 +概要を示すので参考にしてください。 + +* `FlashCap.V4L2Generator` は、V4L2への移植に必要な相互運用ソースコードを自動生成するためのジェネレータです。 + このプロジェクトは、[Clang](https://clang.llvm.org/) が出力するAST JSONファイルを使用して、 + V4L2のヘッダファイルから、正しいABI構造を厳密に適用したC#の相互運用定義ソースコードを生成します。 +* 従って、まずターゲットとするLinuxのABIに対応したClangが必要になります。 + この理由により、安定的なABIが定まっていない環境に移植することはできません。 +* 同様に、`FlashCap.V4L2Generator` を動作させるために、ターゲットとするLinuxで動作するmono又は.NETランタイムが必要です。 +* ターゲットLinuxがDebian系の移植であれば、これらは `apt` パッケージなどから入手可能かもしれません。 + `sudo apt install build-essential clang mono-devel` などでインストール出来れば、可能性が高まります。 + +最初に、 `FlashCap.V4L2Generator` をビルドする必要があります。 +ターゲットのLinux環境で.NET SDKが使用できない場合は、monoの `mcs` を使ってコードをコンパイルする `build-mono.sh` を使用して下さい。 + +その後、大まかな手順は、 `dumper.sh` というスクリプトに示されているので、 +内容をターゲットの環境に合わせて書き換えて下さい。 + +`FlashCap.V4L2Generator` が生成したソースコードは、 `FlashCap.Core/Internal/V4L2/` に配置されます。 +これを使用するには、 `NativeMethods_V4L2.cs` のタイプイニシャライザの `switch` 文に、 +新しいプラットフォームの分岐を加えて下さい。 + +```csharp +switch (buf.machine) +{ + case "x86_64": + case "amd64": + Interop = new NativeMethods_V4L2_Interop_x86_64(); + break; + case "i686": + case "i586": + case "i486": + case "i386": + Interop = new NativeMethods_V4L2_Interop_i686(); + break; + case "aarch64": + Interop = new NativeMethods_V4L2_Interop_aarch64(); + break; + case "armv9l": + case "armv8l": + case "armv7l": + case "armv6l": + Interop = new NativeMethods_V4L2_Interop_armv7l(); + break; + case "mips": + case "mipsel": + Interop = new NativeMethods_V4L2_Interop_mips(); + break; + + // (ここに新しい移植を加えます...) + + default: + throw new InvalidOperationException( + $"FlashCap: Architecture '{buf.machine}' is not supported."); +} +``` + +あとは、神に祈ります :) +Avaloniaのサンプルコードを使用して確認すると良いでしょう。 +Avaloniaが動作しない環境の場合は、OneShotサンプルコードで試した後、 +これを拡張して連続したビットマップを保存して確認する方法もあります。 + +これで成功したら、PRを歓迎します。 + +このプロセスで生成されたコードは、他のプラットフォームとほぼ同一のコードと言えるため、 +私が直接ハードウェアで検証出来ていませんが、恐らくPRを受け入れることが出来るでしょう。 +以下の情報も提供してください（ドキュメントに記載されます）: + +* ターゲットの物理マシン製品名 +* キャプチャユニットやカメラの製品名 +* これらの接続方法（例えばUSB接続・PCIe接続・内臓カメラなど） +* 一般的な小売り業者から入手出来ない場合は、具体的な入手先 +* どうしても解消できなかった制約がある場合の説明（例えば特定の映像特性が動かないなど） + +TIPS: なぜV4L2Generatorが必要になるかというと、.NET相互運用機能で想定されている各種デフォルトは、 +Windows環境に最適化されていて、ターゲットのABIと互換性がないからです。 + ----