libnx  v4.6.0
framebuffer.h
Go to the documentation of this file.
1 /**
2  * @file framebuffer.h
3  * @brief Framebuffer wrapper object, providing support for software rendered graphics.
4  * @author fincs
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../nvidia/map.h"
9 #include "native_window.h"
10 
11 /// Converts red/green/blue/alpha components to packed RGBA8 (i.e. \ref PIXEL_FORMAT_RGBA_8888).
12 #define RGBA8(r,g,b,a) (((r)&0xff)|(((g)&0xff)<<8)|(((b)&0xff)<<16)|(((a)&0xff)<<24))
13 
14 /// Same as \ref RGBA8 except with alpha=0xff.
15 #define RGBA8_MAXALPHA(r,g,b) RGBA8((r),(g),(b),0xff)
16 
17 /// Converts red/green/blue to packed RGBX8 (i.e. \ref PIXEL_FORMAT_RGBX_8888).
18 #define RGBX8(r,g,b) RGBA8((r),(g),(b),0)
19 
20 /// Converts red/green/blue components to packed RGB565 (i.e. \ref PIXEL_FORMAT_RGB_565)
21 #define RGB565(r,g,b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11))
22 
23 /// Same as \ref RGB565 but accepting 8-bit components as input instead.
24 #define RGB565_FROM_RGB8(r,g,b) RGB565((r)>>3,(g)>>2,(b)>>3)
25 
26 /// Converts red/green/blue/alpha components to packed BGR8 (i.e. \ref PIXEL_FORMAT_BGRA_8888).
27 #define BGRA8(r,g,b,a) RGBA8((b),(g),(r),(a))
28 
29 /// Same as \ref BGRA8 except with alpha=0xff.
30 #define BGRA8_MAXALPHA(r,g,b) RGBA8((b),(g),(r),0xff)
31 
32 /// Converts red/green/blue/alpha components to packed RGBA4 (i.e. \ref PIXEL_FORMAT_RGBA_4444).
33 #define RGBA4(r,g,b,a) (((r)&0xf)|(((g)&0xf)<<4)|(((b)&0xf)<<8)|(((a)&0xf)<<12))
34 
35 /// Same as \ref RGBA4 except with alpha=0xf.
36 #define RGBA4_MAXALPHA(r,g,b) RGBA4((r),(g),(b),0xf)
37 
38 /// Same as \ref RGBA4 but accepting 8-bit components as input instead.
39 #define RGBA4_FROM_RGBA8(r,g,b,a) RGBA4((r)>>4,(g)>>4,(b)>>4,(a)>>4)
40 
41 /// Same as \ref RGBA4_MAXALPHA except with alpha=0xff.
42 #define RGBA4_FROM_RGBA8_MAXALPHA(r,g,b) RGBA4_MAXALPHA((r)>>4,(g)>>4,(b)>>4)
43 
44 /// Framebuffer structure.
45 typedef struct Framebuffer {
46  NWindow *win;
47  NvMap map;
48  void* buf;
49  void* buf_linear;
50  u32 stride;
51  u32 width_aligned;
52  u32 height_aligned;
53  u32 num_fbs;
54  u32 fb_size;
55  bool has_init;
56 } Framebuffer;
57 
58 /**
59  * @brief Creates a \ref Framebuffer object.
60  * @param[out] fb Output \ref Framebuffer structure.
61  * @param[in] win Pointer to the \ref NWindow to which the \ref Framebuffer will be registered.
62  * @param[in] width Desired width of the framebuffer (usually 1280).
63  * @param[in] height Desired height of the framebuffer (usually 720).
64  * @param[in] format Desired pixel format (see PIXEL_FORMAT_* enum).
65  * @param[in] num_fbs Number of buffers to create. Pass 1 for single-buffering, 2 for double-buffering or 3 for triple-buffering.
66  * @note Framebuffer images are stored in Tegra block linear format with 16Bx2 sector ordering, read TRM chapter 20.1 for more details.
67  * In order to use regular linear layout, consider calling \ref framebufferMakeLinear after the \ref Framebuffer object is created.
68  * @note Presently, only the following pixel formats are supported:
69  * \ref PIXEL_FORMAT_RGBA_8888
70  * \ref PIXEL_FORMAT_RGBX_8888
71  * \ref PIXEL_FORMAT_RGB_565
72  * \ref PIXEL_FORMAT_BGRA_8888
73  * \ref PIXEL_FORMAT_RGBA_4444
74  */
75 Result framebufferCreate(Framebuffer* fb, NWindow *win, u32 width, u32 height, u32 format, u32 num_fbs);
76 
77 /// Enables linear framebuffer mode in a \ref Framebuffer, allocating a shadow buffer in the process.
79 
80 /// Closes a \ref Framebuffer object, freeing all resources associated with it.
82 
83 /**
84  * @brief Begins rendering a frame in a \ref Framebuffer.
85  * @param[in] fb Pointer to \ref Framebuffer structure.
86  * @param[out] out_stride Output variable containing the distance in bytes between rows of pixels in memory.
87  * @return Pointer to buffer to which new graphics data should be written to.
88  * @note When this function is called, a buffer will be dequeued from the corresponding \ref NWindow.
89  * @note This function will return pointers to different buffers, depending on the number of buffers it was initialized with.
90  * @note If \ref framebufferMakeLinear was used, this function will instead return a pointer to the shadow linear buffer.
91  * In this case, the offset of a pixel is \p y * \p out_stride + \p x * \p bytes_per_pixel.
92  * @note Each call to \ref framebufferBegin must be paired with a \ref framebufferEnd call.
93  */
94 void* framebufferBegin(Framebuffer* fb, u32* out_stride);
95 
96 /**
97  * @brief Finishes rendering a frame in a \ref Framebuffer.
98  * @param[in] fb Pointer to \ref Framebuffer structure.
99  * @note When this function is called, the written image data will be flushed and queued (presented) in the corresponding \ref NWindow.
100  * @note If \ref framebufferMakeLinear was used, this function will copy the image from the shadow linear buffer to the actual framebuffer,
101  * converting it in the process to the layout expected by the compositor.
102  * @note Each call to \ref framebufferBegin must be paired with a \ref framebufferEnd call.
103  */
Result framebufferCreate(Framebuffer *fb, NWindow *win, u32 width, u32 height, u32 format, u32 num_fbs)
Creates a Framebuffer object.
void * framebufferBegin(Framebuffer *fb, u32 *out_stride)
Begins rendering a frame in a Framebuffer.
Result framebufferMakeLinear(Framebuffer *fb)
Enables linear framebuffer mode in a Framebuffer, allocating a shadow buffer in the process.
void framebufferEnd(Framebuffer *fb)
Finishes rendering a frame in a Framebuffer.
void framebufferClose(Framebuffer *fb)
Closes a Framebuffer object, freeing all resources associated with it.
Native window (NWindow) wrapper object, used for presenting images to the display (or other sinks).
Framebuffer structure.
Definition: framebuffer.h:45
Native window structure.
Definition: native_window.h:17
Definition: map.h:4
u32 Result
Function error code result type.
Definition: types.h:44
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21