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"

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.

NWindow *	nwindowGetDefault (void)
	Retrieves the default NWindow object.

Result	nwindowCreate (NWindow nw, Service binder_session, s32 binder_id, bool producer_controlled_by_app)
	Creates a NWindow.

Result	nwindowCreateFromLayer (NWindow nw, const ViLayer layer)
	Creates a NWindow operating on a ViLayer.

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.

Result	nwindowSetDimensions (NWindow *nw, u32 width, u32 height)
	Sets the dimensions of a NWindow.

Result	nwindowSetCrop (NWindow *nw, s32 left, s32 top, s32 right, s32 bottom)
	Configures the crop applied to images presented through a NWindow.

Result	nwindowSetTransform (NWindow *nw, u32 transform)
	Configures the transformation applied to images presented through a NWindow.

Result	nwindowSetSwapInterval (NWindow *nw, u32 swap_interval)
	Configures the swap interval of a NWindow.

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.

Result	nwindowDequeueBuffer (NWindow nw, s32 out_slot, NvMultiFence *out_fence)
	Dequeues a buffer from a NWindow.

Result	nwindowCancelBuffer (NWindow nw, s32 slot, const NvMultiFence fence)
	Cancels a buffer previously dequeued with nwindowDequeueBuffer.

Result	nwindowQueueBuffer (NWindow nw, s32 slot, const NvMultiFence fence)
	Queues a buffer previously dequeued with nwindowDequeueBuffer, making it ready for presentation.

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

Copyright: libnx Authors

Function Documentation

◆ nwindowCancelBuffer()

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

Cancels a buffer previously dequeued with nwindowDequeueBuffer.

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	slot	ID of the slot to cancel. This must match the output of the previous nwindowDequeueBuffer call.
[in]	fence	Pointer to the NvMultiFence that will be waited on by the compositor before cancelling the buffer. Pass NULL if there is no such fence.

◆ nwindowConfigureBuffer()

Result nwindowConfigureBuffer	(	NWindow *	nw,
		s32	slot,
		NvGraphicBuffer *	buf
	)

Registers a NvGraphicBuffer with a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	slot	ID of the slot to configure (starting from 0).
[in]	buf	Pointer 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.

◆ nwindowCreate()

Result nwindowCreate	(	NWindow *	nw,
		Service *	binder_session,
		s32	binder_id,
		bool	producer_controlled_by_app
	)

Creates a NWindow.

Parameters

[out]	nw	Output NWindow structure.
[in]	binder_session	Service object for the Android IGraphicBufferProducer binder session.
[in]	binder_id	Android IGraphicBufferProducer binder session ID.
[in]	producer_controlled_by_app	Specifies whether the producer is controlled by the application.

◆ nwindowCreateFromLayer()

Result nwindowCreateFromLayer	(	NWindow *	nw,
		const ViLayer *	layer
	)

Creates a NWindow operating on a ViLayer.

Parameters

[out]	nw	Output NWindow structure.
[in]	layer	Pointer to ViLayer structure (such as the one returned by viCreateLayer).

◆ nwindowDequeueBuffer()

Result nwindowDequeueBuffer	(	NWindow *	nw,
		s32 *	out_slot,
		NvMultiFence *	out_fence
	)

Dequeues a buffer from a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[out]	out_slot	Output variable containing the ID of the slot that has been dequeued.
[out]	out_fence	Output 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.

◆ nwindowGetDefault()

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.

◆ nwindowGetDimensions()

Result nwindowGetDimensions	(	NWindow *	nw,
		u32 *	out_width,
		u32 *	out_height
	)

Retrieves the dimensions of a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[out]	out_width	Output variable containing the width of the NWindow.
[out]	out_height	Output 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.

◆ nwindowQueueBuffer()

Result nwindowQueueBuffer	(	NWindow *	nw,
		s32	slot,
		const NvMultiFence *	fence
	)

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

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	slot	ID of the slot to queue. This must match the output of the previous nwindowDequeueBuffer call.
[in]	fence	Pointer to the NvMultiFence that will be waited on by the compositor before queuing/presenting the buffer. Pass NULL if there is no such fence.

◆ nwindowSetCrop()

Result nwindowSetCrop	(	NWindow *	nw,
		s32	left,
		s32	top,
		s32	right,
		s32	bottom
	)

Configures the crop applied to images presented through a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	left	X coordinate of the left margin of the crop bounding box.
[in]	top	Y coordinate of the top margin of the crop bounding box.
[in]	right	X coordinate of the right margin of the crop bounding box.
[in]	bottom	Y 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.

◆ nwindowSetDimensions()

Result nwindowSetDimensions	(	NWindow *	nw,
		u32	width,
		u32	height
	)

Sets the dimensions of a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	width	Desired width of the NWindow.
[in]	height	Desired width of the NWindow.

Note: This function cannot be called when there are buffers registered with the NWindow.

◆ nwindowSetSwapInterval()

Result nwindowSetSwapInterval	(	NWindow *	nw,
		u32	swap_interval
	)

Configures the swap interval of a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	swap_interval	Value 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.

◆ nwindowSetTransform()

Result nwindowSetTransform	(	NWindow *	nw,
		u32	transform
	)

Configures the transformation applied to images presented through a NWindow.

Parameters

[in]	nw	Pointer to NWindow structure.
[in]	transform	Android transformation mode (see NATIVE_WINDOW_TRANSFORM_* enum)

Note: The default transformation is 0 (i.e. no transformation applied)

Data Structures

Functions

Detailed Description

Function Documentation

◆ nwindowCancelBuffer()

◆ nwindowConfigureBuffer()

◆ nwindowCreate()

◆ nwindowCreateFromLayer()

◆ nwindowDequeueBuffer()

◆ nwindowGetDefault()

◆ nwindowGetDimensions()

◆ nwindowQueueBuffer()

◆ nwindowSetCrop()

◆ nwindowSetDimensions()

◆ nwindowSetSwapInterval()

◆ nwindowSetTransform()