1 /*
2  * Copyright (C) 2021 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 android.car.evs;
18 
19 import static android.car.feature.Flags.FLAG_CAR_EVS_STREAM_MANAGEMENT;
20 import static com.android.car.internal.ExcludeFromCodeCoverageGeneratedReport.BOILERPLATE_CODE;
21 import static com.android.car.internal.ExcludeFromCodeCoverageGeneratedReport.DUMP_INFO;
22 
23 import android.annotation.FlaggedApi;
24 import android.annotation.NonNull;
25 import android.annotation.SuppressLint;
26 import android.annotation.SystemApi;
27 import android.car.Car;
28 import android.car.annotation.RequiredFeature;
29 import android.car.evs.CarEvsManager;
30 import android.car.evs.CarEvsManager.CarEvsServiceType;
31 import android.car.feature.Flags;
32 import android.hardware.HardwareBuffer;
33 import android.os.Parcel;
34 import android.os.Parcelable;
35 
36 import com.android.car.internal.ExcludeFromCodeCoverageGeneratedReport;
37 
38 import java.util.Objects;
39 
40 /**
41  * Wraps around {@link android.hardware.HardwareBuffer} to embed additional metadata of the buffer
42  * from the Extended View System service.
43  *
44  * @hide
45  */
46 @SystemApi
47 @RequiredFeature(Car.CAR_EVS_SERVICE)
48 public final class CarEvsBufferDescriptor implements Parcelable, AutoCloseable {
49     public static final @NonNull Parcelable.Creator<CarEvsBufferDescriptor> CREATOR =
50             new Parcelable.Creator<CarEvsBufferDescriptor>() {
51                 @NonNull
52                 @Override
53                 public CarEvsBufferDescriptor createFromParcel(final Parcel in) {
54                     return new CarEvsBufferDescriptor(in);
55                 }
56 
57                 @NonNull
58                 @Override
59                 public CarEvsBufferDescriptor[] newArray(final int size) {
60                     return new CarEvsBufferDescriptor[size];
61                 }
62             };
63 
64     private final int mId;
65     // This field shouldn't be accessed if CAR_EVS_STREAM_MANAGEMENT flag is not true.
66     private final @CarEvsServiceType int mType;
67 
68     @NonNull
69     private final HardwareBuffer mHardwareBuffer;
70 
71     /**
72      * Creates a {@link CarEvsBufferDescriptor} given an unique identifier and
73      * {@link android.hardware.HardwareBuffer}.
74      *
75      * @param id A 32-bit integer to uniquely identify associated hardware buffer.
76      * @param buffer Hardware buffer that contains the imagery data from EVS service.
77      */
CarEvsBufferDescriptor(int id, @NonNull final HardwareBuffer buffer)78     public CarEvsBufferDescriptor(int id, @NonNull final HardwareBuffer buffer) {
79         this(id, Flags.carEvsStreamManagement() ?
80                 CarEvsManager.SERVICE_TYPE_UNKNOWN : CarEvsManager.SERVICE_TYPE_REARVIEW, buffer);
81     }
82 
83     /**
84      * Creates a {@link CarEvsBufferDescriptor} given an unique identifier and
85      * {@link android.hardware.HardwareBuffer}.
86      *
87      * @param id A 32-bit integer to uniquely identify associated hardware buffer.
88      * @param buffer Hardware buffer that contains the imagery data from EVS service.
89      */
90     @FlaggedApi(FLAG_CAR_EVS_STREAM_MANAGEMENT)
CarEvsBufferDescriptor(int id, @CarEvsServiceType int type, @NonNull HardwareBuffer buffer)91     public CarEvsBufferDescriptor(int id, @CarEvsServiceType int type,
92             @NonNull HardwareBuffer buffer) {
93         Objects.requireNonNull(buffer, "HardwardBuffer cannot be null.");
94 
95         mId = id;
96         mHardwareBuffer = buffer;
97         mType = type;
98     }
99 
100     /** Parcelable methods */
CarEvsBufferDescriptor(final Parcel in)101     private CarEvsBufferDescriptor(final Parcel in) {
102         mId = in.readInt();
103         mType = in.readInt();
104         mHardwareBuffer = Objects.requireNonNull(HardwareBuffer.CREATOR.createFromParcel(in));
105     }
106 
107     @Override
108     @ExcludeFromCodeCoverageGeneratedReport(reason = BOILERPLATE_CODE)
describeContents()109     public int describeContents() {
110         return 0;
111     }
112 
113     @Override
writeToParcel(@onNull final Parcel dest, final int flags)114     public void writeToParcel(@NonNull final Parcel dest, final int flags) {
115         dest.writeInt(mId);
116         dest.writeInt(mType);
117         mHardwareBuffer.writeToParcel(dest, flags);
118     }
119 
120     @Override
121     @ExcludeFromCodeCoverageGeneratedReport(reason = DUMP_INFO)
toString()122     public String toString() {
123         return "CarEvsBufferDescriptor: id = " + mId + ", type = " + mType +
124                 ", buffer = " + mHardwareBuffer;
125     }
126 
127     @Override
128     @SuppressLint("GenericException")
finalize()129     protected void finalize() throws Throwable {
130         try {
131             close();
132         } finally {
133             super.finalize();
134         }
135     }
136 
137     @Override
close()138     public void close() {
139         if (!mHardwareBuffer.isClosed()) {
140             mHardwareBuffer.close();
141         }
142     }
143 
144     /**
145      * Returns an unique identifier of the hardware buffer described by this object.
146      *
147      * @return A 32-bit signed integer unique buffer identifier.
148      */
getId()149     public int getId() {
150         return mId;
151     }
152 
153     /**
154      * Returns a reference to {@link android.hardware.HardwareBuffer} registered
155      * to this descriptor.
156      *
157      * @return the registered {@link android.hardware.HardwareBuffer}.
158      */
159     @NonNull
getHardwareBuffer()160     public HardwareBuffer getHardwareBuffer() {
161         return mHardwareBuffer;
162     }
163 
164     /**
165      * Returns a type of a camera this buffer is originated from.
166      *
167      * @return {@link CarEvsServiceType}.
168      */
169     @FlaggedApi(FLAG_CAR_EVS_STREAM_MANAGEMENT)
getType()170     public @CarEvsServiceType int getType() {
171         return mType;
172     }
173 }
174