Add README.md
This commit is contained in:
parent
6fcf135d6a
commit
61ddd2a067
|
|
@ -0,0 +1,185 @@
|
|||
# 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
|
||||
Loading…
Reference in New Issue