libnx  v4.2.0
native_window.h
Go to the documentation of this file.
1 /**
2  * @file native_window.h
3  * @brief Native window (NWindow) wrapper object, used for presenting images to the display (or other sinks).
4  * @author fincs
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../kernel/mutex.h"
9 #include "../kernel/event.h"
10 #include "../services/vi.h"
11 #include "../nvidia/graphic_buffer.h"
12 #include "types.h"
13 #include "binder.h"
14 #include "buffer_producer.h"
15 
16 /// Native window structure.
17 typedef struct NWindow {
18  u32 magic;
19  Binder bq;
20  Event event;
21  Mutex mutex;
22  u64 slots_configured;
23  u64 slots_requested;
24  s32 cur_slot;
25  u32 width;
26  u32 height;
27  u32 format;
28  u32 usage;
29  BqRect crop;
30  u32 scaling_mode;
31  u32 transform;
32  u32 sticky_transform;
33  u32 default_width;
34  u32 default_height;
35  u32 swap_interval;
36  bool is_connected;
37  bool producer_controlled_by_app;
38  bool consumer_running_behind;
39 } NWindow;
40 
41 ///@name Basic functions
42 ///@{
43 
44 /// Checks whether a pointer refers to a valid \ref NWindow object.
45 bool nwindowIsValid(NWindow* nw);
46 
47 /**
48  * @brief Retrieves the default \ref NWindow object.
49  * @return Pointer to the default \ref NWindow object.
50  * @note When this function is used/referenced, libnx will initialize VI services
51  * and create a \ref NWindow object from a \ref ViLayer created on the default \ref ViDisplay;
52  * all of this happening automatically during application startup (i.e. before main is called).
53  * If creating the default \ref NWindow fails, libnx will throw a LibnxError_BadGfxInit fatal error.
54  * Likewise, after main returns (or exit is called) libnx will clean up all resources used by it.
55  */
57 
58 /**
59  * @brief Creates a \ref NWindow.
60  * @param[out] nw Output \ref NWindow structure.
61  * @param[in] binder_session Service object for the Android IGraphicBufferProducer binder session.
62  * @param[in] binder_id Android IGraphicBufferProducer binder session ID.
63  * @param[in] producer_controlled_by_app Specifies whether the producer is controlled by the application.
64  */
65 Result nwindowCreate(NWindow* nw, Service* binder_session, s32 binder_id, bool producer_controlled_by_app);
66 
67 /**
68  * @brief Creates a \ref NWindow operating on a \ref ViLayer.
69  * @param[out] nw Output \ref NWindow structure.
70  * @param[in] layer Pointer to \ref ViLayer structure (such as the one returned by \ref viCreateLayer).
71  */
72 Result nwindowCreateFromLayer(NWindow* nw, const ViLayer* layer);
73 
74 /// Closes a \ref NWindow, freeing all resources associated with it.
75 void nwindowClose(NWindow* nw);
76 
77 ///@}
78 
79 ///@name Window configuration
80 ///@{
81 
82 /**
83  * @brief Retrieves the dimensions of a \ref NWindow.
84  * @param[in] nw Pointer to \ref NWindow structure.
85  * @param[out] out_width Output variable containing the width of the \ref NWindow.
86  * @param[out] out_height Output variable containing the height of the \ref NWindow.
87  * @note After creation, a \ref NWindow reports a default size (usually 1280x720).
88  * This size can be overriden by calling \ref nwindowSetDimensions.
89  */
90 Result nwindowGetDimensions(NWindow* nw, u32* out_width, u32* out_height);
91 
92 /**
93  * @brief Sets the dimensions of a \ref NWindow.
94  * @param[in] nw Pointer to \ref NWindow structure.
95  * @param[in] width Desired width of the \ref NWindow.
96  * @param[in] height Desired width of the \ref NWindow.
97  * @note This function cannot be called when there are buffers registered with the \ref NWindow.
98  */
99 Result nwindowSetDimensions(NWindow* nw, u32 width, u32 height);
100 
101 /**
102  * @brief Configures the crop applied to images presented through a \ref NWindow.
103  * @param[in] nw Pointer to \ref NWindow structure.
104  * @param[in] left X coordinate of the left margin of the crop bounding box.
105  * @param[in] top Y coordinate of the top margin of the crop bounding box.
106  * @param[in] right X coordinate of the right margin of the crop bounding box.
107  * @param[in] bottom Y coordinate of the bottom margin of the crop bounding box.
108  * @note Passing zero to all parameters disables the crop functionality. This is also the default.
109  * @note The bounding box defined by the parameters will be adjusted to fit within the dimensions of the \ref NWindow.
110  * @note \p left must be less or equal than \p right.
111  * @note \p top must be less or equal than \p bottom.
112  */
113 Result nwindowSetCrop(NWindow* nw, s32 left, s32 top, s32 right, s32 bottom);
114 
115 /**
116  * @brief Configures the transformation applied to images presented through a \ref NWindow.
117  * @param[in] nw Pointer to \ref NWindow structure.
118  * @param[in] transform Android transformation mode (see NATIVE_WINDOW_TRANSFORM_* enum)
119  * @note The default transformation is 0 (i.e. no transformation applied)
120  */
121 Result nwindowSetTransform(NWindow* nw, u32 transform);
122 
123 /**
124  * @brief Configures the swap interval of a \ref NWindow.
125  * @param[in] nw Pointer to \ref NWindow structure.
126  * @param[in] swap_interval Value specifying the number of display refreshes (VBlanks) that must occur between presenting images.
127  * @note The default swap interval is 1.
128  * @note If the \ref NWindow has three or more buffers configured (with \ref nwindowConfigureBuffer), it is possible to pass 0
129  * to disable the swap interval feature and present images as fast as allowed by the compositor. Otherwise, the system
130  * enforces a minimum of 1 as the swap interval.
131  */
132 Result nwindowSetSwapInterval(NWindow* nw, u32 swap_interval);
133 
134 /// Checks whether the consumer of a \ref NWindow is running behind.
136 {
137  return nw->consumer_running_behind;
138 }
139 
140 ///@}
141 
142 ///@name Buffer configuration and presentation
143 ///@{
144 
145 /**
146  * @brief Registers a \ref NvGraphicBuffer with a \ref NWindow.
147  * @param[in] nw Pointer to \ref NWindow structure.
148  * @param[in] slot ID of the slot to configure (starting from 0).
149  * @param[in] buf Pointer to \ref NvGraphicBuffer structure.
150  * @note When a buffer is registered, it is added to the internal queue of buffers used for presenting.
151  * @note All buffers registered with a \ref NWindow must have the same dimensions, format and usage.
152  * If \ref nwindowSetDimensions has not been previously called, the \ref NWindow will automatically
153  * adopt the dimensions of the first buffer registered with it. Otherwise, said buffer will need
154  * to match the dimensions that were previously configured.
155  */
157 
158 /**
159  * @brief Dequeues a buffer from a \ref NWindow.
160  * @param[in] nw Pointer to \ref NWindow structure.
161  * @param[out] out_slot Output variable containing the ID of the slot that has been dequeued.
162  * @param[out] out_fence Output variable containing a \ref NvMultiFence that will be signalled by
163  * the compositor when the buffer is ready to be written to. Pass NULL to wait instead
164  * on this fence before this function returns.
165  * @note For \p out_fence=NULL to work, \ref nvFenceInit must have been previously called.
166  */
167 Result nwindowDequeueBuffer(NWindow* nw, s32* out_slot, NvMultiFence* out_fence);
168 
169 /**
170  * @brief Cancels a buffer previously dequeued with \ref nwindowDequeueBuffer.
171  * @param[in] nw Pointer to \ref NWindow structure.
172  * @param[in] slot ID of the slot to cancel. This must match the output of the previous \ref nwindowDequeueBuffer call.
173  * @param[in] fence Pointer to the \ref NvMultiFence that will be waited on by the compositor before cancelling the buffer.
174  * Pass NULL if there is no such fence.
175  */
176 Result nwindowCancelBuffer(NWindow* nw, s32 slot, const NvMultiFence* fence);
177 
178 /**
179  * @brief Queues a buffer previously dequeued with \ref nwindowDequeueBuffer, making it ready for presentation.
180  * @param[in] nw Pointer to \ref NWindow structure.
181  * @param[in] slot ID of the slot to queue. This must match the output of the previous \ref nwindowDequeueBuffer call.
182  * @param[in] fence Pointer to the \ref NvMultiFence that will be waited on by the compositor before queuing/presenting the buffer.
183  * Pass NULL if there is no such fence.
184  */
185 Result nwindowQueueBuffer(NWindow* nw, s32 slot, const NvMultiFence* fence);
186 
187 /// Releases all buffers registered with a \ref NWindow.
189 
190 ///@}
nwindowSetDimensions
Result nwindowSetDimensions(NWindow *nw, u32 width, u32 height)
Sets the dimensions of a NWindow.
nwindowIsValid
bool nwindowIsValid(NWindow *nw)
Checks whether a pointer refers to a valid NWindow object.
nwindowGetDefault
NWindow * nwindowGetDefault(void)
Retrieves the default NWindow object.
nwindowSetTransform
Result nwindowSetTransform(NWindow *nw, u32 transform)
Configures the transformation applied to images presented through a NWindow.
Event
Kernel-mode event structure.
Definition: event.h:13
nwindowConfigureBuffer
Result nwindowConfigureBuffer(NWindow *nw, s32 slot, NvGraphicBuffer *buf)
Registers a NvGraphicBuffer with a NWindow.
types.h
Definitions for Android-related types and enumerations.
nwindowReleaseBuffers
Result nwindowReleaseBuffers(NWindow *nw)
Releases all buffers registered with a NWindow.
nwindowClose
void nwindowClose(NWindow *nw)
Closes a NWindow, freeing all resources associated with it.
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
nwindowCancelBuffer
Result nwindowCancelBuffer(NWindow *nw, s32 slot, const NvMultiFence *fence)
Cancels a buffer previously dequeued with nwindowDequeueBuffer.
Binder
Definition: binder.h:8
nwindowIsConsumerRunningBehind
static bool nwindowIsConsumerRunningBehind(NWindow *nw)
Checks whether the consumer of a NWindow is running behind.
Definition: native_window.h:135
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
NvMultiFence
Definition: fence.h:6
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
nwindowQueueBuffer
Result nwindowQueueBuffer(NWindow *nw, s32 slot, const NvMultiFence *fence)
Queues a buffer previously dequeued with nwindowDequeueBuffer, making it ready for presentation.
Mutex
_LOCK_T Mutex
Mutex datatype, defined in newlib.
Definition: mutex.h:12
BqRect
Definition: buffer_producer.h:6
nwindowSetCrop
Result nwindowSetCrop(NWindow *nw, s32 left, s32 top, s32 right, s32 bottom)
Configures the crop applied to images presented through a NWindow.
Result
u32 Result
Function error code result type.
Definition: types.h:44
nwindowSetSwapInterval
Result nwindowSetSwapInterval(NWindow *nw, u32 swap_interval)
Configures the swap interval of a NWindow.
nwindowCreateFromLayer
Result nwindowCreateFromLayer(NWindow *nw, const ViLayer *layer)
Creates a NWindow operating on a ViLayer.
nwindowGetDimensions
Result nwindowGetDimensions(NWindow *nw, u32 *out_width, u32 *out_height)
Retrieves the dimensions of a NWindow.
nwindowDequeueBuffer
Result nwindowDequeueBuffer(NWindow *nw, s32 *out_slot, NvMultiFence *out_fence)
Dequeues a buffer from a NWindow.
NWindow
Native window structure.
Definition: native_window.h:17
NvGraphicBuffer
Definition: graphic_buffer.h:22
ViLayer
Definition: vi.h:22
nwindowCreate
Result nwindowCreate(NWindow *nw, Service *binder_session, s32 binder_id, bool producer_controlled_by_app)
Creates a NWindow.
Service
Service object structure.
Definition: service.h:13