Skip to content

HCPP platform view overlays elements it shouldn't when native view is a SurfaceView #175546

Closed

Description

@gmackall

See the video.

Discovered while testing the video_player_android example app, modified with the code from #164899

hcpp_sroll_problems.mp4

Activity

  1. added
    team-androidOwned by Android platform team
    platform-views: hcppIssues which affect the HCPP platform views backend
    P1High-priority issues at the top of the work list
    triaged-androidTriaged by Android platform team
    on Sep 17, 2025
  2. stuartmorgan-g commented on Sep 17, 2025

    @stuartmorgan-g
    Contributor

    and disappears before fully off screen

    This part of the video is correct behavior though, isn't it? If the video should be under the secondary toolbar (the one for display type), then the point where it's disappearing is when it scrolls exactly enough that it's fully obscured.

  3. gmackall commented on Sep 17, 2025

    @gmackall
    MemberAuthor

    and disappears before fully off screen

    This part of the video is correct behavior though, isn't it? If the video should be under the secondary toolbar (the one for display type), then the point where it's disappearing is when it scrolls exactly enough that it's fully obscured.

    Ah good point, yes that's probably correct! Updated title to reflect

  4. changed the title [-]HCPP platform view overlays elements it shouldn't, and disappears before fully off screen[/-] [+]HCPP platform view overlays elements it shouldn't[/+] on Sep 17, 2025
  5. self-assigned this
    on Sep 17, 2025
  6. gmackall commented on Nov 25, 2025

    @gmackall
    MemberAuthor

    I've spent quite a while looking in to this - the problem here seems to be that HCPP does not currently respect (at least clipping) mutators when the native view is a SurfaceView (which is what the platform view implementation of video_player uses on Android).

    For example, modifying the native view used by the existing clippath integration test to use a SurfaceView

    Code
    // Copyright 2014 The Flutter Authors. All rights reserved.
    // Use of this source code is governed by a BSD-style license that can be
    // found in the LICENSE file.
    
    @file:Suppress("PackageName")
    
    package com.example.android_engine_test.fixtures
    
    import android.content.Context
    import android.graphics.Color
    import android.graphics.Paint
    import android.view.SurfaceHolder
    import android.view.SurfaceView // Changed from View
    import android.view.View
    import android.view.ViewGroup
    import io.flutter.plugin.platform.PlatformView
    import io.flutter.plugin.platform.PlatformViewFactory
    
    class ChangingColorButtonPlatformViewFactory : PlatformViewFactory(null) {
        override fun create(
            context: Context,
            viewId: Int,
            args: Any?
        ): PlatformView = ChangingColorButtonPlatformView(context)
    }
    
    private class ChangingColorButtonPlatformView(
        context: Context
    ) : SurfaceView(context), // Extend SurfaceView
        PlatformView,
        SurfaceHolder.Callback { // Implement Callback to listen for surface availability
    
        private val paintRed =
            Paint().apply {
                color = Color.RED
                style = Paint.Style.FILL
            }
        private val paintBlue =
            Paint().apply {
                color = Color.BLUE
                style = Paint.Style.FILL
            }
    
        private var isBlue = false
    
        init {
            layoutParams =
                ViewGroup.LayoutParams(
                    ViewGroup.LayoutParams.MATCH_PARENT,
                    ViewGroup.LayoutParams.MATCH_PARENT
                )
    
            contentDescription = "Change color"
    
            // Register the callback to know when the surface is created
            holder.addCallback(this)
    
            setOnClickListener {
                isBlue = !isBlue
                drawSurface() // Manually trigger the draw routine
            }
        }
    
        // Helper function to handle SurfaceView drawing mechanics
        private fun drawSurface() {
            // Ensure the surface is valid before trying to draw
            if (holder.surface.isValid) {
                // 1. Lock the canvas
                val canvas = holder.lockCanvas()
                
                // 2. Perform drawing
                if (canvas != null) {
                    canvas.drawColor(Color.WHITE) // Clear previous drawing (optional but recommended)
                    canvas.drawRect(
                        0f, 
                        0f, 
                        width.toFloat(), 
                        height.toFloat(), 
                        if (isBlue) paintBlue else paintRed
                    )
                    
                    // 3. Unlock and post the canvas to display it
                    holder.unlockCanvasAndPost(canvas)
                }
            }
        }
    
        override fun getView(): View = this
    
        override fun dispose() {
            // Clean up callbacks to prevent memory leaks
            holder.removeCallback(this)
        }
    
        // --- SurfaceHolder.Callback Implementation ---
    
        override fun surfaceCreated(holder: SurfaceHolder) {
            // The surface is ready, perform the initial draw
            drawSurface()
        }
    
        override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) {
            // If dimensions change, redraw to fit new bounds
            drawSurface()
        }
    
        override fun surfaceDestroyed(holder: SurfaceHolder) {
            // Surface is gone, stop any active rendering threads here if you had them
        }
    }

    We can see that HC mode still clips properly (red is pv, green is content behind pv):
    Image

    But HCPP does not

    Image

    This is causing this bad overlay because the mechanism that the engine is using to prevent this overlay in this case is a clip rect, and it's not being respected (determined from logging).

  7. gmackall commented on Nov 25, 2025

    @gmackall
    MemberAuthor

    Looks like we can fix this by applying the clip via a transaction in onDisplayPlatformView, extremely roughly:

          if (Build.VERSION.SDK_INT >= API_LEVELS.API_29 && view instanceof SurfaceView) {
            SurfaceView surfaceView = (SurfaceView) view;
            SurfaceControl sc = surfaceView.getSurfaceControl();
    
            if (sc != null && sc.isValid()) {
              SurfaceControl.Transaction tx = new SurfaceControl.Transaction();
    
              // 1. HANDLE OPACITY
              // Apply the accumulated opacity from the stack to the Surface layer.
              tx.setAlpha(sc, mutatorsStack.getFinalOpacity());
    
              // 2. HANDLE CLIPPING (RECT, RRECT, PATH, TRANSFORM)
              // We start with the view's final on-screen bounds.
              RectF screenRectF = new RectF(x, y, x+width, y+height);
              Rect screenRect = new Rect();
              screenRectF.roundOut(screenRect);
              
              List<Path> clippingPaths = mutatorsStack.getFinalClippingPaths();
    
              if (clippingPaths != null && !clippingPaths.isEmpty()) {
                RectF pathBounds = new RectF();
                for (Path path : clippingPaths) {
                  // Compute the axis-aligned bounding box of the path.
                  path.computeBounds(pathBounds, true);
    
                  // Round out to ensure we cover the pixels (ceil/floor logic).
                  Rect pathRectInt = new Rect();
                  pathBounds.roundOut(pathRectInt);
    
                  // Intersect the current visible area with this clip.
                  // If the path is a complex shape (star, rounded rect), this
                  // constrains the surface to the bounding box of that shape.
                  screenRect.intersect(pathRectInt);
                }
              }
    
              // 3. CONVERT TO LOCAL SURFACE COORDINATES
              // SurfaceControl.setCrop expects coordinates relative to the Surface (0,0).
              // We shift the calculated screen-space rect by the view's origin (-x, -y).
              screenRect.offset(-x, -y);
              if (screenRect.width() < 0 || screenRect.height() < 0) {
                screenRect.setEmpty();
              }
    
              // Send the command to SurfaceFlinger.
                if (Build.VERSION.SDK_INT >= API_LEVELS.API_33) {
                    tx.setCrop(sc, screenRect);
                    Log.e("HI GRAY", "final computed screenrect is " + screenRect);
                }
    
                // 5. SYNC WITH FRAME
              // Apply this transaction as part of the ViewRoot's draw cycle to prevent
              // visual tearing/jitter during scrolling.
                if (Build.VERSION.SDK_INT >= API_LEVELS.API_33) {
                    flutterView.getRootSurfaceControl().applyTransactionOnDraw(tx);
                }
            }
          }

    Still want to know why the application of FlutterMutatorView.draw() is bypassed when the android view is a SurfaceView, but it certainly seems like that is what is happening here, and that we will need to mirror the application of those graphical modifications somehow. Unfortunately, while direct modification with transactions gives us access to opacity and cliprect, there don't seem to be apis that would apply non rect clipping. Not sure if this is a critical feature that the engine expects to be present outside of use of the specific ClipPath, etc, widgets.

  8. changed the title [-]HCPP platform view overlays elements it shouldn't[/-] [+]HCPP platform view overlays elements it shouldn't when native view is a `SurfaceView`[/+] on Mar 18, 2026
  9. gmackall commented on Apr 1, 2026

    @gmackall
    MemberAuthor

    Some additional thoughts on the fix here, clipping as applied in my previous comment seems to not work exactly when it happens at the same time as a widget tree change - if, say, you apply a clip rect by adding it as a widget wrapping the platform view.

    This is because the view has a null surfacecontrol because it just got deleted and recreated. We can fix this by applying a callback which applies the crop and then schedules a frame:

            SurfaceControl sc = surfaceView.getSurfaceControl();
            if (sc == null) {
                SurfaceHolder.Callback cb = new SurfaceHolder.Callback() {
                    @Override
                    public void surfaceChanged(@NonNull SurfaceHolder holder, int format, int width, int height) {
    
                    }
    
                    @Override
                    public void surfaceCreated(@NonNull SurfaceHolder holder) {
                        SurfaceControl.Transaction tx = createTransaction();
                        tx.setCrop(surfaceView.getSurfaceControl(), screenRect);
                        Log.e("HI GRAY", "applying clip late");
                        Log.e("HI GRAY", "final computed screenrect is " + screenRect); // TODO remove
                        flutterJNI.scheduleFrame();
                    }
    
                    @Override
                    public void surfaceDestroyed(@NonNull SurfaceHolder holder) {
    
                    }
                };
                surfaceView.getHolder().addCallback(cb);
                Log.e("HI GRAY", "we are returning early, maybe concerning??");
                return;
            }

    Some more thoughts from working on the repro:

    1. I think the code above might have an off by one error in the calculation of the rect, because I can see a tiny green line on the right where the widget behind the pv is peeking through
    2. There is a visual flicker when the view gets destroyed and recreated by widget tree changes. This does not happen with HC actually, it does, but maybe it's less somehow? it seems harder to see... I think we are doing something wrong for one frame there, need to figure out what
  10. github-actions commented on Apr 20, 2026

    @github-actions

    This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.

  11. locked as resolved and limited conversation to collaborators on Apr 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P1High-priority issues at the top of the work listplatform-androidAndroid applications specificallyplatform-views: hcppIssues which affect the HCPP platform views backendteam-androidOwned by Android platform teamtriaged-androidTriaged by Android platform team

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions