indigo
/
MediaPlane
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
MediaPlane/docs/Module_Packaging_Spec.md

8.7 KiB
Raw Blame History

Module Packaging Specification

Overview

This document specifies the implementation details for packaging the Maya Image Plane Node plugin as a Maya module for easy installation and distribution.

Requirements

  • Create a proper Maya module structure
  • Ensure the plugin loads correctly when placed in Maya's module path
  • Support multiple versions of Maya (specifically targeting Maya 2023)
  • Include all necessary dependencies (FFmpeg binaries if not system-installed)
  • Provide version information for the plugin
  • Support both debug and release builds
  • Allow easy uninstallation and upgrading

Implementation Details

Maya Module Structure

A Maya module consists of:

  1. A module definition file (.mod)
  2. The plugin binary (.mll for Windows)
  3. Optional: scripts, icons, help files, etc.

Module Definition File

Create MayaImagePlaneNode.mod with contents:

+ MayaImagePlaneNode 1.0 ${MAYA_IMAGE_PLANE_NODE_PATH}
PLUG-INS:

Where:

  • MayaImagePlaneNode is the module name
  • 1.0 is the version
  • ${MAYA_IMAGE_PLANE_NODE_PATH} is the environment variable pointing to the module root
  • PLUG-INS: specifies where to find plugin files

Directory Structure

MayaImagePlaneNode/
├── MayaImagePlaneNode.mod
├── bin/
│   └── MayaImagePlaneNode.mll
├── lib/
│   ├── avcodec-58.dll
│   ├── avformat-58.dll
│   ├── avutil-56.dll
│   └── swscale-5.dll
├── scripts/
│   └── (optional MEL/Python scripts)
├── icons/
│   └── (optional node icons)
└── doc/
    └── (optional documentation)

Build System Integration

Modify CMake to:

  1. Install plugin to appropriate bin directory
  2. Copy FFmpeg DLLs to bin directory (if bundling)
  3. Generate module file during build
  4. Provide option to create package for distribution

Versioning

  • Use semantic versioning (major.minor.patch)
  • Version information accessible via plugin attributes
  • Update module file version when plugin version changes

Dependencies Handling

Option 1: System FFmpeg

  • Rely on FFmpeg being installed in system PATH
  • Simpler deployment but requires user to install FFmpeg separately

Option 2: Bundled FFmpeg

  • Include FFmpeg DLLs with the plugin
  • Larger distribution but guaranteed to work
  • Must comply with FFmpeg licensing (LGPL/GPL)

Option 3: Hybrid

  • Use system FFmpeg if available, fallback to bundled
  • Best of both approaches

Installation Process

  1. User extracts module to a directory
  2. Sets MAYA_IMAGE_PLANE_NODE_PATH environment variable to module root OR places module in standard Maya module locations:
    • <user>/Documents/maya/<version>/modules/
    • <Maya installation>/modules/
  3. Maya automatically detects and loads the module on startup
  4. Plugin becomes available in Maya's Plugin Manager

Uninstallation

  1. Remove module directory
  2. Remove environment variable (if set)
  3. Restart Maya

Build Configurations

  • Debug build: MayaImagePlaneNode_debug.mll
  • Release build: MayaImagePlaneNode.mll
  • Consider using different module files or paths for debug vs release

Maya API Version Compatibility

  • Compiled against Maya 2023 API
  • May work with other versions but not guaranteed
  • Consider using version-specific module files if needed

Loading Verification

  • Plugin should register successfully with Maya's plugin system
  • Node type should be available in Node Editor
  • Attributes should be accessible and editable
  • Viewport display should work when node is created

Dependencies

  • Maya 2023 development kit
  • FFmpeg libraries (matching Maya's compiler version)
  • CMake 3.14+
  • Visual Studio 2017 (matching Maya 2023's compiler)

Implementation Plan

CMake Modifications

  1. Add install() commands for plugin and dependencies
  2. Generate module file using configure_file()
  3. Optionally create package() target for CPack
  4. Set up version numbers

Module File Template

Create MayaImagePlaneNode.mod.in:

+ MayaImagePlaneNode @PROJECT_VERSION@ @CMAKE_INSTALL_PREFIX@
PLUG-INS:

Environment Variables

  • MAYA_IMAGE_PLANE_NODE_PATH: Points to module root
  • Alternatively, rely on standard Maya module discovery

Testing

  • Verify module loads in clean Maya installation
  • Test with both debug and release builds
  • Test FFmpeg dependency resolution
  • Verify plugin appears in Plugin Manager
  • Test node creation and attribute editing

Dependencies

  • CMake
  • Maya 2023 SDK

Overview

This document specifies the implementation details for packaging the Maya Image Plane Node plugin as a Maya module for easy installation and distribution.

Requirements

  • Create a proper Maya module structure
  • Ensure the plugin loads correctly when placed in Maya's module path
  • Support multiple versions of Maya (specifically targeting Maya 2023)
  • Include all necessary dependencies (FFmpeg binaries if not system-installed)
  • Provide version information for the plugin
  • Support both debug and release builds
  • Allow easy uninstallation and upgrading

Implementation Details

Maya Module Structure

A Maya module consists of:

  1. A module definition file (.mod)
  2. The plugin binary (.mll for Windows)
  3. Optional: scripts, icons, help files, etc.

Module Definition File

Create MayaImagePlaneNode.mod with contents:

+ MayaImagePlaneNode 1.0 ${MAYA_IMAGE_PLANE_NODE_PATH}
PLUG-INS:

Where:

  • MayaImagePlaneNode is the module name
  • 1.0 is the version
  • ${MAYA_IMAGE_PLANE_NODE_PATH} is the environment variable pointing to the module root
  • PLUG-INS: specifies where to find plugin files

Directory Structure

MayaImagePlaneNode/
├── MayaImagePlaneNode.mod
├── bin/
│   └── MayaImagePlaneNode.mll
├── lib/
│   ├── avcodec-58.dll
│   ├── avformat-58.dll
│   ├── avutil-56.dll
│   └── swscale-5.dll
├── scripts/
│   └── (optional MEL/Python scripts)
├── icons/
│   └── (optional node icons)
└── doc/
    └── (optional documentation)

Build System Integration

Modify CMake to:

  1. Install plugin to appropriate bin directory
  2. Copy FFmpeg DLLs to bin directory (if bundling)
  3. Generate module file during build
  4. Provide option to create package for distribution

Versioning

  • Use semantic versioning (major.minor.patch)
  • Version information accessible via plugin attributes
  • Update module file version when plugin version changes

Dependencies Handling

Option 1: System FFmpeg

  • Rely on FFmpeg being installed in system PATH
  • Simpler deployment but requires user to install FFmpeg separately

Option 2: Bundled FFmpeg

  • Include FFmpeg DLLs with the plugin
  • Larger distribution but guaranteed to work
  • Must comply with FFmpeg licensing (LGPL/GPL)

Option 3: Hybrid

  • Use system FFmpeg if available, fallback to bundled
  • Best of both approaches

Installation Process

  1. User extracts module to a directory
  2. Sets MAYA_IMAGE_PLANE_NODE_PATH environment variable to module root OR places module in standard Maya module locations:
    • <user>/Documents/maya/<version>/modules/
    • <Maya installation>/modules/
  3. Maya automatically detects and loads the module on startup
  4. Plugin becomes available in Maya's Plugin Manager

Uninstallation

  1. Remove module directory
  2. Remove environment variable (if set)
  3. Restart Maya

Build Configurations

  • Debug build: MayaImagePlaneNode_debug.mll
  • Release build: MayaImagePlaneNode.mll
  • Consider using different module files or paths for debug vs release

Maya API Version Compatibility

  • Compiled against Maya 2023 API
  • May work with other versions but not guaranteed
  • Consider using version-specific module files if needed

Loading Verification

  • Plugin should register successfully with Maya's plugin system
  • Node type should be available in Node Editor
  • Attributes should be accessible and editable
  • Viewport display should work when node is created

Dependencies

  • Maya 2023 development kit
  • FFmpeg libraries (matching Maya's compiler version)
  • CMake 3.14+
  • Visual Studio 2017 (matching Maya 2023's compiler)

Implementation Plan

CMake Modifications

  1. Add install() commands for plugin and dependencies
  2. Generate module file using configure_file()
  3. Optionally create package() target for CPack
  4. Set up version numbers

Module File Template

Create MayaImagePlaneNode.mod.in:

+ MayaImagePlaneNode @PROJECT_VERSION@ @CMAKE_INSTALL_PREFIX@
PLUG-INS:

Environment Variables

  • MAYA_IMAGE_PLANE_NODE_PATH: Points to module root
  • Alternatively, rely on standard Maya module discovery

Testing

  • Verify module loads in clean Maya installation
  • Test with both debug and release builds
  • Test FFmpeg dependency resolution
  • Verify plugin appears in Plugin Manager
  • Test node creation and attribute editing

Dependencies

  • CMake
  • Maya 2023 SDK