1 #ifndef DVR_DISPLAY_MANAGER_CLIENT_H_
2 #define DVR_DISPLAY_MANAGER_CLIENT_H_
3 
4 #include <stdbool.h>
5 #include <stddef.h>
6 #include <stdint.h>
7 #include <sys/cdefs.h>
8 
9 #include <dvr/dvr_display_types.h>
10 #include <dvr/dvr_surface.h>
11 
12 __BEGIN_DECLS
13 
14 typedef struct DvrBuffer DvrBuffer;
15 typedef struct DvrDisplayManager DvrDisplayManager;
16 typedef struct DvrSurfaceState DvrSurfaceState;
17 typedef struct DvrReadBufferQueue DvrReadBufferQueue;
18 
19 typedef uint64_t DvrSurfaceUpdateFlags;
20 
21 // Attempts to connect to the display manager service.
22 // @return 0 on success. Otherwise returns a negative error value.
23 int dvrDisplayManagerCreate(DvrDisplayManager** client_out);
24 
25 // Destroys the display manager client object.
26 void dvrDisplayManagerDestroy(DvrDisplayManager* client);
27 
28 // Sets up a named buffer for shared memory data transfer between display
29 // clients and the display manager.
30 // @return 0 on success. Otherwise returns a negative error value.
31 int dvrDisplayManagerSetupNamedBuffer(DvrDisplayManager* client,
32                                       const char* name, size_t size,
33                                       uint64_t usage, DvrBuffer** buffer_out);
34 
35 // Returns an fd used to signal when surface updates occur. Note that depending
36 // on the underlying transport, only a subset of the real event bits may be
37 // supported. Use dvrDisplayManagerClientTranslateEpollEventMask to get the real
38 // event flags.
39 // @return the fd on success. Otherwise returns a negative error value.
40 int dvrDisplayManagerGetEventFd(DvrDisplayManager* client);
41 
42 // @param in_events pass in the epoll revents that were initially returned by
43 // poll/epoll.
44 // @param on success, this value will be overwritten with the true poll/epoll
45 // values.
46 // @return 0 on success. Otherwise returns a negative error value.
47 int dvrDisplayManagerTranslateEpollEventMask(DvrDisplayManager* client,
48                                              int in_events, int* out_events);
49 
50 // Queries the display manager service for the current state of the display
51 // surfaces and stores the results in the given surface state object.
52 // @return 0 on success. Otherwise returns a negative error value.
53 int dvrDisplayManagerGetSurfaceState(DvrDisplayManager* client,
54                                      DvrSurfaceState* surface_state);
55 
56 // Gets a read buffer queue from the surface |surface_id| named |queue_id|. Each
57 // call returns a different read buffer queue connected to the same write buffer
58 // queue. Callers should cache these instead of requesting new ones when
59 // possible.
60 int dvrDisplayManagerGetReadBufferQueue(DvrDisplayManager* client,
61                                         int surface_id, int queue_id,
62                                         DvrReadBufferQueue** queue_out);
63 
64 // Creates a new surface state object. This object may be used to receive the
65 // results of a surface state query. More than one state object may be created
66 // to keep multiple snapshots, if desired.
67 // @return 0 on success. Otherwise returns a negative error value.
68 int dvrSurfaceStateCreate(DvrSurfaceState** surface_state);
69 
70 // Destorys the surface state object.
71 void dvrSurfaceStateDestroy(DvrSurfaceState* surface_state);
72 
73 // Writes the number of surfaces described in the state object into |count_out|.
74 // @return 0 on success. Otherwise returns a negative error value.
75 int dvrSurfaceStateGetSurfaceCount(DvrSurfaceState* surface_state,
76                                    size_t* count_out);
77 
78 // Returns the update flags for the surface at |surface_index| in the state
79 // object. The flags may be used to determine what changes, if any, occured to
80 // the surface since the last state update.
81 // @return 0 on success. Otherwise returns a negative error value.
82 int dvrSurfaceStateGetUpdateFlags(DvrSurfaceState* surface_state,
83                                   size_t surface_index,
84                                   DvrSurfaceUpdateFlags* flags_out);
85 
86 // Returns the unique identifier of surface at |surface_index| in the state
87 // object. The identifier may be used to distinguish between surfaces.
88 // @return 0 on success. Otherwise returns a negative error value.
89 int dvrSurfaceStateGetSurfaceId(DvrSurfaceState* surface_state,
90                                 size_t surface_index, int* surface_id_out);
91 
92 // Returns the process id of surface at |surface_index| in the state object.
93 // @return 0 on success. Otherwise returns a negative error value.
94 int dvrSurfaceStateGetProcessId(DvrSurfaceState* surface_state,
95                                 size_t surface_index, int* process_id_out);
96 
97 // Writes the number of queues in the surface at |surface_index| in the state
98 // object into |count_out|.
99 // @return 0 on success. Otherwise returns a negative error value.
100 int dvrSurfaceStateGetQueueCount(DvrSurfaceState* surface_state,
101                                  size_t surface_index, size_t* count_out);
102 
103 // Returns up to |max_count| queue ids for the queues belonging to the surface
104 // at |surface_index| in the state object.
105 // @return The number of queue ids written on success. Otherwise returns a
106 // negative error value.
107 ssize_t dvrSurfaceStateGetQueueIds(DvrSurfaceState* surface_state,
108                                    size_t surface_index, int* queue_ids,
109                                    size_t max_count);
110 
111 // Writes the z-order of the surface at |surface_index| in surface state object
112 // into |z_order_out|.
113 // @return 0 on success. Otherwise returns a negative error value.
114 int dvrSurfaceStateGetZOrder(DvrSurfaceState* surface_state,
115                              size_t surface_index, int* z_order_out);
116 
117 // Writes the visible state of the surface at |surface_index| in the surface
118 // state object into |visible_out|.
119 // @return 0 on success. Otherwise it returns a negative error value.
120 int dvrSurfaceStateGetVisible(DvrSurfaceState* surface_state,
121                               size_t surface_index, bool* visible_out);
122 
123 // Writes the number of attributes on the surface at |surface_index| in the
124 // state object into |count_out|.
125 // @return 0 on success. Otherwise it returns a negative error value.
126 int dvrSurfaceStateGetAttributeCount(DvrSurfaceState* surface_state,
127                                      size_t surface_index, size_t* count_out);
128 
129 // Writes the list of attribute key/value pairs for the surface at
130 // |surface_index| in the surface state object into |attributes|.
131 // @return The number of attributes written on success. Otherwise returns a
132 // negative error value.
133 ssize_t dvrSurfaceStateGetAttributes(DvrSurfaceState* surface_state,
134                                      size_t surface_index,
135                                      DvrSurfaceAttribute* attributes,
136                                      size_t max_count);
137 
138 __END_DECLS
139 
140 #endif  // DVR_DISPLAY_MANAGER_CLIENT_H_
141