Skip to content

Commit a0ebb8e

Browse files
author
Sushil Nath
committed
PendingFrameCapture - a place holder for a future FrameCapture
This will be needed to support non suspending Frame captures via FrameGraph. PendingFrameCapture can be used to provide a handle to a concrete FrameCapture which may be available in the future as camera resources become available to handle the Frame capture request. Reference: https://android-review.git.corp.google.com/c/platform/frameworks/support/+/3934512 Test: unit tests Change-Id: Iacb9343b076e9dba77dc841fd6afc7ee1f1374d7
1 parent 2715dde commit a0ebb8e

2 files changed

Lines changed: 295 additions & 0 deletions

File tree

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
/*
2+
* Copyright 2026 The Android Open Source Project
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package androidx.camera.camera2.pipe.framegraph
18+
19+
import androidx.annotation.GuardedBy
20+
import androidx.camera.camera2.pipe.Frame
21+
import androidx.camera.camera2.pipe.FrameCapture
22+
import androidx.camera.camera2.pipe.OutputStatus
23+
import androidx.camera.camera2.pipe.Request
24+
import kotlinx.coroutines.CompletableDeferred
25+
import kotlinx.coroutines.ExperimentalCoroutinesApi
26+
27+
/**
28+
* Placeholder for [FrameCapture] of a Frame request that may be fulfilled at a later point in time.
29+
*/
30+
@OptIn(ExperimentalCoroutinesApi::class)
31+
internal class PendingFrameCapture(override val request: Request) : FrameCapture {
32+
private val lock = Any()
33+
34+
// The type is chosen to be null in order to allow cancellation and not throw exception when
35+
// waiting for it to complete. This choice is made to keep the usage of FrameCapture via
36+
// PendingFrameCapture clean for the clients. The status of close/abort can be always queried
37+
// from the status field of PendingFrameCapture.
38+
private val deferred = CompletableDeferred<FrameCapture?>()
39+
40+
@GuardedBy("lock") private var closed = false
41+
@GuardedBy("lock") private var aborted = false
42+
@GuardedBy("lock") private var pendingListeners: MutableList<Frame.Listener>? = mutableListOf()
43+
44+
fun setFrameCapture(frameCapture: FrameCapture) {
45+
val listeners: List<Frame.Listener>?
46+
synchronized(lock) {
47+
if (closed || aborted) {
48+
frameCapture.close()
49+
return
50+
}
51+
52+
if (!deferred.complete(frameCapture)) {
53+
frameCapture.close()
54+
return
55+
}
56+
listeners = pendingListeners
57+
pendingListeners = null
58+
}
59+
60+
if (listeners != null) {
61+
for (listener in listeners) {
62+
frameCapture.addListener(listener)
63+
}
64+
}
65+
}
66+
67+
override val status: OutputStatus
68+
get() =
69+
synchronized(lock) {
70+
if (deferred.isCompleted) {
71+
deferred.getCompleted()?.let {
72+
return it.status
73+
}
74+
}
75+
return when {
76+
aborted -> OutputStatus.ERROR_OUTPUT_ABORTED
77+
closed -> OutputStatus.UNAVAILABLE
78+
else -> OutputStatus.PENDING
79+
}
80+
}
81+
82+
override suspend fun awaitFrame(): Frame? {
83+
return deferred.await()?.awaitFrame()
84+
}
85+
86+
override fun getFrame(): Frame? {
87+
return if (deferred.isCompleted) deferred.getCompleted()?.getFrame() else null
88+
}
89+
90+
override fun addListener(listener: Frame.Listener) {
91+
val frameCapture: FrameCapture?
92+
synchronized(lock) {
93+
if (closed || aborted) {
94+
listener.onFrameComplete()
95+
return
96+
}
97+
if (!deferred.isCompleted) {
98+
pendingListeners?.add(listener)
99+
return
100+
}
101+
frameCapture = deferred.getCompleted()
102+
}
103+
// If deferred FrameCapture was completed, then attach the listener directly to the source.
104+
// In case it is null, the (closed || aborted) state must be true and listener will be
105+
// completed in the above.
106+
frameCapture?.addListener(listener)
107+
}
108+
109+
override fun close() {
110+
terminate(asClosed = true)
111+
}
112+
113+
fun abort() {
114+
terminate(asClosed = false)
115+
}
116+
117+
private fun terminate(asClosed: Boolean) {
118+
val frameCapture: FrameCapture?
119+
val listeners: List<Frame.Listener>?
120+
synchronized(lock) {
121+
if (closed || aborted) return
122+
if (asClosed) closed = true else aborted = true
123+
124+
// Complete the deferred with null so that awaitFrame method doesn't block when this
125+
// PendingFrameCapture is closed before the actual FrameCapture is set.
126+
deferred.complete(null)
127+
128+
listeners = pendingListeners.also { pendingListeners = null }
129+
frameCapture = deferred.getCompleted()
130+
}
131+
if (listeners != null) {
132+
for (listener in listeners) {
133+
listener.onFrameComplete()
134+
}
135+
}
136+
frameCapture?.close()
137+
}
138+
}
Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
/*
2+
* Copyright 2026 The Android Open Source Project
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package androidx.camera.camera2.pipe.framegraph
18+
19+
import androidx.camera.camera2.pipe.Frame
20+
import androidx.camera.camera2.pipe.FrameCapture
21+
import androidx.camera.camera2.pipe.OutputStatus
22+
import androidx.camera.camera2.pipe.Request
23+
import androidx.camera.camera2.pipe.testing.RobolectricCameraPipeTestRunner
24+
import com.google.common.truth.Truth.assertThat
25+
import kotlinx.coroutines.ExperimentalCoroutinesApi
26+
import kotlinx.coroutines.launch
27+
import kotlinx.coroutines.test.advanceUntilIdle
28+
import kotlinx.coroutines.test.runTest
29+
import org.junit.Test
30+
import org.junit.runner.RunWith
31+
import org.mockito.kotlin.mock
32+
import org.mockito.kotlin.never
33+
import org.mockito.kotlin.verify
34+
import org.mockito.kotlin.whenever
35+
import org.robolectric.annotation.Config
36+
37+
@OptIn(ExperimentalCoroutinesApi::class)
38+
@RunWith(RobolectricCameraPipeTestRunner::class)
39+
@Config(sdk = [Config.ALL_SDKS])
40+
class PendingFrameCaptureTest {
41+
private val request = Request(streams = emptyList())
42+
private val pendingFrameCapture = PendingFrameCapture(request)
43+
44+
@Test
45+
fun initialStatusIsPending() {
46+
assertThat(pendingFrameCapture.status).isEqualTo(OutputStatus.PENDING)
47+
assertThat(pendingFrameCapture.getFrame()).isNull()
48+
}
49+
50+
@Test
51+
fun setFrameCapture_updatesStatusAndDelegatesGetFrame() {
52+
val mockFrame: Frame = mock()
53+
val mockCapture: FrameCapture = mock()
54+
whenever(mockCapture.status).thenReturn(OutputStatus.AVAILABLE)
55+
whenever(mockCapture.getFrame()).thenReturn(mockFrame)
56+
57+
pendingFrameCapture.setFrameCapture(mockCapture)
58+
59+
assertThat(pendingFrameCapture.status).isEqualTo(OutputStatus.AVAILABLE)
60+
assertThat(pendingFrameCapture.getFrame()).isEqualTo(mockFrame)
61+
}
62+
63+
@Test
64+
fun addListener_beforeSetFrameCapture_isTransferred() {
65+
val listener: Frame.Listener = mock()
66+
val mockCapture: FrameCapture = mock()
67+
68+
pendingFrameCapture.addListener(listener)
69+
pendingFrameCapture.setFrameCapture(mockCapture)
70+
71+
// Verify the listener was passed to the real capture once it arrived.
72+
verify(mockCapture).addListener(listener)
73+
verify(listener, never()).onFrameComplete()
74+
}
75+
76+
@Test
77+
fun addListener_afterSetFrameCapture_isDelegatedImmediately() {
78+
val listener: Frame.Listener = mock()
79+
val mockCapture: FrameCapture = mock()
80+
pendingFrameCapture.setFrameCapture(mockCapture)
81+
82+
pendingFrameCapture.addListener(listener)
83+
84+
verify(mockCapture).addListener(listener)
85+
}
86+
87+
@Test
88+
fun awaitFrame_suspendsUntilSetFrameCapture() = runTest {
89+
val mockFrame: Frame = mock()
90+
val mockCapture: FrameCapture = mock()
91+
whenever(mockCapture.awaitFrame()).thenReturn(mockFrame)
92+
93+
var resultFrame: Frame? = null
94+
val job = launch { resultFrame = pendingFrameCapture.awaitFrame() }
95+
96+
advanceUntilIdle()
97+
assertThat(resultFrame).isNull()
98+
99+
pendingFrameCapture.setFrameCapture(mockCapture)
100+
advanceUntilIdle()
101+
102+
assertThat(resultFrame).isEqualTo(mockFrame)
103+
assertThat(job.isCompleted).isTrue()
104+
}
105+
106+
@Test
107+
fun close_setsStatusAndNotifiesPendingListeners() {
108+
val listener: Frame.Listener = mock()
109+
pendingFrameCapture.addListener(listener)
110+
111+
pendingFrameCapture.close()
112+
113+
assertThat(pendingFrameCapture.status).isEqualTo(OutputStatus.UNAVAILABLE)
114+
verify(listener).onFrameComplete()
115+
}
116+
117+
@Test
118+
fun abort_setsStatusAndNotifiesPendingListeners() {
119+
val listener: Frame.Listener = mock()
120+
pendingFrameCapture.addListener(listener)
121+
122+
pendingFrameCapture.abort()
123+
124+
assertThat(pendingFrameCapture.status).isEqualTo(OutputStatus.ERROR_OUTPUT_ABORTED)
125+
verify(listener).onFrameComplete()
126+
}
127+
128+
@Test
129+
fun setFrameCapture_afterClose_closesTheProvidedCapture() {
130+
val mockCapture: FrameCapture = mock()
131+
132+
pendingFrameCapture.close()
133+
pendingFrameCapture.setFrameCapture(mockCapture)
134+
135+
// If the placeholder was already closed, any late-arriving capture should be closed
136+
// immediately.
137+
verify(mockCapture).close()
138+
}
139+
140+
@Test
141+
fun addListener_afterClose_callsOnFrameCompleteImmediately() {
142+
val listener: Frame.Listener = mock()
143+
144+
pendingFrameCapture.close()
145+
pendingFrameCapture.addListener(listener)
146+
147+
verify(listener).onFrameComplete()
148+
}
149+
150+
@Test
151+
fun awaitFrame_returnsNullWhenClosed() = runTest {
152+
launch { pendingFrameCapture.close() }
153+
154+
val frame = pendingFrameCapture.awaitFrame()
155+
assertThat(frame).isNull()
156+
}
157+
}

0 commit comments

Comments
 (0)