Tipi di superfici

Questa pagina descrive i diversi tipi di superfici che possono essere utilizzati per la riproduzione video con Media3 e come scegliere il tipo giusto per il tuo caso d'uso. Per scoprire di più sugli oggetti Surface in Android, leggi questa documentazione sulla grafica.

Impostare la superficie

Esistono quattro punti di accesso per Player per collegare l'uscita video a un Surface:

• void setVideoSurface(@Nullable Surface surface)
• void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void setVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void setVideoTextureView(@Nullable TextureView textureView)

Esistono anche diversi modi per cancellarla:

• void clearVideoSurface()
• void clearVideoSurface(@Nullable Surface surface)
• void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder)
• void clearVideoSurfaceView(@Nullable SurfaceView surfaceView)
• void clearVideoTextureView(@Nullable TextureView textureView)

Scegli un tipo di superficie per PlayerView

L'attributo surface_type di PlayerView consente di impostare il tipo di superficie utilizzata per la riproduzione video. I valori consentiti sono:

• surface_view (SurfaceView)
• texture_view (TextureView)
• spherical_gl_surface_view (SphericalGLSurfaceView) - per la riproduzione di video sferici
• video_decoder_gl_surface_view (VideoDecoderGLSurfaceView) - rendering video utilizzando i renderer delle estensioni
• none, che serve solo per la riproduzione audio e deve essere utilizzato per evitare di dover creare una superficie, perché può essere costoso.

Se la visualizzazione è per la normale riproduzione video, devono essere utilizzati surface_view o texture_view. SurfaceView offre una serie di vantaggi rispetto a TextureView per la riproduzione video:

• Consumo energetico notevolmente inferiore su molti dispositivi.
• Maggiore precisione nella sincronizzazione dei frame, per una riproduzione video più fluida.
• Supporto per l'output video HDR di qualità superiore sui dispositivi idonei.
• Supporto dell'output sicuro durante la riproduzione di contenuti protetti da DRM.
• La possibilità di eseguire il rendering dei contenuti video alla risoluzione completa del display sui dispositivi Android TV che aumentano la risoluzione del livello UI.

Pertanto, SurfaceView deve essere preferito a TextureView, se possibile. TextureView deve essere utilizzato solo se SurfaceView non soddisfa le tue esigenze. Un esempio è quello in cui sono richieste animazioni fluide o lo scorrimento della superficie video prima di Android 7.0 (livello API 24), come descritto nelle note seguenti. In questo caso, è preferibile utilizzare TextureView solo quando SDK_INT è inferiore a 24 (Android 7.0) e SurfaceView altrimenti.

Nota: il rendering di SurfaceView non è stato sincronizzato correttamente con le animazioni delle visualizzazioni fino ad Android 7.0 (livello API 24). Nelle versioni precedenti, una sincronizzazione impropria poteva causare effetti indesiderati quando un SurfaceView veniva inserito in un contenitore a scorrimento o quando veniva animato. Gli effetti indesiderati includevano il contenuto della visualizzazione che sembrava leggermente in ritardo rispetto a dove doveva essere visualizzato e la visualizzazione che diventava nera quando animata. Per ottenere un'animazione o uno scorrimento fluido del video prima di Android 7.0, utilizza TextureView anziché SurfaceView.

Nota: il ciclo di vita della superficie di un SurfaceView è legato alla visibilità della visualizzazione, mentre il ciclo di vita della superficie di un TextureView è legato all'associazione e al distacco della finestra. Pertanto, nelle UI a scorrimento che utilizzano SurfaceView, l'avvio della riproduzione può richiedere più tempo perché la superficie di output diventa disponibile leggermente dopo. A partire da Android 14, PlayerView utilizza SurfaceView.setSurfaceLifecycle(SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT) per evitare questo comportamento. Se la tua app utilizza SurfaceView direttamente (senza PlayerView), ti consigliamo di attivare questa modalità. Prima di Android 14, è possibile aggirare la distruzione della superficie traducendo le visualizzazioni fuori dallo schermo quando vengono riciclate.

Nota: alcuni dispositivi Android TV eseguono il livello UI a una risoluzione inferiore rispetto alla risoluzione completa del display, eseguendo l'upscaling per la presentazione all'utente. Ad esempio, il livello UI potrebbe essere eseguito a 1080p su un'Android TV con un display 4K. Su questi dispositivi, SurfaceView deve essere utilizzato per il rendering dei contenuti alla risoluzione completa del display. È possibile eseguire query sulla risoluzione completa del display (nella modalità di visualizzazione corrente) utilizzando Util.getCurrentDisplayModeSize. La risoluzione del livello UI può essere interrogata utilizzando l'API Display.getSize di Android.

Nota: se utilizzi PlayerView all'interno di AndroidView, non possiamo garantire la compatibilità perché PlayerView non è stato creato pensando a Compose. Uno dei problemi comuni per SDK_INT == 34 è una superficie allungata/ritagliata/trapelata che non corrisponde correttamente al contenitore principale (AspectRatioFrameLayout). Puoi attivare una soluzione alternativa per Compose chiamando PlayerView.setEnableComposeSurfaceSyncWorkaround, ma tieni presente che causa problemi con le transizioni condivise basate su XML.

Scegliere un tipo di superficie in Crea

In Compose, la soluzione di interoperabilità utilizza il componibile AndroidView per eseguire il wrapping di SurfaceView e TextureView. I due composable corrispondenti sono AndroidExternalSurface e AndroidEmbeddedExternalSurface di androidx.compose.foundation. Tuttavia, queste classi proxy forniscono una superficie API che limita l'accesso alle visualizzazioni sottostanti. Queste visualizzazioni sono necessarie al Player per gestire un ciclo di vita completo della superficie (creazione e aggiornamenti delle dimensioni).

Nel modulo media3-ui-compose, puoi trovare i composable ContentFrame e PlayerSurface che collegano Player a un Surface in modo consapevole del ciclo di vita. I tipi di superficie in questo caso sono:

• androidx.media3.ui.compose.SURFACE_TYPE_SURFACE_VIEW
• androidx.media3.ui.compose.SURFACE_TYPE_TEXTURE_VIEW

Non esiste il tipo none, poiché corrisponderebbe a non includere il componente componibile nell'albero dell'interfaccia utente di Compose.