JOMUCOPYOPENMAX intro.docx

JOMUCOPYOPENMAX intro.docx

《JOMUCOPYOPENMAX intro.docx》由会员分享，可在线阅读，更多相关《JOMUCOPYOPENMAX intro.docx（17页珍藏版）》请在冰点文库上搜索。

JOMUCOPYOPENMAXintro

OpenMAXALforAndroid

ThisarticledescribestheAndroidnativemultimediaAPIsbasedontheKhronosGroupOpenMAXAL™1.0.1standard,asofAndroidAPIlevel14（Androidplatformversion4.0）andhigher.

OpenMAXALisacompanionAPItoOpenSLES,butformultimedia（videoandaudio）ratherthanaudioonly.

Android4.0providesadirect,efficientpathforlow-levelstreamingmultimedia.Thenewpathisidealforapplicationsthatneedtomaintaincompletecontrolovermediadatabeforepassingittotheplatformforpresentation.Forexample,mediaapplicationscannowretrievedatafromanysource,applyproprietaryencryption/decryption,andthensendthedatatotheplatformfordisplay.

Applicationscannowsendprocesseddatatotheplatformasamultiplexedstreamofaudio/videocontentinMPEG-2transportstreamformat.Theplatformde-muxes,decodes,andrendersthecontent.Theaudiotrackisrenderedtotheactiveaudiodevice,whilethevideotrackisrenderedtoeitheraSurfaceoraSurfaceTexture.WhenrenderingtoaSurfaceTexture,theapplicationcanapplysubsequentgraphicseffectstoeachframeusingOpenGL.

OpenMAXALprovidesaClanguageinterfacethatisalsocallablefromC++,andexposesfeaturessimilartotheseAndroidAPIscallablefromJavaprogramminglanguagecode:

∙android.media.MediaPlayer

AswithalloftheAndroidNativeDevelopmentKit（NDK）,theprimarypurposeofOpenMAXALforAndroidistofacilitatetheimplementationofsharedlibrariestobecalledfromJavaprogramminglanguagecodeviaJavaNativeInterface（JNI）.NDKisnotintendedforwritingpureC/C++applications.

Note:

thoughbasedonOpenMAXAL,theAndroidnativemultimediaAPIis not aconformingimplementationofeitherOpenMAXAL1.0.1profile（mediaplayerormediaplayer/recorder）.ThisisbecauseAndroiddoesnotimplementallofthefeaturesrequiredbyeitheroftheprofiles.AnyknowncaseswhereAndroidbehavesdifferentlythanthespecificationaredescribedinsection"Androidextensions"below.TheAndroidOpenMAXALimplementationhaslimitedfeatures,andisintendedprimarilyforcertainperformance-sensitivenativestreamingmultimediaapplicationssuchasvideoplayers.

ThemajorfeatureistheabilitytoplayanMPEG-2transportstreamcontainingasingleprogramstreammadeupofoneH.264videoelementarystreamandoneAACaudioelementarystream.TheapplicationprovidesthestreamviaanAndroidbufferqueuedatasource,whichisbasedontheOpenSLESbufferqueueconceptandAndroid-specificextensions.

Thevideosinkisan ANativeWindow* abstracthandle,derivedfroman android.view.Surface （"surface"）.ASurfacefrom SurfaceHolder.getSurface（） shouldbeusedwhendisplayinganunalteredvideowithinafixedSurfaceViewframe.ASurfacefrom newSurface（SurfaceTexture） allowsstreamingthedecodedvideoframestoanOpenGLES2.0texture,wheretheframescanbeusedasinputtoashaderalgorithmintheGraphicsProcessingUnit（GPU）.Besureto release（） theSurfaceassoonaspossibleaftercalling setSurface orANativeWindow_fromSurface.

Theaudiosinkisalwaysanoutputmix,adevice-independentmixerobjectsimilartothatofOpenSLES.

Gettingstarted

Examplecode

Recommended

Supportedandtestedexamplecode,usableasamodelforyourowncode,islocatedinNDKfolder platforms/android-14/samples/native-media/.

Notrecommended

TheOpenMAXAL1.0.1specificationcontainsexamplecodeintheappendices（seesection"References"belowforthelinktothisspecification）.However,theexamplesinAppendixD:

SampleCodeusefeaturesnotsupportedbyAndroid.Someexamplesalsocontaintypographicalerrors,oruseAPIsthatarelikelytochange.Proceedwithcautioninreferringtothese;thoughthecodemaybehelpfulinunderstandingthefullOpenMAXALstandard,itshouldnotbeusedasiswithAndroid.

AddingOpenMAXALtoyourapplicationsourcecode

OpenMAXALisaCAPI,butiscallablefrombothCandC++code.

Addthefollowinglinestoyourcode:

#include

#include

Makefile

ModifyyourAndroid.mkasfollows:

LOCAL_LDLIBS+=libOpenMAXAL

Multimediacontent

TheonlysupportedwaytosupplymultimediacontentisviaanMPEG-2transportstream.

Findingorcreatingusefulmultimediacontentforyourapplicationisbeyondthescopeofthisarticle.

Notethatitisyourresponsibilitytoensurethatyouarelegallypermittedtoplaythecontent.

Debugging

Forrobustness,werecommendthatyouexaminethe XAresult valuewhichisreturnedbymostAPIs.Useof assert vs.moreadvancederrorhandlinglogicisamatterofcodingstyleandtheparticularAPI;seetheWikipediaarticleon assert formoreinformation.Inthesuppliedexample,wehaveused assert for"impossible"conditionswhichwouldindicateacodingerror,andexpliciterrorhandlingforotherswhicharemorelikelytooccurinproduction.

ManyAPIerrorsresultinalogentry,inadditiontothenon-zeroresultcode.TheselogentriesprovideadditionaldetailwhichcanbeespeciallyusefulforthemorecomplexAPIssuchas Engine:

:

CreateMediaPlayer.

Use adblogcat,the EclipseADTplugin LogCatpane,or ddmslogcat toseethelog.

SupportedfeaturesfromOpenMAXAL1.0.1

Thissectionsummarizesavailablefeatures.Insomecases,therearelimitationswhicharedescribedinthenextsub-section.

Globalentrypoints

Supportedglobalentrypoints:

∙xaCreateEngine

∙xaQueryNumSupportedEngineInterfaces

∙xaQuerySupportedEngineInterfaces

Objectsandinterfaces

ThefollowingfigureindicatesobjectsandinterfacessupportedbyAndroid'sOpenMAXALimplementation.Agreencellmeansthefeatureissupported.

Limitations

Thissectiondetailslimitationswithrespecttothesupportedobjectsandinterfacesfromtheprevioussection.

Audio

Theaudiostreamtypecannotbeconfigured;itisalways AudioManager.STREAM_MUSIC.

Effectsarenotsupported.

Dynamicinterfacemanagement

RemoveInterface and ResumeInterface arenotsupported.

Engine

Supported:

∙CreateMediaPlayer

Notsupported:

∙CreateCameraDevice

∙CreateRadioDevice

∙CreateLEDDevice

∙CreateVibraDevice

∙CreateMetadataExtractor

∙CreateExtensionObject

∙GetImplementationInfo

For CreateMediaPlayer,theserestrictionsapply:

∙audiosinkisanoutputmixdatalocator

∙videosinkisanativedisplaydatalocator

∙soundbank,LEDarray,andvibrasinksmustbe NULL

MIMEdataformat

InthecurrentAndroidimplementationofOpenMAXAL,amediaplayerreceivesitssourcedataasanMPEG-2transportstreamviaabufferqueue.

Thesourcedatalocatormustbe XA_DATALOCATOR_ANDROIDBUFFERQUEUE （see"Androidextensions"below）.

Thesourcedataformatmustbe XADataFormat_MIME.Initialize mimeType to XA_ANDROID_MIME_MP2TS,and containerType to XA_CONTAINERTYPE_MPEG_TS.

ThecontainedtransportstreammusthaveasingleprogramwithoneH.264videoelementarystreamandoneAACaudioelementarystream.

Object

Resume, RegisterCallback, AbortAsyncOperation, SetPriority, GetPriority,and SetLossOfControlInterfaces arenotsupported.

StreamInformation

UsetheStreamInformationinterfaceonamediaplayerobjecttodiscoverwhenthevideometrics（height/widthoraspectratio）areavailableorchanged,andtothengetthesizes.

Supported:

∙RegisterStreamChangeCallback

∙QueryMediaContainerInformation

∙QueryStreamInformation

∙QueryStreamType

Notsupported:

∙QueryActiveStreams

∙QueryStreamName

∙SetActiveStream

VideoDecoderCapabilities

Thisinterfaceontheengineobjectreportsvideodecodercapabilitieswithoutinterpretation,exactlyasclaimedbytheunderlyingOpenMAXILimplementation.

Thesefieldsin XAVideoCodecDescriptor arefilled:

∙codecId

∙profileSetting

∙levelSetting

Theotherfieldsarenotfilledandshouldbeignored.

Applicationsshouldrelyonthecapabilitiesdocumentedat AndroidSupportedMediaFormats,nottheinformationreportedbythisinterface.

Datastructures

AndroidAPIlevel14supportstheseOpenMAXAL1.0.1datastructures:

∙XADataFormat_MIME

∙XADataLocator_NativeDisplay

∙XADataLocator_OutputMix

∙XADataSink

∙XADataSource

∙XAEngineOption

∙XAInterfaceID

∙XAMediaContainerInformation

∙XANativeHandle

∙XA*StreamInformation

∙XAVideoCodecDescriptor

XADataLocator_NativeDisplay

Thenativedisplaydatalocatorisusedtospecifythevideosink:

typedefstructXADataLocator_NativeDisplay_{

XAuint32locatorType;//XA_DATALOCATOR_NATIVEDISPLAY

XANativeHandlehWindow;//ANativeWindow*

XANativeHandlehDisplay;//NULL

}XADataLocator_NativeDisplay;

Setthe hWindow fieldtoan ANativeWindow* andset hDisplay to NULL.Youcangeta ANativeWindow* handlefroman android.view.Surface,usingthisNDKfunction:

#include

ANativeWindow*ANativeWindow_fromSurface（JNIEnv*env,jobjectsurface）;

Don'tforgettofreethishandleinyourshutdowncodewith ANativeWindow_release.

Platformconfiguration

OpenMAXALforAndroidisdesignedformulti-threadedapplications,andisthread-safe.

OpenMAXALforAndroidsupportsasingleengineperapplication,andupto32objects.AvailabledevicememoryandCPUmayfurtherrestricttheusablenumberofobjects.

xaCreateEngine recognizes,butignores,theseengineoptions:

∙XA_ENGINEOPTION_THREADSAFE

∙XA_ENGINEOPTION_LOSSOFCONTROL

OpenMAXALandOpenSLESmaybeusedtogetherinthesameapplication.Inthiscase,thereisinternallyasinglesharedengineobject,andthe32objectlimitissharedbetweenOpenMAXALandOpenSLES.Theapplicationshouldfirstcreatebothengines,thenusebothengines,andfinallydestroybothengines.Theimplementationmaintainsareferencecountonthesharedengine,sothatitiscorrectlydestroyedattheseconddestroy.

Planningforfutur