libnx
Data Structures
native_window.h File Reference

Native window (NWindow) wrapper object, used for presenting images to the display (or other sinks). More...

#include "../kernel/mutex.h"
#include "../kernel/event.h"
#include "../services/vi.h"
#include "../nvidia/graphic_buffer.h"
#include "types.h"
#include "binder.h"
#include "buffer_producer.h"

Go to the source code of this file.

Data Structures

struct  NWindow
 Native window structure. More...
 

Functions

Basic functions
bool nwindowIsValid (NWindow *nw)
 Checks whether a pointer refers to a valid NWindow object.
 
NWindownwindowGetDefault (void)
 Retrieves the default NWindow object. More...
 
Result nwindowCreate (NWindow *nw, s32 binder_id, bool producer_controlled_by_app)
 Creates a NWindow. More...
 
Result nwindowCreateFromLayer (NWindow *nw, const ViLayer *layer)
 Creates a NWindow operating on a ViLayer. More...
 
void nwindowClose (NWindow *nw)
 Closes a NWindow, freeing all resources associated with it.
 
Window configuration
Result nwindowGetDimensions (NWindow *nw, u32 *out_width, u32 *out_height)
 Retrieves the dimensions of a NWindow. More...
 
Result nwindowSetDimensions (NWindow *nw, u32 width, u32 height)
 Sets the dimensions of a NWindow. More...
 
Result nwindowSetCrop (NWindow *nw, s32 left, s32 top, s32 right, s32 bottom)
 Configures the crop applied to images presented through a NWindow. More...
 
Result nwindowSetTransform (NWindow *nw, u32 transform)
 Configures the transformation applied to images presented through a NWindow. More...
 
Result nwindowSetSwapInterval (NWindow *nw, u32 swap_interval)
 Configures the swap interval of a NWindow. More...
 
static bool nwindowIsConsumerRunningBehind (NWindow *nw)
 Checks whether the consumer of a NWindow is running behind.
 
Buffer configuration and presentation
Result nwindowConfigureBuffer (NWindow *nw, s32 slot, NvGraphicBuffer *buf)
 Registers a NvGraphicBuffer with a NWindow. More...
 
Result nwindowDequeueBuffer (NWindow *nw, s32 *out_slot, NvMultiFence *out_fence)
 Dequeues a buffer from a NWindow. More...
 
Result nwindowCancelBuffer (NWindow *nw, s32 slot, const NvMultiFence *fence)
 Cancels a buffer previously dequeued with nwindowDequeueBuffer. More...
 
Result nwindowQueueBuffer (NWindow *nw, s32 slot, const NvMultiFence *fence)
 Queues a buffer previously dequeued with nwindowDequeueBuffer, making it ready for presentation. More...
 
Result nwindowReleaseBuffers (NWindow *nw)
 Releases all buffers registered with a NWindow.
 

Detailed Description

Native window (NWindow) wrapper object, used for presenting images to the display (or other sinks).

Author
fincs

Function Documentation

Result nwindowCancelBuffer ( NWindow nw,
s32  slot,
const NvMultiFence fence 
)

Cancels a buffer previously dequeued with nwindowDequeueBuffer.

Parameters
[in]nwPointer to NWindow structure.
[in]slotID of the slot to cancel. This must match the output of the previous nwindowDequeueBuffer call.
[in]fencePointer to the NvMultiFence that will be waited on by the compositor before cancelling the buffer. Pass NULL if there is no such fence.
Result nwindowConfigureBuffer ( NWindow nw,
s32  slot,
NvGraphicBuffer buf 
)

Registers a NvGraphicBuffer with a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[in]slotID of the slot to configure (starting from 0).
[in]bufPointer to NvGraphicBuffer structure.
Note
When a buffer is registered, it is added to the internal queue of buffers used for presenting.
All buffers registered with a NWindow must have the same dimensions, format and usage. If nwindowSetDimensions has not been previously called, the NWindow will automatically adopt the dimensions of the first buffer registered with it. Otherwise, said buffer will need to match the dimensions that were previously configured.
Result nwindowCreate ( NWindow nw,
s32  binder_id,
bool  producer_controlled_by_app 
)

Creates a NWindow.

Parameters
[out]nwOutput NWindow structure.
[in]binder_idAndroid IGraphicBufferProducer binder session ID.
[in]producer_controlled_by_appSpecifies whether the producer is controlled by the application.
Result nwindowCreateFromLayer ( NWindow nw,
const ViLayer layer 
)

Creates a NWindow operating on a ViLayer.

Parameters
[out]nwOutput NWindow structure.
[in]layerPointer to ViLayer structure (such as the one returned by viCreateLayer).
Result nwindowDequeueBuffer ( NWindow nw,
s32 *  out_slot,
NvMultiFence out_fence 
)

Dequeues a buffer from a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[out]out_slotOutput variable containing the ID of the slot that has been dequeued.
[out]out_fenceOutput variable containing a NvMultiFence that will be signalled by the compositor when the buffer is ready to be written to. Pass NULL to wait instead on this fence before this function returns.
Note
For out_fence=NULL to work, nvFenceInit must have been previously called.
NWindow* nwindowGetDefault ( void  )

Retrieves the default NWindow object.

Returns
Pointer to the default NWindow object.
Note
When this function is used/referenced, libnx will initialize VI services and create a NWindow object from a ViLayer created on the default ViDisplay; all of this happening automatically during application startup (i.e. before main is called). If creating the default NWindow fails, libnx will throw a LibnxError_BadGfxInit fatal error. Likewise, after main returns (or exit is called) libnx will clean up all resources used by it.
Result nwindowGetDimensions ( NWindow nw,
u32 *  out_width,
u32 *  out_height 
)

Retrieves the dimensions of a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[out]out_widthOutput variable containing the width of the NWindow.
[out]out_heightOutput variable containing the height of the NWindow.
Note
After creation, a NWindow reports a default size (usually 1280x720). This size can be overriden by calling nwindowSetDimensions.
Result nwindowQueueBuffer ( NWindow nw,
s32  slot,
const NvMultiFence fence 
)

Queues a buffer previously dequeued with nwindowDequeueBuffer, making it ready for presentation.

Parameters
[in]nwPointer to NWindow structure.
[in]slotID of the slot to queue. This must match the output of the previous nwindowDequeueBuffer call.
[in]fencePointer to the NvMultiFence that will be waited on by the compositor before queuing/presenting the buffer. Pass NULL if there is no such fence.
Result nwindowSetCrop ( NWindow nw,
s32  left,
s32  top,
s32  right,
s32  bottom 
)

Configures the crop applied to images presented through a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[in]leftX coordinate of the left margin of the crop bounding box.
[in]topY coordinate of the top margin of the crop bounding box.
[in]rightX coordinate of the right margin of the crop bounding box.
[in]bottomY coordinate of the bottom margin of the crop bounding box.
Note
Passing zero to all parameters disables the crop functionality. This is also the default.
The bounding box defined by the parameters will be adjusted to fit within the dimensions of the NWindow.
left must be less or equal than right.
top must be less or equal than bottom.
Result nwindowSetDimensions ( NWindow nw,
u32  width,
u32  height 
)

Sets the dimensions of a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[in]widthDesired width of the NWindow.
[in]heightDesired width of the NWindow.
Note
This function cannot be called when there are buffers registered with the NWindow.
Result nwindowSetSwapInterval ( NWindow nw,
u32  swap_interval 
)

Configures the swap interval of a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[in]swap_intervalValue specifying the number of display refreshes (VBlanks) that must occur between presenting images.
Note
The default swap interval is 1.
If the NWindow has three or more buffers configured (with nwindowConfigureBuffer), it is possible to pass 0 to disable the swap interval feature and present images as fast as allowed by the compositor. Otherwise, the system enforces a minimum of 1 as the swap interval.
Result nwindowSetTransform ( NWindow nw,
u32  transform 
)

Configures the transformation applied to images presented through a NWindow.

Parameters
[in]nwPointer to NWindow structure.
[in]transformAndroid transformation mode (see NATIVE_WINDOW_TRANSFORM_* enum)
Note
The default transformation is 0 (i.e. no transformation applied)