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/
├── 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 for MediaPlane
│       ├── AEMediaImagePlaneTemplate.mel  # Attribute Editor template for MediaImagePlane
│       ├── MediaPlaneNode.h/cpp     # MediaPlane node (MPxNode)
│       ├── MediaPlaneDrawOverride.h/cpp  # Viewport 2.0 draw override
│       ├── MediaImagePlane.h/cpp    # MediaImagePlane node (MPxImagePlane)
│       ├── 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
│       └── resources/
│           └── icons/
│               └── out_MediaPlane.svg  # Node icon
├── 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 Nodes

This plugin provides two types of nodes:

#### 1. MediaPlane Node (MPxNode with Viewport 2.0)

```mel
// MEL command
createNode MediaPlane;
```

#### 2. MediaImagePlane Node (MPxImagePlane)

```mel
// Create MediaImagePlane node
createNode mediaImagePlane;

// Attach to camera (required for image plane)
imagePlane -edit -camera "persp" <nodeName>;
```

### Use AE Template

The plugin includes custom Attribute Editor templates:
- `AETemplateMediaPlane.mel` - For MediaPlane node
- `AEMediaImagePlaneTemplate.mel` - For MediaImagePlane node

After installation, the MEL files are 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 for MediaPlane
source "AETemplateMediaPlane.mel";

// Source the AE template for MediaImagePlane
source "AEMediaImagePlaneTemplate.mel";
```

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

### Set Video File

#### MediaPlane Node
```mel
// Set video path
setAttr "MediaPlane1.videoFile" -type "string" "C:/path/to/video.mp4";
```

#### MediaImagePlane Node
```mel
// Set video path
setAttr "mediaImagePlane1.videoFile" -type "string" "C:/path/to/video.mp4";
```

### Difference Between Nodes

| Feature | MediaPlane | MediaImagePlane |
|---------|------------|-----------------|
| Type | MPxNode (custom) | MPxImagePlane (native) |
| Viewport | Viewport 2.0 draw override | Native image plane |
| Camera attachment | Not required | Required |
| Use case | 3D plane in scene | Standard image plane |

### MediaImagePlane Specific Usage

The MediaImagePlane node integrates with Maya's native image plane system:

```mel
// Full workflow example
createNode mediaImagePlane;
rename "imagePlane1" "myVideoPlane";

// Attach to camera
imagePlane -edit -camera "persp" "myVideoPlane";

// Set video file
setAttr "myVideoPlane.videoFile" -type "string" "C:/path/to/video.mp4";

// Optional: Adjust size
setAttr "myVideoPlane.width" 1920;
setAttr "myVideoPlane.height" 1080;
```

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

#### MediaImagePlane Specific Attributes

 | Attribute Name | Short Name | Type | Description |
 |---------------|------------|------|-------------|
 | frameOffset | fo | double | Frame offset for alignment |
 | imageSize | is | double2 | Original image size (read-only) |
 | coverage | cv | double2 | Coverage (read-only) |

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