autodesk developer network api reference guide...the sparks api is maintained for upwards...

Autodesk® Visual Eff ects and Finishing2010 Extension 1 Edition

Autodesk® Developer Network Sparks® API Reference Guide

Autodesk® Visual Effects and Finishing 2010 Extension 1

© 2009 Autodesk, Inc. All rights reserved. Except as otherwise permitted by Autodesk, Inc., this publication, orparts thereof, may not be reproduced in any form, by any method, for any purpose.

Certain materials included in this publication are reprinted with the permission of the copyright holder. Portions relating to MD5 Copyright © 1991-2, RSA Data Security, Inc. Created 1991. All rights reserved. License to copy and use this softwareis granted provided that it is identified as the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencingthis software or this function. License is also granted to make and use derivative works provided that such works are identified as "derived fromthe RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing the derived work. RSA Data Security, Inc.makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. Itis provided "as is" without express or implied warranty of any kind. These notices must be retained in any copies of any part of this documentationand/or software.

TrademarksThe following are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and other countries:3DEC (design/logo), 3December, 3December.com, 3ds Max, ADI, Algor, Alias, Alias (swirl design/logo), AliasStudio, Alias|Wavefront (design/logo),ATC, AUGI, AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface,Autodesk, Autodesk Envision, Autodesk Intent, Autodesk Inventor, Autodesk Map, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSnap,AutoSketch, AutoTrack, Backburner, Backdraft, Built with ObjectARX (logo), Burn, Buzzsaw, CAiCE, Can You Imagine, Character Studio, Cinestream,Civil 3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer,Create>what's>Next> (design/logo), Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer,DesignStudio, Design|Studio (design/logo), Design Web Format, Discreet, DWF, DWG, DWG (logo), DWG Extreme, DWG TrueConvert, DWGTrueView, DXF, Ecotect, Exposure, Extending the Design Team, Face Robot, FBX, Fempro, Filmbox, Fire, Flame, Flint, FMDesktop, Freewheel,Frost, GDX Driver, Gmax, Green Building Studio, Heads-up Design, Heidi, HumanIK, IDEA Server, i-drop, ImageModeler, iMOUT, Incinerator,Inferno, Inventor, Inventor LT, Kaydara, Kaydara (design/logo), Kynapse, Kynogon, LandXplorer, Lustre, MatchMover, Maya, Mechanical Desktop,Moldflow, Moonbox, MotionBuilder, Movimento, MPA, MPA (design/logo), Moldflow Plastics Advisers, MPI, Moldflow Plastics Insight, MPX,MPX (design/logo), Moldflow Plastics Xpert, Mudbox, Multi-Master Editing, NavisWorks, ObjectARX, ObjectDBX, Open Reality, Opticore,Opticore Opus, Pipeplus, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream, ProjectPoint, ProMaterials, RasterDWG,Reactor, RealDWG, Real-time Roto, REALVIZ, Recognize, Render Queue, Retimer,Reveal, Revit, Showcase, ShowMotion, SketchBook, Smoke,Softimage, Softimage|XSI (design/logo), Sparks, SteeringWheels, Stitcher, Stone, StudioTools, Topobase, Toxik, TrustedDWG, ViewCube, Visual,Visual Construction, Visual Drainage, Visual Landscape, Visual Survey, Visual Toolbox, Visual LISP, Voice Reality, Volo, Vtour, Wire, Wiretap,WiretapCentral, XSI, and XSI (design/logo). Adobe, Flash and Reader are either trademarks or registered trademarks in the United States and/or countries. Automatic Duck and the ducklogo are trademarks of Automatic Duck, Inc. FFmpeg is a trademark of Fabrice Bellard, originator of the FFmpeg project. Python is a registeredtrademark of Python Software Foundation. All other brand names, product names or trademarks belong to their respective holders.

DisclaimerTHIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY AUTODESK, INC. “AS IS.” AUTODESK, INC. DISCLAIMSALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY ORFITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS. Published by: Autodesk, Inc.111 Mclnnis ParkwaySan Rafael, CA 94903, USA Title: Autodesk Visual Effects and Finishing 2010 Extension 1 Edition Autodesk Developer Network Sparks API Reference GuideDocument Version: 1Date: August 28, 2009

Contents

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1About Sparks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Using this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Chapter 2 Sparks API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5About the Sparks API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Mandatory—SparkInfoStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Sparks Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Mandatory—SparkInitialise ( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Mandatory—SparkClips( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Mandatory—SparkProcess( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Mandatory—SparkUnInitialise( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7SparkProcessEnd( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7SparkProcessStart( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Recommended—SparkMemoryTempBuffers( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7SparkEvent( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8SparkSetupIOEvent( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8SparkIdle( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8SparkFrameChange( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8SparkAnalyse( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8SparkAnalyseStart( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8SparkAnalyseEnd( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9SparkInteract( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9SparkOverlay( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9SparkChannelEditor( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10SparkIsInputFormatSupported( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Calling Sequence for Sparks Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

iii

New Memory Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Old Memory Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Memory Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Old Memory Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11New Memory Buffer Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12State Transition of Sparks Memory Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Batch Processing in Autodesk Visual Effects and Finishing products . . . . . . . . . . . . . . . . 13Working with Memory Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Sparks User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Control Page Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Setup Page Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Sparks Hot Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Sparks Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Desktop and Component Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16The Desktop Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17The Component Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Sample User Interface Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17The Channel Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Adding Controls to the Channel Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Customizing the Channel Editor Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Using Channel Editor Folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Sparks Setup Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 3 Sparks Utility Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21About Sparks Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21User Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

sparkMessage( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22sparkCursorBusy( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22sparkViewingCursor( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22sparkControlUpdate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22sparkReprocess( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22sparkViewingDraw( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22sparkMessageConfirm( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkClipControlTitle( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkPointerRead( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkPointerWaitOff( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkPointerWaitOn( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkQueryKeyMap( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkError( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkMpFork( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23sparkMpInfo( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24sparkMpForkPixels( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24sparkMpIsMainTask( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24sparkProcessTruncate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24sparkDisableParameter( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24sparkEnableParameter( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24sparkControlTitle( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkResultClipName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkPointerInfo( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkGetViewerRatio( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkFrameRate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkSetupControlUpdate ( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkFileBrowserDisplayLoad( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25sparkFileBrowserDisplayLoadSequence( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26sparkFileBrowserDisplaySave( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26sparkFileCheckOverwrite( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26sparkFileHasExtension( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26sparkSystemSh( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

iv | Contents

sparkSystemNoSh( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26sparkWaitpid( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Memory Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27sparkMemRegisterBuffer( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27sparkMemRegisterBufferSize( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27sparkMemRegisterBufferFmt( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28sparkMemGetBuffer( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28sparkMemGetFreeMemory( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Channel Editor Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28sparkSetCurveKey( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28sparkSetCurveKeyf( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28sparkGetCurveValuef( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28sparkGetCurveValue( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sparkIsAutoKeyOn ( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sparkCeAddFolder( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sparkCeAddControl( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sparkSetControlName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sparkChRemoveKey( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29sparkChClear( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30sparkChCopy( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30sparkChPreComputeValues ( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30sparkChPreComputedValues( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30sparkChReadRawKeys( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Environment Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30sparkGraphSetup( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30sparkAPIVersionInfo( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31sparkProgramGetName( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31sparkGetInfo( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31sparkWorkingDir( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31sparkCallingEnv( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Image Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31sparkGetFrame( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Image Colour Space Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32sparkMonochrome( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32sparkNegative( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32sparkToYUV( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32sparkToHLS( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32sparkFromYUV( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32sparkFromHLS( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33sparkRGBtoYUV( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33sparkRGBtoHLS( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33sparkYUVtoRGB( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33sparkHLStoRGB( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Image-Processing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33sparkBlur( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34sparkComposite( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Image Buffer Manipulation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34sparkCopyBuffer( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34sparkCopyChannel( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34sparkResizeBuffer( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

File I/O Support Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35sparkSetPermissions( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35sparkSaveSetup( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35sparkLoadSetup( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Scan Mode Identification Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35sparkGetScanFormat( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Process Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35sparkMpAllocateTaskHandle( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36int sparkMpCreateTask( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36sparkMpWaitTask( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Contents | v

sparkMpFreeTaskHandle( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36sparkMpGetCpu( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Chapter 4 Sparks Audio API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37About Sparks Audio API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Global Audio Parameter Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

sparkSampleFormat( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38sparkSampleWidth( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38sparkAudioBlockSize( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38sparkAudioFreeSpace( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38sparkAudioMaxOutputTracks( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38sparkFrameRate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38sparkSamplingRate( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Memory Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38typedef enum spark_buffer_fmt { } SparkBufferFmt; . . . . . . . . . . . . . . . . . . . . . . . . 38

SparkClipInfoStruct and SparkTrackInfoStruct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39typedef struct spark_clip_info_struct { } SparkClipInfoStruct; . . . . . . . . . . . . . . . . . . . 39typedef struct spark_track_info_struct { } SparkTrackInfoStruct; . . . . . . . . . . . . . . . . . . 39

Processing and Analyse Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40SparkProcessEnd( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40SparkAnalyse( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40SparkAnalyseStart( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40SparkAnalyseEnd( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40sparkSetCurveKeyf( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Other Audio Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41SparkClipFilter( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41sparkGetClipInfo( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41sparkGetAudioTrackInfo( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41sparkAudioOutputEnable( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42sparkReadAudio( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42sparkNewAudio( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42sparkWriteAudio( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42sparkTruncateAudio( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Chapter 5 Testing Your Spark Using Burn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Testing Sparks Using Burn in Stand-alone Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Configuring an Autodesk Application for Testing Sparks via Burn . . . . . . . . . . . . . . . . . 46Disabling the Backburner Server and Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Starting Burn on the Render Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Testing Sparks and Previewing Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Using a Script for Your Test Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Building Spark DSO Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Using Sparks and Reactivating the Distributed Queueing System . . . . . . . . . . . . . . . . . . . . 50

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

vi | Contents

Introduction

Topics in this chapter:

■ About Sparks on page 1■ Compatibility on page 1■ System Requirements on page 2■ Using this Guide on page 2■ Getting Help on page 3

About SparksA Sparks® plug-in defines an interactive user interface similar to any of the standard modules in Autodesk®

Visual Effects and Finishing products and can be used to load clips from the desktop or EditDesk, manipulatethem, and process new clips back to the desktop or EditDesk. These plug-ins can be used to provide imageand audio processing features that are not already available with Inferno®, Flame®, Flint®, and Smoke®.

In Autodesk Visual Effects products, some Sparks can be used in Batch from the Spark node. In AutodeskFinishing products, some Sparks can be used as soft effects.

Sparks plug-ins allow you to customize your environment and expand the capabilities of your system.

After you create a Sparks plug-in, you can copy it to the /usr/discreet/sparks directory of a Autodesk VisualEffects and Finishing product. For information on how to load a Sparks plug-in into a Autodesk Visual Effectsand Finishing product, refer to the “Sparks” chapter in your Inferno, Flame, Flint, or Smoke user guide.

CompatibilityAll the Sparks plug-in conventions detailed in this guide are compatible with Inferno 2010 Extension 1, Flint2010 Extension 1, Flame 2010 Extension 1, and Smoke 2010 Extension 1.

1

1

System RequirementsYou can use the C++ compiler that comes with your Linux® operating system to build Sparks.

Files related to Sparks plug-ins are located in the ~/sparks directory. They include the following.

Makefile This file includes parameters and code for compiling and linking Spark code. Once compiled andlinked, Sparks are loaded onto Autodesk Visual Effects and Finishing products.

spark.h The header file that must be included in the Sparks plug-in. It contains all the function declarationsrequired to compile a Sparks DSO (dynamic shared object).

spark*.c Sample Sparks plug-in files distributed with Autodesk Visual Effects and Finishing products.

When compiling, you must use the spark.h header file distributed with your Autodesk Visual Effects andFinishing product. If you use a more recent header, you might have unresolved symbols when linking theSparks plug-in to your Autodesk Visual Effects and Finishing product.

The Sparks API is maintained for upwards compatibility, but new versions of the API introduce new functions.If you use these new functions when developing your Sparks plug-ins, be aware that users who have notupgraded their systems will not be able to run your Sparks plug-ins.

Using this GuideThe Autodesk Sparks API Reference Guide has been created to allow third parties to develop software plug-insfor use with Autodesk Visual Effects and Finishing products. This guide describes:

■ The Sparks interface

■ Functions required by a Sparks plug-in

■ The organization of the Sparks user interface

■ Utility functions that are provided in the API including audio functions

In addition to reading this document, Sparks developers should examine the sample Sparks source filessupplied with Autodesk Visual Effects and Finishing products. You can find these files in the ~/sparks directory.

Related DocumentationRead this document in conjunction with the documentation set of your Autodesk Visual Effects and Finishingproduct. Refer to the “Sparks” chapter in your Inferno, Flame, Flint, or Smoke user guide.

You can also learn about Linux configuration in the latest Configuration Guide for Autodesk Developer NetworkSparks Plug-ins, available through the Autodesk Developer Network Sparks program.

Documentation ConventionsThe following notation conventions are used in this document.

ExampleConvention

/usr/project1Italics denote UNIX files and directories.

SparkInitialisefunctions appear in Courier bold font.

SPARK_FLAG_YOutput from functions is printed in Courier regular font.

2 | Chapter 1 Introduction

Getting HelpIf you need more information or help with the Sparks Plug-In API, contact the Autodesk Developer Network(ADN) Sparks program: http://www.autodesk.com/joinadn

Getting Help | 3

http://www.autodesk.com/joinadn

Sparks API


■ About the Sparks API on page 5■ Sparks Interface Functions on page 6■ Calling Sequence for Sparks Interface Functions on page 10■ Memory Buffer Management on page 11■ Sparks User Interface on page 15■ Desktop and Component Levels on page 16

About the Sparks APIA Sparks plug-in is a dynamic shared object (DSO). This is a compiled object that can be dynamically loadedand linked to a process at run time.

Each Sparks plug-in uses a standard internal format. Since Autodesk Visual Effects and Finishing productsmakes calls to the Sparks routines, you must correctly name and implement certain functions in order tocreate a working Sparks plug-in.

Mandatory—SparkInfoStructThe parameter of type SparkInfoStruct appears in many of the functions. This parameter defines theinterface between Autodesk Visual Effects and Finishing products and the Sparks environment, and alsocontains information required for processing source images. The structure type is defined in the spark.hheader file, which must be included in each Sparks source file.

2

5

Sparks Interface FunctionsThe following section provides the correct naming for mandatory, optional, and recommended interfacefunctions that you can use to facilitate communication between Autodesk Visual Effects and Finishingproducts and Sparks plug-ins.

NOTE The first four functions are mandatory.

Mandatory—SparkInitialise ( )unsigned int SparkInitialise ( SparkInfoStruct SparkInfo )

Autodesk Visual Effects and Finishing products call the SparkInitialise function in three situations:

■ When you invoke a new Sparks plug-in.

NOTE When you use the same Sparks plug-in numerous times, the SparkInitialise function is onlycalled the first time.

■ When the resolution of the input used with the Sparks plug-in changes (in Batch or on the desktop).

■ When the resolution of the output of the Sparks plug-in changes. (In this case, the Sparks plug-in hasno input.)

A Sparks plug-in typically uses this function to perform the following:

■ To load a setup that was saved from the last invocation of the Sparks plug-in and that sets the userinterface variables to the previously defined values.

■ To allocate any resources, such as dynamic memory, that the Sparks plug-in requires.

The return value of the SparkInitialise function determines whether the Sparks plug-in operates atthe desktop level or at the component level, and it is defined by the “bit-wise or” of the required levels. Forexample, if the Sparks plug-in is to operate at both the desktop and component levels, the return valuewould be (SPARK_DESKTOP | SPARK_MODULE). In this case, it is up to you to supply software thatoperates at both these levels. See Desktop and Component Levels on page 16.

Mandatory—SparkClips( )int SparkClips( void )

The SparkClips function tells Autodesk Visual Effects and Finishing products how many source clips arerequired by the Sparks plug-in. For example, a Sparks plug-in used for image compositing requires a frontclip, back clip, and matte clip in order to produce an output clip. Therefore, the SparkClips functionwould return a value of 3. A Sparks plug-in used for image blending requires only two source clips; in thiscase, the SparkClips function would return a value of 2.

Autodesk Visual Effects and Finishing products use the return value to determine which of the Front, Back,and Matte control buttons appear at the component level. See The Component Level on page 17.

Mandatory—SparkProcess( )unsigned long *SparkProcess( SparkInfoStruct SparkInfo )

6 | Chapter 2 Sparks API

The SparkProcess function contains the processing algorithms (written by you) of the Sparks plug-in.The function is called once for every output frame to be generated, as indicated by the return value of theSparkProcessStart function. The SparkProcess return value must be the address of the image bufferthat contains the processed image. Autodesk Visual Effects and Finishing products use the contents of theimage buffer to generate a frame of the output clip on the destination reel (or EditDesk); the destinationreel is selected when the user calls the Sparks plug-in from the desktop. If the return value is NULL, no actionis taken by the calling environment of the Autodesk Visual Effects and Finishing products.

Mandatory—SparkUnInitialise( )void SparkUnInitialise( SparkInfoStruct SparkInfo )

The SparkUnInitialise function can be used to save user interface configurations or to release anyresources that were allocated by the SparkInitialise function. There is no associated return value forthis function. It is called in the following situations:

■ When another Sparks plug-in is invoked from the desktop.

■ When the resolution of the input used with the Sparks plug-in changes (in Batch or on the desktop).

■ When the resolution of the output of the Sparks plug-in changes. (In this case, the Sparks plug-in hasno input.)

■ Upon exit of Autodesk Visual Effects and Finishing products.

SparkProcessEnd( )void SparkProcessEnd( SparkInfoStruct SparkInfo )

SparkProcessEnd( ) is executed once at the end of the processing loop whether it is completed oraborted.

NOTE SparkProcess( ) must return a valid pointer to a frame buffer if the Sparks plug-in is called fromBatch.

SparkProcessStart( )int SparkProcessStart( SparkInfoStruct SparkInfo )

SparkProcessStart( ) is no longer mandatory. If not defined, it is assumed to return 1. TheSparkProcessStart function determines the frame layout of the processed clip. The return value of thefunction indicates the number of frames to be generated for the current input frame. Since in most casesthere is a one-to-one relationship between the length of the input clip and the length of the output clip,the function return value is usually 1. The value is different than 1 for functions in which the length of theprocessed clip is not the same as that of the source clip, for example, when using a timewarp function inwhich the source clip is either expanded or compressed in time. For an example, see the file sparkAverage1.c,located in the ~/sparks directory.

NOTE A Sparks plug-in can also request any frame of any input clip using the sparkGetFrame utility function.See Sparks Utility Library on page 21.

Recommended—SparkMemoryTempBuffers( )void SparkMemoryTempBuffers( void )

Mandatory—SparkUnInitialise( ) | 7

The SparkMemoryTempBuffers function (introduced with Inferno 2.5, Smoke 2.5, Flame 5.5, and Flint5.5 [Sparks API version 2.5+] ) allows you to access the memory buffer interface. This function, unlike thememory management interface from previous versions, allows memory to be allocated for loading Sparksplug-ins on-the-fly, and is essential to batch processing. The API memory functions used to register imagebuffers have an effect only through this function.

NOTE There is no return value associated with this function.

TIP The new memory management system, which is more resource-friendly and provides greater stability isrecommended. It is required to load a Sparks plug-in from Batch or to access the Player from a Sparks plug-in.See Memory Buffer Management on page 11.

SparkEvent( )void SparkEvent( SparkModuleEvent Event )

The SparkEvent function can be used to notify Sparks plug-ins of certain user events (defined in spark.hheader file).

SparkSetupIOEvent( )void SparkSetupIOEvent( SparkModuleEvent Event, char *Path, char *File)

The SparkSetupIOEvent function can be used to notify a Sparks plug-in of user load or save setup events.The path and file parameters will receive the values entered by the user.

SparkIdle( )void SparkIdle( void )

The SparkIdle function can be used to determine when the application is idle and waiting for an event.

SparkFrameChange( )void SparkFrameChange( SparkInfoStruct SparkInfo )

The SparkFrameChange function can be used by Sparks plug-ins that need to be notified of frame changes.

SparkAnalyse( )ulong * SparkAnalyse( SparkInfoStruct SparkInfo )

SparkAnalyse( ) works like SparkProcess( ) but does not generate any output clips.

The field SparkInfo.TotalFrameNo passed to this function gives the maximum video length amongthe input clips. If none of the input clips contain video frames, SparkInfo.TotalFrameNo is set to 1.SparkInfo.TotalFrameNo is defined in the spark.h header file.

SparkAnalyseStart( )int SparkAnalyseStart( SparkInfoStruct SparkInfo )


SparkAnalyseStart( ) is used to control the length ratio between the input and the output just asSparkProcessStart( ) does. If not defined, it is assumed to return 1.


SparkAnalyseEnd( )void SparkAnalyseEnd( SparkInfoStruct SparkInfo )

SparkAnalyseEnd( ) is executed once at the end of the analysis loop whether it is completed or aborted.


SparkInteract( )unsigned long *SparkInteract( SparkInfoStruct SparkInfo, int SX, int SY,float Pressure, float VX, float VY, float VZ )

The SparkInteract function provides for interactive image manipulation by defining the Sparks actionswhen a mouse, tablet, or other input device event occurs in the image window. For example, this functioncan be used to define a processing region or crop box in the image.

The input parameters are used as follows:

■ SX and SY correspond to the screen coordinates of the input device event, with the origin defined as thelower-left corner of the screen.

■ Pressure indicates the pressure exerted on the input device. The range of values for this parameter is from0 to 1.

■ VX and VY correspond to image coordinates, with the origin defined as the lower-left corner of the image.Note that the current position of the image origin in screen coordinates is given by the FrameBufferXand FrameBufferY fields of the SparkInfo structure.

■ VZ is the zoom factor.

The return value should be the address of an image buffer used to update the image window. If the returnvalue is NULL, no action is taken by the calling environment.

SparkOverlay( )void SparkOverlay( SparkInfoStruct SparkInfo, float ZoomFactor )

The SparkOverlay function provides a way to add user-defined information on top of the image windowthat is not actually part of the image. Typically, the function is used to draw things such as object handles,axes, or crop boxes. The function is called every time the image window is redrawn, immediately afterrefreshing the image itself.

SparkAnalyseEnd( ) | 9

WARNING Sparks writers should use the SparkOverlay function carefully, making sure to restore the graphicalcontext to its original state before exiting the function. Autodesk Visual Effects and Finishing products cannotprevent a Sparks plug-in from changing graphical parameters required for normal operation. If Autodesk VisualEffects and Finishing products start behaving strangely after running a Sparks plug-in that uses the SparkOverlayfunction, the first debugging step should be to comment out SparkOverlay from that Sparks plug-in and runthe Autodesk Visual Effects and Finishing product again.

SparkChannelEditor( )void SparkChannelEditor(void)

The SparkChannelEditor function lets you customize the Channel Editor layout by creating channelhierarchies. It is invoked by the Autodesk Visual Effects and Finishing product before the SparkInitialisefunction. The sparkCeAddFolder and sparkCeAddControl API functions have an effect only throughthis function.

SparkIsInputFormatSupported( )int SparkIsInputFormatSupported( SparkPixelFormat fmt )

The SparkIsInputFormatSupported function allows a Spark to tell IFF whether it supports a givenpixel format.

The input parameter fmt must be one of the supported pixel formats in the SparkPixelFormatenumeration (declared in the sparks.h header file).

This function must return 1 if the Spark supports the given format. Otherwise, it should return 0. If a Sparkdoes not provide this function, support for the SPARKBUF_RGB_24_3x8 and SPARKBUF_RGB_48_3x12formats is assumed, thus maintaining API compatibility with existing Sparks.

Note that support for certain formats is subject to the license restrictions of Autodesk's Visual FX and Finishingapplications. A Spark that supports RGB 16-bit floating point format may not be allowed to process an imagein that format if the application (into which the image is loaded) does not support 16-bit floating pointprocessing.

The following image conversion and processing functions only support SPARKBUF_RGB_24_3x8 andSPARKBUF_RGB_48_3x12 images:

■ sparkMonochrome()

■ sparkFromHLS()

■ sparkFromYUV()

■ sparkBlur()

■ sparkNegative()

■ sparkToHLS()

■ sparkToYUV()

■ sparkComposite()

Calling Sequence for Sparks Interface FunctionsThis section shows the sequence in which Autodesk Visual Effects and Finishing products call the Sparksinterface functions. For the sake of simplicity, the function parameters are not shown.


New Memory Modelclip_total = SparkClips( )

SparkMemoryTempBuffers( )

SparkChannelEditor( )

SparkInitialise( )

for( i = 0; i < length_of_longest_input_clip; i++ ) {

do {

frame_total = SparkProcessStart( )

} while( frame_total == 0 )

for( j = 0; j < frame_total; j++ ) {

result_buffer = SparkProcess( )

}

}

SparkProcessEnd( )

SparkUnInitialise( )

Old Memory ModelSparkChannelEditor( )

SparkInitialise( )

clip_total = SparkClips( )

for( i = 0; i < length_of_longest_input_clip; i++ ) {

do {

frame_total = SparkProcessStart( )

} while( frame_total == 0 )

for( j = 0; j < frame_total; j++ ) {

result_buffer = SparkProcess( )

}

}

SparkProcessEnd( )

SparkUnInitialise( )

Since the SparkInteract function is a ghost function that is called each time an input device eventoccurs, it is not shown in the calling sequence.

NOTE The SparkOverlay function is also called whenever the image window needs refreshing.

Memory Buffer ManagementThere are two main ways to approach memory buffer management, referred to here as the old memoryinterface and the new memory interface. To maintain backwards compatibility with the Sparks plug-inscoded for versions earlier than Inferno 2.5, Smoke 2.5, Flame 5.5, and Flint 5.5, the Sparks API will defaultto the old memory buffer interface. The advantage of the new memory interface is a more flexible interfacethat includes the ability to use the Sparks plug-in from the Batch module.

Old Memory InterfaceIn general, a Sparks plug-in uses a set of n source clips, where n is determined by the return value of theSparkClips function, to produce one or more output frames. Autodesk Visual Effects and Finishingproducts pass the addresses of the input clips to the Sparks plug-in from the Buffers field of theSparkInfoStruct input parameter. If multiple frames from the source clips are required to produce a

New Memory Model | 11

single output frame, all but the last frame of information must be saved in temporary buffers. This can easilybe achieved using the supplemental buffers that are provided in the Buffers field of SparkInfoStruct.

The maximum number of image buffers available to the Sparks plug-in is 17 plus the number of buffersdeclared on the Memory line of the configuration file. There is a restriction that the first n buffers are reservedfor input from Autodesk Visual Effects and Finishing products. The additional buffers can be used in anyfashion, and the address of the output image is returned to the calling environment as the return value ofeither the SparkProcess or the SparkInteract function.

If you require more image buffers than Autodesk Visual Effects and Finishing products provide, you mayallocate them yourself. You must adhere to the following restrictions to allow the buffers to be passed backto Autodesk Visual Effects and Finishing products for display and/or processing:

■ The buffers must be longword aligned in memory. Autodesk Visual Effects and Finishing products rejectany buffer that does not follow this constraint.

■ The buffer definition must correspond to one of the structures defined in the spark.h header file.

New Memory Buffer InterfaceSparks plug-ins access the memory buffer interface by defining the SparkMemoryTempBuffers function.When this function is defined, Autodesk Visual Effects and Finishing products will allocate n input buffersreturned by the SparkClips function, plus one buffer for the result. Any extra buffer(s) must be registeredwithin the SparkMemoryTempBuffers function’s scope using one of the three memory functions of theSparks Utility Library.

All Sparks plug-in memory buffers registered to Autodesk Visual Effects and Finishing products receive aunique ID number:

■ The result clip's ID is 1.

■ The input clips receive IDs 2 to n.

■ Any extra buffer registered use an ID from n+1 to n+x.

These IDs are used by your processing routines to access specific memory buffers. The following exampleshows how you can use these IDs.

/* Aliases for Image Buffers */

static int RESULT_ID = 1;

static int AUX1_ID;

static int AUX2_ID;

static int AUX3_ID;

static SparkMemBufStruct SparkResult;

static SparkMemBufStruct SparkAux1;



void SparkMemoryTempBuffers( void )

{

AUX1_ID = sparkMemRegisterBuffer( );

AUX2_ID = sparkMemRegisterBufferSize(

sizeof(unsigned long)*400 );

AUX3_ID = sparkMemRegisterBufferFmt(

200, 100, SPARK_FMT_MONO );

}

/* ...etc */


State Transition of Sparks Memory BuffersOnce a Sparks memory buffer is registered, Autodesk Visual Effects and Finishing products are in control ofits state transition. Memory buffers are locked only when needed, for example, when processing a frame(desktop processing) or when a Sparks module is edited. A Sparks plug-in can write to a memory buffer onlywhen its state is locked. When processing, the contents of a buffer are still valid and clean only if the bufferis flagged unlocked and/or clean. If it is flagged dirty, the Autodesk Visual Effects and Finishing product hasaccessed that memory location, and the buffer contents have therefore been compromised.

Batch Processing in Autodesk Visual Effects and Finishing productsWhen loaded in the Batch environment of Visual Effects products, a Sparks plug-in has to share its memoryresources with other process nodes active in Batch. Sparks memory buffers are unlocked between processes.If a Sparks memory buffer is used by any other process, its state will become compromised, or dirty. If aSparks memory buffer is flagged clean, the contents of the buffer are still valid.

Registered

Unregistered

New

Locked

Unlocked(Clean)

Dirty

Working with Memory BuffersThe following are important factors to consider when working with memory buffers:

■ A fixed temporary memory buffer is assumed; however, you must use non-fixed temporary memorybuffers if the input or output resolution of your Sparks plug-in could change. You can assume that thevalidity of pointers or memory buffers will not persist if the input or output resolution changes and thatcorruption problems may ensue. See sparkMemRegisterBuffer( ) on page 27.

■ If you decide to use the new memory buffer interface, you will benefit from a more flexible interface andyour Sparks plug-in will be supported in the Batch processing module of Visual Effects products (the oldmemory interface does not support Batch processing).

■ With the new memory interface, the Sparks plug-in interface calling sequence has been changed: bufferchecking done in SparkInitialise or SparkClips is no longer valid. Buffer allocation is nowchecked on-the-fly.

■ Memory is only allocated when a memory buffer is flagged MEMBUF_LOCKED

WARNING A registered buffer is not a locked buffer (that is, you cannot access the Sparks memory unless thebuffer is MEMBUF_LOCKED).

■ Be careful when using sparkError( ) within SparkInitialise( ). The sparkError( )function unlinks your Sparks DSO and calls SparkUnitialise( ).

WARNING Do not delete any uninitialised memory!

The following is an example of how to use the Sparks memory interface.

State Transition of Sparks Memory Buffers | 13

static int RESULT_ID = 1;

static int CLIP1_ID;

static int AUX1_ID;

static int AUX2_ID;

static int AUX3_ID;

static SparkMemBufStruct SparkResult;

static SparkMemBufStruct SparkClip1;




int SparkClips( void )

{

return ( 1 );

}

void SparkMemoryTempBuffers( void )

{

AUX1_ID = sparkMemRegisterBuffer();

AUX2_ID = sparkMemRegisterBufferSize(

sizeof(unsigned long)*400 );

AUX3_ID = sparkMemRegisterBufferFmt(

200, 100, SPARK_FMT_MONO );

}

unsigned int SparkInitialise( SparkInfoStruct SparkInfo )

{

int bufCount;

int i;

if ( sparkAPIVersionInfo() < 2.5 )

{

/* clean here before bailing out! */

sparkError("The current IFFFSE version

"doesn't support this SPARK!");

}

/* etc... */

return ( SPARK_MODULE );

}

unsigned long *SparkProcess( SparkInfoStruct SparkInfo )

{

int bufCount, i;

if ( sparkMemGetBuffer(RESULT_ID, &SparkResult) == 0 )

return NULL;

if ( sparkMemGetBuffer(CLIP1_ID, &SparkAux1) == 0)

return NULL;

if ( sparkMemGetBuffer(AUX1_ID, &SparkAux1) == 0 )

return NULL;


return NULL;


return NULL;

if ( !(SparkResult.BufState & MEMBUF_LOCKED )

|| !(SparkClip1.BufState & MEMBUF_LOCKED )

|| !(SparkAux1.BufState & MEMBUF_LOCKED )



return NULL;

bufCount = SparkResult.TotalBuffers;

/* ...etc. */


return (SparkResult.Buffer);

}

/* ...etc. */

Sparks User InterfaceThe Sparks user interface employs the same basic control types found in the components of other AutodeskVisual Effects and Finishing products. These control types include an integer numeric display, a floatingpoint numeric display, a text string display, a colour button, a toggle button, a mode display, and a pushbutton.

A specific format is used to name the controls. All control names begin with the string "Spark" followedby a string identifying the control type.

Identifies:Control type string:

An integer numeric display.Int

A floating point display.Float

A text string display.String

A color button.Color

A toggle button.Boolean

A mode display.Popup

A simple push button.Push

The control name must end in a numeric value that identifies the position of the control on a predefinedgrid. For example, the control named SparkFloat0 identifies a floating point numeric display at position0 on the grid. The control named SparkPopup21 identifies a mode display at position 21 on the grid.

Text string parameters are wider than the other types of parameters. Typically, they occupy two grid positions,except for those at the desktop level in the extreme right column of the component level.

Control Page CanvasSparks plug-ins used in Component mode now have access to the control page canvas by defining anappropriate SparkCanvasStruct structure. If a Sparks control is also defined on the control page wherea canvas was defined by a Sparks plug-in, the Sparks control will be drawn on top of the canvas. Controlpage 5 can be used uniquely for a canvas.The following example defines a Sparks canvas on control page 5.

SparkCanvasStruct SparkCanvas5 = { HistoDisplayCB,

HistoInteractCB };

These are the related structure declarations added to the spark.h header file:

Sparks User Interface | 15

typedef struct {

void (*DisplayCallback) (SparkCanvasInfo);

int (*InteractCallback)(SparkCanvasInfo Canvas, int

PointerX, int PointerY, float PointerPressure);

/* return 1 for canvas display */

} SparkCanvasStruct;

typedef struct {

int X0; /* Canvas Origin */

int Y0;

int Width; /* Canvas Width */

int Heigth; /* Canvas Height */

};SparkCanvasInfo;

Setup Page ControlsA Sparks plug-in can create up to 22 user interface controls in the Setup menu. You cannot animate thesecontrols. The following example defines an integer numeric display in the Sparks setup menu.

SparkIntStruct SparkSetupInt21 = { 5,

1,

10,

1,

SPARK_FLAG_NO_ANIM,

"Undo Levels %d",

NULL } ;

Sparks Hot KeysSparks plug-ins used in Component mode have standard predefined hot keys. The F1 through F4 hotkeyscan be used to toggle between the input clips and result clip views. The 1 through 5 hot keys toggle betweenthe five control pagesThe Channel Editor comes with the standard hot keys. Refer to the Hot Keys ReferenceGuide for your product.

Sparks PlayerSparks plug-ins using the new memory model have access to the Player. When a clip is processed, Play andDelete buttons are displayed on the right side on the timebar allowing the user to respectively play or deletethe last clip processed.

Desktop and Component LevelsA Sparks plug-in can operate at either or both of two levels: the desktop level and the component level.When a Sparks plug-in is chosen, the Autodesk Visual Effects and Finishing product prompts the user toselect all required input clips using the standard clip selection cursors. Enabling the S[ ] box on the Sparksbutton in the Autodesk Visual Effects and Finishing product lets the user retrieve the same clips used thelast time the Sparks plug-in was invoked.

If the Sparks plug-in can operate at both the desktop and the component levels, the E[ ] box in the AutodeskVisual Effects and Finishing product then appears on the Sparks button. If the E[ ] box is selected beforeselecting the destination reel, the Sparks plug-in runs at the component level; otherwise, it runs at thedesktop level. The E[ ] box does not appear if the Sparks plug-in operates only at one of the levels.


The Desktop LevelAt the desktop level, the Sparks controls appear in the menu when the user chooses the Sparks plug-in. Thisis similar to the command menu that appears when the user chooses Dissolve in the Editing menu in Flame.

A Sparks plug-in can have up to six controls at the desktop level. The controls are numbered 0 through 5.No interactive callback functions are associated with the controls at this level. To see the effect of applyinga Sparks plug-in to the source clips, the user must set the control values and then process the clips by selectingthe destination reel or EditDesk.

The Component LevelAt the component level, the Sparks user interface occupies the entire desktop. There is an image window inthe work area, control displays and buttons, wide screen viewing tools, and a Channel Editor. This is similarto the interface of the Dissolve Editor, for example, in the Editing menu in Flame. Using a Sparks plug-in atthe component level is the best way to debug and fine-tune the Sparks plug-in itself.

The basic controls include timelines, buttons to select the Front, Back, Matte or Result clip for display,buttons to access the Setup, Control or Anim submenus, and an Exit button.

The controls at the component level are numbered from 6 to 121 and may have associated callback functions.You can save your user interface configuration, or setup, and create animation channels for each user interfacevariable. An animation channel has the same callback function as that of the corresponding interface control.

Sparks parameters 6 to 34 appear on the first control page; parameters 35 to 63 appear on the second controlpage; parameters 64 to 92 appear on the third control page; and parameters 93 to 121 appear on the fourthcontrol page.

The user interface buttons on control pages two to four only appear for Sparks plug-ins that define parameterson these pages.

Sample User Interface ControlThe following example defines an integer numeric display, or slider, in a Sparks menu.

SparkIntStruct SparkInt6 = { 0,

0,

100,

1,

SPARK_FLAG_X | SPARK_FLAG_NO_ANIM,

"Slider Value %d",

NULL } ;

In this declaration, the integer numeric display has the following properties:

■ The initial value is 0.

■ The minimum value is 0.

■ The maximum value is 100.

■ The increment value is 1. This is used to modify the current value when the pointer device is draggedover the display.

■ The flags tell the Autodesk Visual Effects and Finishing product that this parameter is an X coordinatethat should be rescaled if the Sparks plug-in is applied to a frame of a different size, and that this parametershould not appear as an entry in the Channel Editor. Other possibilities are SPARK_FLAG_Y (to identifya parameter as a Y coordinate) and SPARK_FLAG_NO_INPUT (to tag a display as an output-only field).

The Desktop Level | 17

■ The text string defines how the integer value appears in the numeric display.

■ The Value field corresponds to the integer value you enter.

■ The NULL parameter indicates that there is no callback function associated with the numeric display.

■ The value of 6 in the control name tells the Autodesk Visual Effects and Finishing product that thiscontrol appears at the component level of the Sparks plug-in, on the first control page.

Most Sparks plug-ins are designed to operate at both the desktop and component levels. In order to havethe same controls available at both levels, you must declare each desktop level control at the componentlevel as well. For example, the control SparkInt0 operating at the desktop level may have an almostidentical control named SparkInt6 operating at the component level.

Other Sparks parameter types have similar fields. Refer to the spark.h header file for a complete list of thefields available for each parameter type.

For controls that operate at the two different levels, you may want to include a callback in the declarationof the component level control. A callback updates the image each time you modify the control value (eitherdrag-and-drop or continuous updating). To include a callback in the previous example, replace the NULLparameter with the name of a function that is called by the Autodesk Visual Effects and Finishing producteach time you modify the control value.

NOTE The interfaces at the two levels are completely independent; you must declare the same controls at eachlevel.

The Channel EditorThe Sparks user interface includes the standard Channel Editor used by the modules in Autodesk VisualEffects and Finishing products. The Channel Editor is only available at the component level. By default, allSparks numerical controls (int and float types) appear in the Channel Editor unless their Flags fieldincludes the SPARK_FLAG_NO_ANIM value.

You can access the Channel Editor with the Animation button available at the component level. When itappears, it replaces the Sparks control page. The standard Channel Editor controls to add, move, and deletekeyframes are available. There is also an AutoKey feature that automatically generates a keyframe when aSparks control is updated, either through the control page or through a call to the SparksControlUpdateutility function. You can toggle the AutoKey on and off from the Set Up, control, or Channel Editor page.

A control is animated by the Channel Editor if it has one or more keyframes. Otherwise, the control valueis taken from the control page.

Adding Controls to the Channel EditorThe Sparks utility functions let you create Channel Editor controls that are not attached to user interfacenumerical controls. You define these controls using the same structures as user interface controls; the controlscan be numbered from 0 to 121. You can set and retrieve keyframes using Sparks utility functions.

NOTE The Channel Editor supports a maximum of 244 controls (folders and controls are considered to be thesame; that is, you handle both in the same way since Autodesk Visual Effects and Finishing products do not makea distinction).

The following example defines a floating numeric control in the Channel Editor.


SparkFloatStruct SparkUserFloat10 = { 0,

0,

50,

0.5,

SPARK_FLAG_NONE,

"Amplitude: %d",

NULL };

Controls associated with the Channel Editor are identified by the Sparks User prefix. These controls appearin the Channel Editor only. Unlike regular controls, they are not tied to user interface controls. The flag andcallback fields have no effect with Channel Editor controls.

Customizing the Channel Editor LayoutSparks utility functions let you create channel hierarchies in the Channel Editor. See Channel Editor Functionson page 28. You can create up to four levels in the Channel Editor. You do this by adding folders andinserting controls into them. Any controls that you have not added to a folder are appended to the end ofthe list on the first level.

Using Channel Editor FoldersNote the following when creating Channel Editor folders:

■ You activate levels 2, 3, and 4 of the Channel Editor by creating folders.

■ You create folders in a parent-child fashion. For example, to create a folder on the second level, a foldermust already exist on the first level.

■ You must first activate a level before adding a Sparks user interface control or Channel Editor control toit.

■ You can create a maximum of four levels in the Channel Editor. Therefore, you cannot add folders tolevel four.

■ Autodesk Visual Effects and Finishing products keep track of the last item on each level. For example, ifyou create a folder on level one and insert controls into it, and then create another folder on level one,all controls you then insert are added to the newly created folder. This is shown in the following example.

void SparkChannelEditor ( void )

{

sparkCeAddFolder (SPARK_CE_LEVEL1, "offset");

/* ...creates a folder on level 1 and activates level 2 */

sparkCeAddControl (SPARK_CE_LEVEL2,

SPARK_CE_CONTROL, 121);

/* ...adds the Spark Channel Editor control

number 121 on level 2 in the offset folder */

sparkCeAddFolder (SPARK_CE_LEVEL1, "shift");

/* ...creates a new folder on level 1 */

sparkCeAddControl (SPARK_CE_LEVEL2,

SPARK_UI_CONTROL, 121);

/* ...adds the sparks user interface numerical

control number 121 on level 2 in the shift folder */

}

NOTE Your UNIX terminal displays all errors that occur when using the sparkCeAddFolder and thesparkCeAddControl functions.

Customizing the Channel Editor Layout | 19

Sparks Setup ManagementThe Sparks Setup menu is also available at the component level from the Sparks user interface. Sparks setups(including all current control values and Channel Editor curves) can be saved, loaded, or deleted.

NOTE Attempts to load setups containing controls that no longer exist in a Sparks plug-in will fail. When modifyingan existing Sparks plug-in, care should be taken to keep it compatible with earlier versions.


Sparks Utility Library


■ About Sparks Plug-ins on page 21■ User Interface Functions on page 21■ System Functions on page 26■ Memory Functions on page 27■ Channel Editor Functions on page 28■ Environment Functions on page 30■ Image Access Functions on page 31■ Image Colour Space Conversion Functions on page 32■ Image-Processing Functions on page 33■ Image Buffer Manipulation Functions on page 34■ File I/O Support Functions on page 35■ Scan Mode Identification Function on page 35■ Process Management Functions on page 35

About Sparks Plug-insThe Sparks development environment includes a number of utility functions that simplify image processingand extend the Sparks user interface. Together, the utility functions form the Sparks utility library. All thesefunctions use the prefix "spark" (all lowercase) to differentiate them from the "Spark"-prefixed functionscalled by Autodesk Visual Effects and Finishing products. The following sections describe the currentlyavailable utility functions.

User Interface FunctionsUse the user interface functions to show, hide, or control different user interface elements such as theChannel Editor, cursors, and the file browser.

3

21

sparkMessage( )void sparkMessage( char *MessageString )

The sparkMessage function displays the text message supplied by MessageString in the desktopmessage window.

sparkCursorBusy( )void sparkCursorBusy( void )

The sparkCursorBusy function can be used to change the cursor type while a clip is being processed.This function is called from other user interface callback functions only.

sparkViewingCursor( )void sparkViewingCursor( int CursorIndex )

The sparkViewingCursor function can be used to define which of the standard cursors in AutodeskVisual Effects and Finishing products should appear when the pointer device is over the image window. Allcurrently available cursors for Autodesk Visual Effects and Finishing products are described in the spark.hheader file.

NOTE This list or the appearance of the cursors is subject to change in future releases.

sparkControlUpdate( )void sparkControlUpdate( int ControlNumber )

The sparkControlUpdate function forces Autodesk Visual Effects and Finishing products to redraw aspecific user interface control. This function is required; changing the value associated with a user interfacecontrol within the environment of Autodesk Visual Effects and Finishing products does not ensure that thecontrol will be redrawn. The sparkControlUpdate function acts as a type of callback within a callback,ensuring consistent updating of user interface controls. The ControlNumber parameter is the numberused to position the control; this number is associated with the control name. See Sparks User Interface onpage 15.

sparkReprocess( )void sparkReprocess( void )

The sparkReprocess function is useful in cases when a Sparks plug-in needs to reprocess the currentoutput frame after a user interface update. Typically, you use this with timewarp Sparks plug-ins wheremultiple input frames are used to create one output frame. If a user parameter is updated, thesparkReprocess function can force a reprocess, causing the Sparks plug-in to receive all input framesagain. The Sparks plug-in then generates a new output frame to appear in the image window.

sparkViewingDraw( )void sparkViewingDraw( void )

The sparkViewingDraw function refreshes the Channel Editor and image window. It also generates acall to SparkOverlay, when defined.

22 | Chapter 3 Sparks Utility Library

sparkMessageConfirm( )int sparkMessageConfirm( char *MessageString )

The sparkMessageConfirm function displays the text message supplied by MessageString in thedesktop message window and displays a Confirm button. This function returns 1 when the Confirm buttonis pressed.

sparkClipControlTitle( )void sparkClipControlTitle( SparkClipSelect Clip, char *Title )

The sparkClipControlTitle function lets a Sparks plug-in change default clip control titles. The clip(specified by an enumerator value defined in the spark.h header file) title is replaced with the new title.

sparkPointerRead( )int sparkPointerRead( void )

The sparkPointerRead function returns the pointer device pressure value.

sparkPointerWaitOff( )void sparkPointerWaitOff( void )

The sparkPointerWaitOff function waits and returns when 0 pressure is applied to the pointer device.

sparkPointerWaitOn( )void sparkPointerWaitOn( void )

The sparkPointerWaitOn function waits and returns when pressure is applied to the pointer device.

sparkQueryKeyMap( )int sparkQueryKeyMap( long Device )

The sparkQueryKeyMap function returns the logical state of a device you want to test. The Deviceparameter corresponds to the old device codes extracted from gl.h and device.h (on IrisGL systems).

sparkError( )void sparkError( char *ErrorString )

The sparkError function displays the error message supplied by ErrorString in the desktop messagewindow and aborts the current Sparks plug-in.

sparkMpFork( )void sparkMpFork( void (*Function()), int NumArgs, ... )

sparkMessageConfirm( ) | 23

The sparkMpFork function is used for multiprocessing a user-defined function. The Function argumentis the name of the function to be multiprocessed. The NumArgs argument specifies the number of argumentsrequired by the Function. The other arguments of sparkMpFork are the arguments of the function tobe multiprocessed; you can use a maximum of six arguments.

It is your responsibility to ensure that the task is correctly allocated to the different CPUs. The total numberof processors available for the task is contained in the NumProcessors field of the structureSparkInfoStruct, and can be extracted using the SparkInitialise function.

sparkMpInfo( )void sparkMpInfo( unsigned long *offset, unsigned long *pixels )

The sparkMpInfo function calculates an offset in the image buffer to be processed as well as the totalnumber of pixels to be processed. The calculation is based on the number of available processors and on theprocessor currently being used by the Sparks plug-in.

You should call the sparkMpInfo function from the function that is passed as the first argument of thesparkMpFork function.

sparkMpForkPixels( )void sparkMpForkPixels( void ( *Function ) ( ), ulong Pixels, int NumArgs,...)

The sparkMpForkPixels function is a subset of the sparkMpFork function. The Pixels argumentlets you determine how to divide pixels between processes.

sparkMpIsMainTask( )void sparkMpIsMainTask( void )

The sparkMpIsMainTask function will return TRUE when called from the main task and return FALSEotherwise. Tasks are usually created via calls to sparkMpFork, sparkMpForkPixels, orsparkMpCreateTask.

sparkProcessTruncate( )void sparkProcessTruncate( void )

You can use the sparkProcessTruncate function within the SparkProcess function to truncate acurrently processing clip.

sparkDisableParameter( )void sparkDisableParameter(int Type, int ControlNo)

The sparkDisableParameter function can be used to hide the UI parameter specified by ControlNoin the control page and the Channel Editor.

sparkEnableParameter( )void sparkEnableParameter(int Type, int ControlNo)


The sparkEnableParameter function can be used to show the UI parameter specified by ControlNoin the control page and the Channel Editor.

sparkControlTitle( )void sparkControlTitle(SparkControlSelect Control, char *Title)

The sparkControlTitle function can be used to rename the control page parameter identified byControl.

sparkResultClipName( )void sparkResultClipName(char *NewName)

The sparkResultClipName function can be used to set the name of the clip processed by a Sparksplug-in. By default, the Sparks plug-in will use the Sparks plug-in name as the clip name.

sparkPointerInfo( )float sparkPointerInfo(int *PX, int *PY)

The sparkPointerInfo( ) function can be used to get the current pointer device position. This functionreturns the current pointer pressure.

sparkGetViewerRatio( )float sparkGetViewerRatio(void)

The sparkGetViewerRatio( ) returns the current ratio value applied in the image window.

sparkFrameRate( )double sparkFrameRate( )

The sparkFrameRate( ) function returns the current video frame rate in frames per second.

sparkSetupControlUpdate ( )void sparkSetupControlUpdate( int ControlNo )

The sparkSetupControlUpdate function forces the application to redraw a specific user interface setupcontrol.

sparkFileBrowserDisplayLoad( )void sparkFileBrowserDisplayLoad( char *Path, char *Extension, void(*Callback) (char *FileName) )

The sparkFileBrowserDisplayLoad function displays the file browser and sets the current searchpath to Path. Extension is used to filter the file. Callback will be called on the user-selected file. Theselected file is passed as an argument to the callback.

sparkControlTitle( ) | 25

sparkFileBrowserDisplayLoadSequence( )void sparkFileBrowserDisplayLoadSequence( char *Path, char *Extension, void(*Callback) (char *FileName) )

The sparkFileBrowserDisplayLoadSequence function displays the file browser and sets the currentsearch path to Path, where the user can select multiple files. Extension is used to filter the file. The selectedfiles are passed as an argument to the Callback one by one; the Callback is called as many times asthere are selected files.

sparkFileBrowserDisplaySave( )void sparkFileBrowserDisplaySave( char *Path, char *Extension, void(*Callback) (char *FileName) )

The sparkFileBrowserDisplaySave function displays the file browser and sets the current searchpath to Path. Extension is used to filter the file. Callback will be called on the user-selected file. Theselected file is passed as an argument to the callback.

sparkFileCheckOverwrite( )int sparkFileCheckOverwrite( const char *Name )

The sparkFileCheckOverwrite function can be used within the sparkFileBrowserDisplayLoador sparkFileBrowserDisplaySave callbacks to prompt the user with the standard confirm message.

sparkFileHasExtension( )int sparkFileHasExtension(const char *File, const char *Extension)

The sparkFileHasExtension function returns 1 if File has an extension equal to Extension. Thisfunction is case sensitive. It returns 0 otherwise.

System FunctionsUse the system functions to bypass the sprocs, pcreate, fork, and exec calls that are no longeravailable.

sparkSystemSh( )int sparkSystemSh( int wait, const char *cmd )

The sparksSystemSh function is a wrapper to pcreatel(). If the wait argument is TRUE, the functionwill wait for the child process to complete before returning. The cmd argument will be passed to a subshell(/bin/sh), which will perform the path search—with wildcard expansion if required—as well as break up thecommand line into separate arguments to be passed to the process that has started.

sparkSystemNoSh( )int sparkSystemNoSh( int wait, const char *path, const char **argv )


The sparksSystemNoSh function is a wrapper to pcreatev(). If the wait argument is TRUE, thefunction will wait for the child process to complete before returning. The path argument points to theexecutable. The argv argument is a pointer to an array of strings representing the parameters to thesubprocess. Usually argv[0] is the path to the executable; no path searching is done and no wildcardexpansion is performed.

NOTE The last entry in argv[] should be a zero to indicate its end.

sparkWaitpid( )int sparkWaitpid( pid_t pid, int *statptr, int option )

The sparksWaitpid function is a wrapper to waitpid(). The pid argument—if used with a FALSEwait argument—is the value returned from the sparksSystemSh or sparksSystemNoSh functions.If the statptr argument is non-zero, 16 bits of information called “status” are stored in the low-order 16bits of the memory location that the statptr argument points to. Use the wstat Unix command formore information. The options argument is constructed from the bitwise inclusive “OR” of zero or more ofthe “WNOHANG” and “WUNTRACED” flags.

Memory FunctionsUse the memory functions to register buffers, set information based on the type of buffer, and estimate thenumber of buffers that the system can accommodate.

sparkMemRegisterBuffer( )int sparkMemRegisterBuffer( void )

The sparkMemRegisterBuffer function registers Autodesk Visual Effects and Finishing product-sizedbuffers. The buffer definition corresponds to one of the structures defined in the spark.h header file. The sizeof registered buffers is determined by the current resolution and current bit depth of the Sparks plug-in. Ifthe output resolution or bit depth of the Sparks plug-in changes, existing memory buffers will be deletedand new ones registered. The function returns the buffer ID.

NOTE Because the input and output resolution of the Sparks plug-in can change, memory buffers are not validacross resolution changes and cached pointers cannot be relied on to point to valid data.

WARNING Image buffers should be requested through the memory management system of Autodesk VisualEffects and Finishing products using API calls. As of Inferno 5.0, Flame 8.0, Flint 8.0, Smoke 5.2, the use of dynamicmemory allocation of image buffers through malloc, new, or other similar functions is strongly discouraged. Ifthe memory management of the Autodesk Visual Effects and Finishing product cannot satisfy a request for memory,calls to malloc, new, or other similar functions are unlikely to succeed. Immediate and violent program terminationmay ensue; however, you can use dynamic memory allocation for runtime objects and data structures.

sparkMemRegisterBufferSize( )int sparkMemRegisterBufferSize( unsigned long size )

The sparkMemRegisterBufferSize function registers a buffer of the specified size. The function returnsthe buffer ID.

sparkWaitpid( ) | 27

sparkMemRegisterBufferFmt( )int sparkMemRegisterBufferFmt( int width, int height,SparkBufferFmt )

The sparkMemRegisterBufferFmt function registers a buffer of the specified format. The functionreturns the buffer ID.

sparkMemGetBuffer( )int sparkMemGetBuffer( int id, SparkMemBufStruct *memBufInfo )

When passed the ID of a registered buffer and a SparkMemBufStruct, this function will set all theinformation relative to this buffer. This function returns 1 if successful.

sparkMemGetFreeMemory( )int sparkMemGetFreeMemory( )

The sparkaMemGetFreeMemory function returns an estimate of the maximum number of AutodeskVisual Effects and Finishing product-sized memory buffers that can be locked at the same time by a Sparksplug-in.

NOTE Depending on which type of sparkMemRegisterBuffer is used, Autodesk Visual Effects and Finishingproducts will provide more or less information in the SparkMemBufStruct with a buffer. TheSparkBufferFmt and SparkMemBufStruct fields used by the Memory functions are defined i

autodesk developer network api reference guide...the sparks api is maintained for upwards...

Documents