# 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/
├── README.md                    # This file
├── CMakeLists.txt              # Top-level CMake configuration
├── CMakePresets.json           # CMake preset configurations
├── PLAN.md                     # Project plan
├── IMPLEMENTATION_GUIDE.md     # Implementation guide
├── TEST_PLAN.md                # Test plan
├── .gitignore                  # Git ignore file
├── cmake/
│   └── modules/
│       ├── FindMaya.cmake      # Maya SDK finder module
│       └── FindFFmpeg.cmake    # FFmpeg finder module
├── src/
│   └── MayaMediaPlaneNode/
│       ├── CMakeLists.txt      # Plugin CMake configuration
│       ├── Plugin.cpp          # Maya plugin entry point
│       ├── AETemplateMediaPlane.mel  # Attribute Editor template
│       ├── 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 viewport test script
│   ├── test_video.mp4               # Test video file
│   └── TEST_REPORT.md               # Test report
├── docs/                        # Documentation directory
├── install/                     # Installation directory
└── third_party/                 # Third-party dependencies
```

## 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;
```

### Use AE Template

The plugin includes a custom Attribute Editor template (AETemplateMediaPlane.mel). After installation, the MEL file is automatically placed in the Maya scripts directory and will be loaded when the plugin is loaded.

For manual loading in Script Editor:

```mel
// Source the AE template
source "AETemplateMediaPlane.mel";
```

Or copy to your Maya scripts directory:
```
C:\Users\<username>\Documents\maya\2023\scripts\
```

### 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