1/*
2 * Copyright 2020 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
17package [email protected];
18
19import ISurroundViewSession;
20
21/**
22 * Interface representing a surround view 3d session.
23 *
24 * Surround view 3d provides a virtual view from any desired position in the 3d space around the
25 * car. Surround view 3d creates an approximate 3d surface around the car to match the surrounds
26 * and provides a virtual view as seen on this surface.
27 */
28interface ISurroundView3dSession extends ISurroundViewSession {
29
30    /**
31     * Sets the desired views of surround view 3d.
32     *
33     * Surround view 3d takes a list of desired virtual view points and provides an output frame
34     * for each view. Default view list is a single view from behind the car front facing in the
35     * front direction.
36     * A call to setViews() results in the views set by a previous call to be discarded.
37     * Each view set is identified by an Id which is returned with the corresponding output frame
38     * of that view.
39     * Clients can call setViews() at any stage of the session (before/after startStream). Client
40     * may continue to receive frames of previous views after setViews() call for a while and can
41     * identify updated set of views once effective using the view Id provided in the updated
42     * views frames.
43     *
44     * @param views     List of desired views to generate output frames.
45     * @return svResult Returns OK if successful, appropriate error result otherwise.
46     */
47    setViews(vec<View3d> views) generates (SvResult svResult);
48
49    /**
50     * Sets the configuration of 3d surround view.
51     *
52     * Configuration is used for supported different target use-cases of the surround view eg.
53     * fullscreen view or preview. A set config call can be performed at anytime (before or after
54     * startStream) of the session.
55     * Once config change is complete, a CONFIG_CHANGED event is sent, after which
56     * all frames received will be of the updated config.
57     *
58     * @param sv3dConfig Configuration to set.
59     * @return svResult  Returns OK if successful, appropriate error result otherwise.
60     */
61    set3dConfig(Sv3dConfig sv3dConfig) generates (SvResult svResult);
62
63    /**
64     * Gets the current configuration of the 3d surround view.
65     *
66     * Configuration is used for supported different target use-cases of the surround view eg.
67     * fullscreen view or preview. Use setConfig call to set a configuration.
68     *
69     * @return sv3dConfig The current active configuration of the 3d session.
70     */
71    get3dConfig() generates (Sv3dConfig sv3dConfig);
72
73    /**
74     * Updates 3d overlays in scene.
75     *
76     * updateOverlays() provides a way to set a 3d overlay object in the scene. An overlay is an
77     * 3d object in the scene which can be a visual indicator to provide additional information eg.
78     * parking sensor distance indicators or overlays for objects in scene.
79     *
80     * An overlay object is defined by a set of points (forming triangles) with some color and
81     * transparency values and each overlay is identified by an overlay Id.
82     * When an overlay with a new Id is passed, a new overlay is added to the scene.
83     * When an overlay with previous id is passed, its vertices/color are updated with passed data.
84     * If the overlay data is empty, the overlay is removed from the scene.
85     *
86     * @param overlaysData   Object with shared memory containing overlays to add/update in the
87     *                       scene. Refer to OverlaysData structure for layout in shared memory.
88     * @return svResult      Returns OK if successful, appropriate error result otherwise.
89     */
90    updateOverlays(OverlaysData overlaysData) generates (SvResult svResult);
91
92    /**
93     * Projects points on camera image to surround view 3D surface.
94     *
95     * Useful for mapping points detected on individual camera frames onto the surround view 3D
96     * surface, these 3d points can then be used to set overlays using the updateOverlays() for
97     * the detected objects in the scene.
98     * Note:
99     * 3d points returned are projected on an approximate 3d surface and do not provide the exact
100     * 3d location.
101     *
102     * @param cameraPoints  List of camera pixel points to be projected in range including (0, 0)
103     *                      and (width - 1, height -1) of camera frame. If point is outside camera
104                            frame INVALID_ARG error is returned.
105     * @param cameraId      Id of the EvsCamera to use for projecting points. Id must be one of the
106     *                      cameras as returned by getCameraIds() else INVALID_ARG error is returned
107     * @return points3d     Returns a list of 3d points on the approximate 3d surface in the
108     *                      automotive coordinate system in the same order as cameraPoints.
109     *                      Points that do not project to 3d surface are set with inValid true.
110     */
111    projectCameraPointsTo3dSurface(vec<Point2dInt> cameraPoints, string cameraId) generates (
112            vec<Point3dFloat> points3d);
113};
114