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

# 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 command
createNode MediaPlane;

2. MediaImagePlane Node (MPxImagePlane)

// 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:

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

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

MediaImagePlane Node

// 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:

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

"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