186 lines
4.9 KiB
Markdown
186 lines
4.9 KiB
Markdown
# Maya Media Plane Node
|
|
|
|
A Maya plugin for displaying video frames in Maya Viewport 2.0.
|
|
|
|
## Features
|
|
|
|
- **Video Decoding**: Uses FFmpeg to decode MP4 and other video formats
|
|
- **Frame Rate Synchronization**: Automatically adjusts playback rate based on Maya's timeline frame rate
|
|
- **Playback Control**: Adjustable video playback rate (0.25x - 4.0x)
|
|
- **Post-Processing Effects**:
|
|
- Crop
|
|
- Resize
|
|
- Flip
|
|
- **Frame Caching**: Video frame caching mechanism for smooth playback
|
|
|
|
## Requirements
|
|
|
|
- Maya 2023 or higher
|
|
- CMake 3.14+
|
|
- Visual Studio 2019 or higher
|
|
- FFmpeg (included)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
MediaPlane/
|
|
├── CMakeLists.txt # Top-level CMake configuration
|
|
├── CMakePresets.json # CMake preset configurations
|
|
├── cmake/
|
|
│ └── modules/
|
|
│ ├── FindMaya.cmake # Maya SDK finder module
|
|
│ └── FindFFmpeg.cmake # FFmpeg finder module
|
|
├── src/
|
|
│ └── MayaImagePlaneNode/
|
|
│ ├── CMakeLists.txt # Plugin CMake configuration
|
|
│ ├── Plugin.cpp # Maya plugin entry point
|
|
│ ├── MayaMediaPlaneNode.h # Node header file
|
|
│ ├── MayaMediaPlaneNode.cpp # Node implementation
|
|
│ ├── FFmpegVideoDecoder.h # FFmpeg decoder header
|
|
│ ├── FFmpegVideoDecoder.cpp # FFmpeg decoder implementation
|
|
│ ├── FrameCache.h # Frame cache header
|
|
│ ├── FrameCache.cpp # Frame cache implementation
|
|
│ └── MediaPlane.mod # Maya module file
|
|
├── test/
|
|
│ ├── test_plugin.py # Python test script
|
|
│ ├── test_maya_plugin.cpp # C++ test code
|
|
│ └── test_viewport.mel # MEL test script
|
|
└── docs/ # Documentation directory
|
|
```
|
|
|
|
## Build Instructions
|
|
|
|
### Using CMake GUI
|
|
|
|
1. Open CMake GUI
|
|
2. Set source code directory to `MediaPlane`
|
|
3. Set build directory to `MediaPlane/build`
|
|
4. Click Configure, select Maya 2023 version
|
|
5. Click Generate
|
|
6. Open the generated solution and build
|
|
|
|
### Using Command Line
|
|
|
|
```bash
|
|
# Navigate to project directory
|
|
cd MediaPlane
|
|
|
|
# Create build directory
|
|
mkdir build
|
|
cd build
|
|
|
|
# Configure project
|
|
cmake .. -G "Visual Studio 17 2022" -DMAYA_VERSION=2023
|
|
|
|
# Build project
|
|
cmake --build . --config Release
|
|
|
|
# Install plugin
|
|
cmake --install . --config Release
|
|
```
|
|
|
|
## Installation
|
|
|
|
1. After building, the plugin will be installed to Maya 2023's plug-ins directory
|
|
2. You can also manually copy the generated `.mll` file to Maya's `plug-ins` directory
|
|
|
|
### Manual Installation
|
|
|
|
Copy the compiled `MayaMediaPlaneNode.mll` to:
|
|
|
|
```
|
|
C:\Program Files\Autodesk\Maya2023\plug-ins\
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Load Plugin in Maya
|
|
|
|
1. Open Maya 2023
|
|
2. Menu: Window > Settings/Preferences > Plug-in Manager
|
|
3. Browse and select `MayaMediaPlaneNode.mll`
|
|
4. Check Loaded
|
|
|
|
### Create Media Plane Node
|
|
|
|
```mel
|
|
// MEL command
|
|
createNode MediaPlane;
|
|
```
|
|
|
|
### Set Video File
|
|
|
|
```mel
|
|
// Set video path
|
|
setAttr "MediaPlane1.videoFile" -type "string" "C:/path/to/video.mp4";
|
|
```
|
|
|
|
### Attribute Reference
|
|
|
|
| Attribute Name | Short Name | Type | Description |
|
|
|---------------|------------|------|-------------|
|
|
| videoFile | vf | string | Video file path |
|
|
| currentTime | ct | double | Current time |
|
|
| frameRate | fr | double | Frame rate (1-240) |
|
|
| playbackRate | pr | double | Playback rate (0.25-4.0) |
|
|
| useMayaFrameRate | umf | boolean | Use Maya frame rate |
|
|
| loop | lp | boolean | Loop playback |
|
|
| postEffectCrop | pec | double4 | Crop (x, y, width, height) |
|
|
| postEffectResize | per | double2 | Resize (width, height) |
|
|
| postEffectFlip | pef | int2 | Flip (horizontal, vertical) |
|
|
| cachePolicy | cp | int | Cache policy (0-2) |
|
|
| cacheSize | cs | int | Cache size (MB, 16-2048) |
|
|
| clearCache | cc | boolean | Clear cache |
|
|
|
|
### Output Attributes
|
|
|
|
| Attribute Name | Short Name | Type | Description |
|
|
|---------------|------------|------|-------------|
|
|
| outFrameWidth | ofw | int | Output frame width |
|
|
| outFrameHeight | ofh | int | Output frame height |
|
|
| outFrameTimestamp | oft | double | Output frame timestamp |
|
|
| outFrameCount | ofc | int64 | Total frame count |
|
|
| outIsValid | oiv | boolean | Has valid frame |
|
|
| outCacheHitRatio | och | double | Cache hit ratio |
|
|
| outFrameData | ofd | int | Frame data validity flag |
|
|
|
|
## Testing
|
|
|
|
### Test Plugin Loading with mayapy.exe
|
|
|
|
```bash
|
|
"C:\Program Files\Autodesk\Maya2023\bin\mayapy.exe" test/test_plugin.py
|
|
```
|
|
|
|
### Test Viewport Display with maya.exe
|
|
|
|
1. Open Maya
|
|
2. Load the plugin
|
|
3. Execute MEL script: `source test/test_viewport.mel`
|
|
|
|
## Technical Details
|
|
|
|
### Dependencies
|
|
|
|
- Maya API (Maya 2023)
|
|
- FFmpeg (libavcodec, libavformat, libavutil, libswscale)
|
|
|
|
### Thread Safety
|
|
|
|
- Decoder is protected by mutex
|
|
- Cache is protected by mutex
|
|
|
|
### Cache Strategies
|
|
|
|
- 0: Auto cache
|
|
- 1: Preload all frames
|
|
- 2: On-demand cache
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Authors
|
|
|
|
MediaPlane Team
|