1 /*
2  * Copyright (c) 2024 Huawei Device Co., Ltd.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  *     http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #ifndef API_RENDER_IRENDER_NODE_GRAPH_MANAGER_H
17 #define API_RENDER_IRENDER_NODE_GRAPH_MANAGER_H
18 
19 #include <base/containers/array_view.h>
20 #include <base/containers/string.h>
21 #include <base/containers/string_view.h>
22 #include <base/containers/unique_ptr.h>
23 #include <base/containers/vector.h>
24 #include <render/namespace.h>
25 #include <render/render_data_structures.h>
26 #include <render/resource_handle.h>
27 
28 RENDER_BEGIN_NAMESPACE()
29 class IRenderNodeGraphLoader;
30 
31 /** \addtogroup group_render_irendernodegraphmanager
32  *  @{
33  */
34 /** Render node desctriptor */
35 struct RenderNodeDesc {
36     /** Type name */
37     RenderDataConstants::RenderDataFixedString typeName;
38     /** Name of render node instance */
39     RenderDataConstants::RenderDataFixedString nodeName;
40     /** Description of setup data */
41     RenderNodeGraphInputs description;
42     /** Render node specific json string */
43     BASE_NS::string nodeJson;
44 };
45 
46 /** Render node desctriptor */
47 struct RenderNodeGraphOutputResource {
48     /** Simple output name */
49     RenderDataConstants::RenderDataFixedString name;
50     /** Name of render node instance where the output is from */
51     RenderDataConstants::RenderDataFixedString nodeName;
52 };
53 
54 /** Render node graph descriptor */
55 struct RenderNodeGraphDesc {
56     /** Render node graph name */
57     RenderDataConstants::RenderDataFixedString renderNodeGraphName;
58     /** Render node graph (default) data store name (can be used in various for access point) */
59     RenderDataConstants::RenderDataFixedString renderNodeGraphDataStoreName;
60     /** Optional uri, which can be fetched later to get path to the loaded file */
61     RenderDataConstants::RenderDataFixedString renderNodeGraphUri;
62     /** Render nodes */
63     BASE_NS::vector<RenderNodeDesc> nodes;
64 
65     /** Render node graph output resources */
66     BASE_NS::vector<RenderNodeGraphOutputResource> outputResources;
67 };
68 
69 struct RenderNodeDescInfo {
70     /** Type name */
71     RenderDataConstants::RenderDataFixedString typeName;
72     /** Name of render node instance */
73     RenderDataConstants::RenderDataFixedString nodeName;
74     /** Specific flags for node to change state (e.g. enable / disable) */
75     uint32_t flags { 0u };
76 };
77 
78 /** Render node graph descriptor */
79 struct RenderNodeGraphDescInfo {
80     /** Render node graph name */
81     RenderDataConstants::RenderDataFixedString renderNodeGraphName;
82     /** Render node graph (default) data store name (can be used in various for access point) */
83     RenderDataConstants::RenderDataFixedString renderNodeGraphDataStoreName;
84     /** Render node graph uri (if set) */
85     RenderDataConstants::RenderDataFixedString renderNodeGraphUri;
86     /** Render nodes */
87     BASE_NS::vector<RenderNodeDescInfo> nodes;
88 };
89 
90 /** Render node graph input and output resources. Depending on the rendering state these might not be valid */
91 struct RenderNodeGraphResourceInfo {
92     /** Render node input resources */
93     BASE_NS::vector<RenderHandleReference> inputResources;
94     /** Render node output resources */
95     BASE_NS::vector<RenderHandleReference> outputResources;
96 };
97 
98 /** Interface class to hold all render node graphs and their data.
99  *
100  * Internally synchronized.
101  */
102 class IRenderNodeGraphManager {
103 public:
104     /**
105      * With dynamic render node graphs render nodes can be inserted or erased.
106      */
107     enum class RenderNodeGraphUsageType : uint8_t {
108         RENDER_NODE_GRAPH_STATIC = 0,
109         RENDER_NODE_GRAPH_DYNAMIC = 1,
110     };
111 
112     IRenderNodeGraphManager(const IRenderNodeGraphManager&) = delete;
113     IRenderNodeGraphManager& operator=(const IRenderNodeGraphManager&) = delete;
114 
115     /** Get render handle reference for raw handle.
116      *  @param handle Raw render handle
117      *  @return Returns A render handle reference for the handle.
118      */
119     virtual RenderHandleReference Get(const RenderHandle& handle) const = 0;
120 
121     /** Create render node graph.
122      * @param usage Usage style of graphs. (Static, Dynamic)
123      * @param desc Render node graph description.
124      * @param renderNodeGraphName Override render node graph name.
125      * @param renderNodeGraphName Override render node graph data store name (default access point data store).
126      * @return Render data handle resource.
127      */
128     virtual RenderHandleReference Create(const RenderNodeGraphUsageType usage, const RenderNodeGraphDesc& desc,
129         const BASE_NS::string_view renderNodeGraphName, const BASE_NS::string_view renderNodeGraphDataStoreName) = 0;
130 
131     /** Create render node graph.
132      * @param usage Usage style of graphs. (Static, Dynamic)
133      * @param desc Render node graph description.
134      * @param renderNodeGraphName Override render node graph name.
135      * @return Render data handle resource.
136      */
137     virtual RenderHandleReference Create(const RenderNodeGraphUsageType usage, const RenderNodeGraphDesc& desc,
138         const BASE_NS::string_view renderNodeGraphName) = 0;
139 
140     /** Create render node graph.
141      * @param usage Usage style of graphs. (Static, Dynamic)
142      * @param desc Render node graph description.
143      * @return Render data handle.
144      */
145     virtual RenderHandleReference Create(const RenderNodeGraphUsageType usage, const RenderNodeGraphDesc& desc) = 0;
146 
147     /** Insert new render node to dynamic render node graph to the last render node in graph.
148      * @param handle Handle of a render node graph.
149      * @param renderNodeDesc Description of render node.
150      */
151     virtual void PushBackRenderNode(const RenderHandleReference& handle, const RenderNodeDesc& renderNodeDesc) = 0;
152 
153     /** Remove render node from dynamic render node graph.
154      * Erase does not destroy GPU resource that have been created in the erased render node.
155      * The resources are destroyed when the render node graph is destroyed.
156      * @param handle Handle of a render node graph.
157      * @param renderNodeName A valid render node name in this particular render node graph.
158      */
159     virtual void EraseRenderNode(const RenderHandleReference& handle, const BASE_NS::string_view renderNodeName) = 0;
160 
161     /** Insert new render node to dynamic render node graph to a position.
162      * @param handle Handle of a render node graph.
163      * @param renderNodeDesc Description of render node.
164      * @pos renderNodeName Instance name of render node to insert before.
165      */
166     virtual void InsertBeforeRenderNode(const RenderHandleReference& handle, const RenderNodeDesc& renderNodeDesc,
167         const BASE_NS::string_view renderNodeName) = 0;
168 
169     /** Insert new render node to dynamic render node graph to a position.
170      * @param handle Handle of a render node graph.
171      * @param renderNodeDesc Description of render node.
172      * @pos renderNodeName Instance name of render node to insert after.
173      */
174     virtual void InsertAfterRenderNode(const RenderHandleReference& handle, const RenderNodeDesc& renderNodeDesc,
175         const BASE_NS::string_view renderNodeName) = 0;
176 
177     /** Update status etc. with flags.
178      * @param handle Handle of a render node graph.
179      * @param graphDescInfo Render node graph description info with updatable flags.
180      */
181     virtual void UpdateRenderNodeGraph(
182         const RenderHandleReference& handle, const RenderNodeGraphDescInfo& graphDescInfo) = 0;
183 
184     /** Get render node graph description info with render node types, names, and current flags
185      * @param handle Handle of a render node graph.
186      * @return RenderNodeGraphDescInfo New render node graph description info struct.
187      */
188     virtual RenderNodeGraphDescInfo GetInfo(const RenderHandleReference& handle) const = 0;
189 
190     /** Set render node graph inputs and outputs.
191      * This needs to be called before RenderFrame in the frame where these are supposed to be used.
192      * Overrides everything -> Need to re-set existing if called.
193      * One can reset handle references by calling this with empty inputs and outputs.
194      * @param handle Handle of a render node graph.
195      * @param inputs Render node graph input handles.
196      * @param outputs Render node graph output handles.
197      */
198     virtual void SetRenderNodeGraphResources(const RenderHandleReference& handle,
199         const BASE_NS::array_view<const RenderHandleReference> inputs,
200         const BASE_NS::array_view<const RenderHandleReference> outputs) = 0;
201 
202     /** Get render node graph resource info. Returns the handles set through SetRnederNodeGraphResources.
203      * @param handle Handle of a render node graph.
204      * @return RenderNodeGraphResourceInfo Render node graph resources.
205      */
206     virtual RenderNodeGraphResourceInfo GetRenderNodeGraphResources(
207         const RenderHandleReference& handleResource) const = 0;
208 
209     /** Create render node graph directly from uri. Stores the uri for later info.
210      * @param usage Usage style of graphs. (Static, Dynamic)
211      * @param uri Path to render node graph json file.
212      * @return Render data handle resource.
213      */
214     virtual RenderHandleReference LoadAndCreate(
215         const RenderNodeGraphUsageType usage, const BASE_NS::string_view uri) = 0;
216 
217     /** Access to render node graph loader.
218      */
219     virtual IRenderNodeGraphLoader& GetRenderNodeGraphLoader() = 0;
220 
221 protected:
222     IRenderNodeGraphManager() = default;
223     virtual ~IRenderNodeGraphManager() = default;
224 };
225 
226 /** Interface class for creating a RenderNodeGraphDesc from a JSON file.
227  */
228 class IRenderNodeGraphLoader {
229 public:
230     /** Describes result of the loading operation. */
231     struct LoadResult {
232         LoadResult() = default;
LoadResultLoadResult233         explicit LoadResult(const BASE_NS::string& error) : success(false), error(error) {}
234 
235         /** Indicates, whether the parsing operation is successful. */
236         bool success { true };
237 
238         /** In case of parsing error, contains the description of the error. */
239         BASE_NS::string error;
240 
241         /** A valid render node graph descriptor, when success is true. */
242         RenderNodeGraphDesc desc;
243     };
244 
245     /** Load a render node graph description from a file.
246      * @param fileManager File manager to be used for file access
247      * @param uri URI to a file containing the render node graph description in JSON format.
248      * @return If loading fails LoadResult::success is false and LoadResult::error contains an error message.
249      */
250     virtual LoadResult Load(const BASE_NS::string_view uri) = 0;
251 
252     /** Load a render node graph description from a JSON string.
253      * @param json String containing the render node graph description in JSON format.
254      * @return If loading fails LoadResult::success is false and LoadResult::error contains an error message.
255      */
256     virtual LoadResult LoadString(const BASE_NS::string_view json) = 0;
257 
258 protected:
259     IRenderNodeGraphLoader() = default;
260     virtual ~IRenderNodeGraphLoader() = default;
261 };
262 /** @} */
263 RENDER_END_NAMESPACE()
264 
265 #endif // API_RENDER_IRENDER_NODE_GRAPH_MANAGER_H
266