MediaPlane/README.md

# 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
│       ├── 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 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;
```

### Use AE Template

The plugin includes a custom Attribute Editor template. When the plugin loads, you'll see instructions in the Script Editor. To manually load the AE template:

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

For automatic loading, copy the MEL file to your Maya scripts directory:
```
C:\Users\<username>\Documents\maya\2023\scripts\
```

Or add this to your `userSetup.mel`:
```mel
// Add to userSetup.mel
if (!`exists AETemplateMediaPlane`)
    source "AETemplateMediaPlane.mel";
```

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