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
│       ├── 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
│       └── 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 Media Plane Node

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

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

Or copy to your Maya scripts directory:

C:\Users\<username>\Documents\maya\2023\scripts\

Set Video File

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

"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