404 lines
13 KiB
Markdown
404 lines
13 KiB
Markdown
# VavCore Godot 4.x Extension - Windows Platform
|
|
|
|
Windows-specific C# extension for hardware-accelerated AV1 video decoding in Godot 4.x using VavCore library.
|
|
|
|
## 🎯 **Features**
|
|
|
|
### **🚀 Windows Hardware-Accelerated AV1 Decoding**
|
|
- **NVIDIA NVDEC**: RTX 30/40 series GPU acceleration
|
|
- **Intel VPL**: 11th gen+ CPU with Intel Xe graphics
|
|
- **AMD AMF**: RX 6000/7000 series GPU acceleration
|
|
- **Media Foundation**: Windows 10/11 built-in decoder
|
|
- **dav1d fallback**: Software decoding for all systems
|
|
|
|
### **🎮 Godot 4.x Integration**
|
|
- **High-level Nodes**: Easy-to-use video player components
|
|
- **Low-level API**: Direct decoder control for advanced use cases
|
|
- **Resource System**: Godot-native video file and settings resources
|
|
- **Editor Integration**: Asset importers, custom inspectors, dock widgets
|
|
|
|
### **🔧 Windows Platform Architecture**
|
|
- **VavCore.Wrapper**: P/Invoke layer for Windows VavCore DLL
|
|
- **VavCore.Godot**: Godot-specific nodes and utilities
|
|
- **Windows Libraries**: NVDEC, VPL, AMF native integration
|
|
|
|
## 📁 **Project Structure**
|
|
|
|
```
|
|
vav2/platforms/windows/godot-plugin/
|
|
├── VavCoreGodot.sln # Visual Studio solution
|
|
├── build.bat # Windows build script
|
|
├── src/
|
|
│ ├── VavCore.Wrapper/ # P/Invoke wrapper library
|
|
│ │ ├── VavCore.Wrapper.csproj # .NET 6.0 library project
|
|
│ │ ├── VavCoreTypes.cs # C# data types matching C API
|
|
│ │ ├── VavCoreNative.cs # P/Invoke declarations
|
|
│ │ └── VavCoreWrapper.cs # High-level C# wrapper
|
|
│ └── VavCore.Godot/ # Godot extension library
|
|
│ ├── VavCore.Godot.csproj # Godot 4.x project
|
|
│ ├── Nodes/ # Godot nodes
|
|
│ │ ├── VavCoreVideoPlayer.cs # High-level video player
|
|
│ │ ├── VavCoreVideoTexture.cs # Video texture with YUV conversion
|
|
│ │ └── VavCoreVideoStream.cs # Low-level stream control
|
|
│ ├── Resources/ # Godot resources
|
|
│ │ ├── VavCoreVideoFile.cs # Video file metadata resource
|
|
│ │ └── VavCoreDecoderSettings.cs # Decoder configuration resource
|
|
│ ├── Utilities/ # Helper utilities
|
|
│ │ ├── VavCoreGodotUtils.cs # Platform detection and optimization
|
|
│ │ └── VavCoreImageConverter.cs # Optimized YUV→RGB conversion
|
|
│ └── Plugin/ # Editor integration
|
|
│ └── VavCorePlugin.cs # Editor plugin and importers
|
|
├── libs/ # Native library binaries
|
|
│ └── windows-x86_64/ # Windows-specific libraries
|
|
│ ├── VavCore.dll # Release VavCore library
|
|
│ └── VavCore-debug.dll # Debug VavCore library
|
|
├── addons/ # Godot addon structure
|
|
├── bin/ # Build output
|
|
├── obj/ # Intermediate files
|
|
└── README.md # This file
|
|
```
|
|
|
|
## 🚀 **Getting Started**
|
|
|
|
### **1. Prerequisites**
|
|
|
|
- **Godot 4.2.1+** with C# support
|
|
- **.NET 6.0 SDK** or higher
|
|
- **Visual Studio 2022** or **VS Code** with C# extension
|
|
- **VavCore library** binaries for your platform
|
|
- **VavCore C API** implementation (vavcore_* functions)
|
|
|
|
### **2. Building the Extension**
|
|
|
|
```bash
|
|
# Navigate to the Windows godot-plugin directory
|
|
cd vav2/platforms/windows/godot-plugin/
|
|
|
|
# Restore NuGet packages
|
|
dotnet restore
|
|
|
|
# Build the solution
|
|
dotnet build --configuration Release
|
|
|
|
# Or build specific projects
|
|
dotnet build src/VavCore.Wrapper/VavCore.Wrapper.csproj --configuration Release
|
|
dotnet build src/VavCore.Godot/VavCore.Godot.csproj --configuration Release
|
|
```
|
|
|
|
### **3. Installing in Godot Project**
|
|
|
|
#### **Option A: Add as Project Reference**
|
|
```xml
|
|
<!-- In your Godot project's .csproj file -->
|
|
<ItemGroup>
|
|
<ProjectReference Include="vav2/platforms/windows/godot-plugin/src/VavCore.Godot/VavCore.Godot.csproj" />
|
|
</ItemGroup>
|
|
```
|
|
|
|
#### **Option B: Copy Built Assemblies**
|
|
```bash
|
|
# Copy built DLLs to your Godot project
|
|
cp src/VavCore.Wrapper/bin/Release/net6.0/VavCore.Wrapper.dll /path/to/godot/project/
|
|
cp src/VavCore.Godot/bin/Release/net6.0/VavCore.Godot.dll /path/to/godot/project/
|
|
|
|
# Copy Windows native libraries
|
|
cp libs/windows-x86_64/VavCore.dll /path/to/godot/project/
|
|
```
|
|
|
|
#### **Option C: Use Demo Project**
|
|
```bash
|
|
# Use the complete demo project
|
|
cd ../../../godot-projects/vavcore-demo/
|
|
# Open in Godot 4.4.1 - already configured with VavCore extension
|
|
```
|
|
|
|
## 🎮 **Usage Examples**
|
|
|
|
### **Simple Video Player**
|
|
|
|
```csharp
|
|
using Godot;
|
|
using VavCore.Wrapper;
|
|
|
|
public partial class MyVideoPlayer : Control
|
|
{
|
|
private VavCoreWrapper _player;
|
|
|
|
public override void _Ready()
|
|
{
|
|
// Initialize VavCore library
|
|
if (!VavCoreWrapper.Initialize())
|
|
{
|
|
GD.PrintErr("Failed to initialize VavCore");
|
|
return;
|
|
}
|
|
|
|
// Create video player
|
|
_player = new VavCoreWrapper();
|
|
|
|
// Open and play video
|
|
if (_player.OpenFile("res://videos/sample.webm"))
|
|
{
|
|
// Get metadata
|
|
if (_player.GetMetadata(out var metadata))
|
|
{
|
|
GD.Print($"Video: {metadata.Width}x{metadata.Height}, {metadata.DurationSeconds:F2}s");
|
|
}
|
|
|
|
// Decode frames
|
|
DecodeFrames();
|
|
}
|
|
}
|
|
|
|
private void DecodeFrames()
|
|
{
|
|
while (!_player.IsEndOfFile)
|
|
{
|
|
if (_player.DecodeNextFrame(out var frame))
|
|
{
|
|
GD.Print($"Decoded frame {frame.FrameNumber}: {frame.Width}x{frame.Height}");
|
|
|
|
// Convert to RGB if needed
|
|
// VavCoreWrapper.ConvertYuvToRgb(frame, rgbBuffer, stride);
|
|
}
|
|
}
|
|
}
|
|
|
|
public override void _ExitTree()
|
|
{
|
|
_player?.Dispose();
|
|
VavCoreWrapper.Cleanup();
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Advanced Stream Control**
|
|
|
|
```csharp
|
|
using VavCore.Godot.Nodes;
|
|
using VavCore.Wrapper;
|
|
|
|
public partial class AdvancedVideoControl : Node
|
|
{
|
|
private VavCoreVideoStream _videoStream;
|
|
|
|
public override void _Ready()
|
|
{
|
|
_videoStream = new VavCoreVideoStream();
|
|
|
|
// Connect to low-level events
|
|
_videoStream.PacketRead += OnPacketRead;
|
|
_videoStream.FrameDecoded += OnFrameDecoded;
|
|
_videoStream.StreamError += OnStreamError;
|
|
|
|
// Open stream with specific decoder
|
|
_videoStream.OpenStream("res://videos/4k_video.webm", VavCoreTypes.DecoderType.NVDEC);
|
|
}
|
|
|
|
private void DecodeManualFrame()
|
|
{
|
|
// Manual frame-by-frame decoding
|
|
if (_videoStream.ReadNextPacket(out var packet))
|
|
{
|
|
if (_videoStream.DecodePacket(packet, out var frame))
|
|
{
|
|
// Process decoded frame
|
|
GD.Print($"Decoded frame {frame.FrameIndex}: {frame.Width}x{frame.Height}");
|
|
}
|
|
}
|
|
}
|
|
|
|
private void OnPacketRead(ulong frameIndex, double timestamp, uint packetSize)
|
|
{
|
|
GD.Print($"Read packet {frameIndex}: {packetSize} bytes at {timestamp:F3}s");
|
|
}
|
|
|
|
private void OnFrameDecoded(ulong frameIndex, double timestamp, Vector2I resolution)
|
|
{
|
|
GD.Print($"Decoded frame {frameIndex}: {resolution.X}x{resolution.Y} at {timestamp:F3}s");
|
|
}
|
|
|
|
private void OnStreamError(string errorMessage)
|
|
{
|
|
GD.PrintErr($"Stream error: {errorMessage}");
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Custom Decoder Settings**
|
|
|
|
```csharp
|
|
using VavCore.Godot.Resources;
|
|
|
|
public partial class VideoSettings : Control
|
|
{
|
|
public override void _Ready()
|
|
{
|
|
// Create optimal settings for current platform
|
|
var settings = VavCore.Godot.Utilities.VavCoreGodotUtils.CreateOptimalSettings();
|
|
|
|
// Customize settings
|
|
settings.PreferredDecoderType = VavCoreTypes.DecoderType.NVDEC;
|
|
settings.EnableHardwareAcceleration = true;
|
|
settings.MaxFrameBufferSize = 15;
|
|
settings.EnableZeroCopyDecoding = true;
|
|
|
|
// Apply quality preset
|
|
settings.ApplyPreset(VavCoreDecoderSettings.QualityPreset.Ultra);
|
|
|
|
// Save settings as resource
|
|
ResourceSaver.Save(settings, "user://vavcore_settings.tres");
|
|
|
|
// Load settings
|
|
var loadedSettings = GD.Load<VavCoreDecoderSettings>("user://vavcore_settings.tres");
|
|
}
|
|
}
|
|
```
|
|
|
|
### **Video File Metadata**
|
|
|
|
```csharp
|
|
using VavCore.Godot.Resources;
|
|
|
|
public partial class VideoMetadata : Control
|
|
{
|
|
public override void _Ready()
|
|
{
|
|
// Create video file resource
|
|
var videoFile = new VavCoreVideoFile("res://videos/sample.webm");
|
|
|
|
if (videoFile.IsValid)
|
|
{
|
|
// Access metadata
|
|
GD.Print($"Resolution: {videoFile.VideoWidth}x{videoFile.VideoHeight}");
|
|
GD.Print($"Duration: {videoFile.DurationSeconds:F2} seconds");
|
|
GD.Print($"Frame rate: {videoFile.FrameRate:F2} FPS");
|
|
GD.Print($"Codec: {videoFile.CodecType}");
|
|
GD.Print($"File size: {videoFile.GetFormattedFileSize()}");
|
|
|
|
// Get detailed info
|
|
var info = videoFile.GetVideoInfo();
|
|
foreach (var key in info.Keys)
|
|
{
|
|
GD.Print($"{key}: {info[key]}");
|
|
}
|
|
|
|
// Check decoder compatibility
|
|
var compatibleDecoders = videoFile.GetCompatibleDecoders();
|
|
GD.Print($"Compatible decoders: {string.Join(", ", compatibleDecoders)}");
|
|
|
|
var recommendedDecoder = videoFile.GetRecommendedDecoder();
|
|
GD.Print($"Recommended decoder: {recommendedDecoder}");
|
|
}
|
|
else
|
|
{
|
|
GD.PrintErr($"Invalid video file: {videoFile.ErrorMessage}");
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 🔧 **Configuration**
|
|
|
|
### **Decoder Settings Presets**
|
|
|
|
```csharp
|
|
// Ultra Quality (High-end systems)
|
|
settings.ApplyPreset(VavCoreDecoderSettings.QualityPreset.Ultra);
|
|
|
|
// High Quality (Gaming systems)
|
|
settings.ApplyPreset(VavCoreDecoderSettings.QualityPreset.High);
|
|
|
|
// Balanced (Most systems)
|
|
settings.ApplyPreset(VavCoreDecoderSettings.QualityPreset.Balanced);
|
|
|
|
// Performance (Lower-end systems)
|
|
settings.ApplyPreset(VavCoreDecoderSettings.QualityPreset.Performance);
|
|
|
|
// Power Saver (Mobile/battery)
|
|
settings.ApplyPreset(VavCoreDecoderSettings.QualityPreset.PowerSaver);
|
|
```
|
|
|
|
### **Platform-Specific Optimization**
|
|
|
|
```csharp
|
|
// Get platform information
|
|
var platformInfo = VavCoreGodotUtils.GetPlatformInfo();
|
|
GD.Print($"Platform: {platformInfo["platform"]}");
|
|
GD.Print($"Optimal decoder: {platformInfo["optimal_decoder"]}");
|
|
GD.Print($"Hardware acceleration: {platformInfo["hardware_acceleration"]}");
|
|
|
|
// Check hardware acceleration support
|
|
bool hwSupported = VavCoreGodotUtils.IsHardwareAccelerationSupported();
|
|
string perfCategory = VavCoreGodotUtils.GetPerformanceCategory();
|
|
string optimalAPI = VavCoreGodotUtils.GetOptimalGraphicsAPI();
|
|
|
|
// Validate video file
|
|
var (isValid, errorMessage) = VavCoreGodotUtils.ValidateVideoFile("path/to/video.webm");
|
|
```
|
|
|
|
## 📊 **Performance Monitoring**
|
|
|
|
```csharp
|
|
// Get performance statistics
|
|
var stats = videoPlayer.GetPerformanceStats();
|
|
GD.Print($"Frames decoded: {stats["frames_decoded"]}");
|
|
GD.Print($"Frames dropped: {stats["frames_dropped"]}");
|
|
GD.Print($"Average decode time: {stats["avg_decode_time_ms"]} ms");
|
|
|
|
// Format stats for display
|
|
string formattedStats = VavCoreGodotUtils.FormatPerformanceStats(stats);
|
|
GD.Print(formattedStats);
|
|
|
|
// Monitor hardware capabilities
|
|
var capabilities = videoPlayer.GetHardwareCapabilities();
|
|
GD.Print($"Hardware acceleration: {capabilities["hardware_acceleration"]}");
|
|
GD.Print($"Zero-copy decoding: {capabilities["zero_copy_decoding"]}");
|
|
```
|
|
|
|
## 🐛 **Troubleshooting**
|
|
|
|
### **Common Issues**
|
|
|
|
1. **VavCore library not found**
|
|
```
|
|
Error: Could not load VavCore.dll/libVavCore.so
|
|
Solution: Ensure native libraries are in the correct path
|
|
```
|
|
|
|
2. **Hardware acceleration not available**
|
|
```
|
|
Check: VavCoreGodotUtils.IsHardwareAccelerationSupported()
|
|
Solution: Use software decoder fallback
|
|
```
|
|
|
|
3. **Video file not supported**
|
|
```
|
|
Check: VavCoreVideoFile.IsFormatSupported(filePath)
|
|
Solution: Convert to WebM/MKV with AV1 codec
|
|
```
|
|
|
|
### **Debug Information**
|
|
|
|
```csharp
|
|
// Log comprehensive system information
|
|
VavCoreGodotUtils.LogSystemInfo();
|
|
|
|
// Create detailed system report
|
|
var systemReport = VavCoreGodotUtils.CreateSystemReport();
|
|
|
|
// Check video file validation
|
|
var (isValid, error) = VavCoreGodotUtils.ValidateVideoFile(videoPath);
|
|
```
|
|
|
|
## 🎯 **Next Steps**
|
|
|
|
1. **Audio Support**: Future integration with VavCore audio decoding
|
|
2. **Streaming**: Network video streaming support
|
|
3. **GPU Integration**: Direct GPU surface rendering optimization
|
|
4. **Mobile Optimization**: Enhanced Android/iOS performance
|
|
|
|
---
|
|
|
|
🎮 **Cross-platform AV1 video decoding made easy for Godot 4.x!**
|
|
⚡ **Hardware acceleration with software fallback for maximum compatibility!** |