libnx  v4.2.0
grc.h
Go to the documentation of this file.
1 /**
2  * @file grc.h
3  * @brief GRC Game Recording (grc:*) service IPC wrapper.
4  * @author yellows8
5  * @copyright libnx Authors
6  */
7 #pragma once
8 #include "../types.h"
9 #include "../sf/service.h"
10 #include "../services/caps.h"
11 #include "../kernel/event.h"
12 #include "../kernel/tmem.h"
13 #include "../display/native_window.h"
14 
15 /// Stream type values for \ref grcdTransfer.
16 typedef enum {
17  GrcStream_Video = 0, ///< Video stream with H.264 NAL units. Official sw uses buffer size 0x32000.
18  GrcStream_Audio = 1, ///< Audio stream with PcmFormat_Int16, 2 channels, and samplerate = 48000Hz. Official sw uses buffer size 0x1000.
19 } GrcStream;
20 
21 /// GameMovieTrimmer
22 typedef struct {
23  Service s; ///< IGameMovieTrimmer
24  TransferMemory tmem; ///< TransferMemory
26 
27 /// IMovieMaker
28 typedef struct {
29  Service a; ///< applet IMovieMaker
30  Service s; ///< grc IMovieMaker
31  Service video_proxy; ///< IHOSBinderDriver VideoProxy
32  Event recording_event; ///< Output Event from GetOffscreenLayerRecordingFinishReadyEvent with autoclear=false.
33  Event audio_event; ///< Output Event from GetOffscreenLayerAudioEncodeReadyEvent with autoclear=false.
34  TransferMemory tmem; ///< TransferMemory
35  NWindow win; ///< \ref NWindow
36  u64 layer_handle; ///< LayerHandle
37  bool layer_open; ///< Whether OpenOffscreenLayer was used successfully, indicating that CloseOffscreenLayer should be used during \ref grcMovieMakerClose.
38  bool started_flag; ///< Whether \ref grcMovieMakerStart was used successfully. This is also used by \ref grcMovieMakerAbort.
40 
41 /// GameMovieId
42 typedef struct {
43  CapsAlbumFileId file_id; ///< \ref CapsAlbumFileId
44  u8 reserved[0x28]; ///< Unused, always zero.
46 
47 /// OffscreenRecordingParameter
48 typedef struct {
49  u8 unk_x0[0x10]; ///< Unknown. Default value is 0.
50  u32 unk_x10; ///< Unknown. Must match value 0x103, which is the default value.
51 
52  s32 video_bitrate; ///< VideoBitRate, 0 is invalid. Default value is 8000000.
53  s32 video_width; ///< VideoWidth, must match 1280 or 1920. Default value is 1280.
54  s32 video_height; ///< VideoHeight, must match 720 or 1080. Default value is 720.
55  s32 video_framerate; ///< VideoFrameRate, must match 30 or 60. Default value is 30.
56  s32 video_keyFrameInterval; ///< VideoKeyFrameInterval, 0 is invalid. Default value is 30.
57 
58  s32 audio_bitrate; ///< AudioBitRate. Default value is 128000 ([5.0.0-5.1.0] 1536000).
59  s32 audio_samplerate; ///< AudioSampleRate, 0 is invalid. Default value is 48000.
60  s32 audio_channel_count; ///< AudioChannelCount. Must match 2, which is the default value.
61  s32 audio_sample_format; ///< \ref PcmFormat AudioSampleFormat. Must match PcmFormat_Int16, which is the default value.
62 
63  s32 video_imageOrientation; ///< \ref AlbumImageOrientation VideoImageOrientation. Default value is ::AlbumImageOrientation_Unknown0.
64 
65  u8 unk_x3c[0x44]; ///< Unknown. Default value is 0.
67 
68 /// Default size for \ref grcCreateMovieMaker, this is the size used by official sw.
69 #define GRC_MOVIEMAKER_WORKMEMORY_SIZE_DEFAULT 0x6000000
70 
71 ///@name Trimming
72 ///@{
73 
74 /**
75  * @brief Creates a \ref GrcGameMovieTrimmer using \ref appletCreateGameMovieTrimmer, uses the cmds from it to trim the specified video, then closes it.
76  * @note See \ref appletCreateGameMovieTrimmer for the requirements for using this.
77  * @note This will block until video trimming finishes.
78  * @param[out] dst_movieid \ref GrcGameMovieId for the output video.
79  * @param[in] src_movieid \ref GrcGameMovieId for the input video.
80  * @param[in] tmem_size TransferMemory size. Official sw uses size 0x2000000.
81  * @param[in] thumbnail Optional, can be NULL. RGBA8 1280x720 thumbnail image data.
82  * @param[in] start Start timestamp in 0.5s units.
83  * @param[in] end End timestamp in 0.5s units.
84  */
85 Result grcTrimGameMovie(GrcGameMovieId *dst_movieid, const GrcGameMovieId *src_movieid, size_t tmem_size, const void* thumbnail, s32 start, s32 end);
86 
87 ///@}
88 
89 ///@name IMovieMaker
90 ///@{
91 
92 /**
93  * @brief Creates a \ref GrcOffscreenRecordingParameter with the default values, see \ref GrcOffscreenRecordingParameter for the default values.
94  * @param[out] param \ref GrcOffscreenRecordingParameter
95  */
97 
98 /**
99  * @brief Creates a \ref GrcMovieMaker using \ref appletCreateMovieMaker, and does the required initialization.
100  * @note See \ref appletCreateMovieMaker for the requirements for using this.
101  * @param[out] m \ref GrcMovieMaker
102  * @param[in] size TransferMemory WorkMemory size. See \ref GRC_MOVIEMAKER_WORKMEMORY_SIZE_DEFAULT.
103  */
104 Result grcCreateMovieMaker(GrcMovieMaker *m, size_t size);
105 
106 /**
107  * @brief Closes a \ref GrcMovieMaker.
108  * @note This also uses \ref grcMovieMakerAbort.
109  * @param m \ref GrcMovieMaker
110  */
112 
113 /**
114  * @brief Gets the \ref NWindow for the specified MovieMaker.
115  * @param m \ref GrcMovieMaker
116  */
118  return &m->win;
119 }
120 
121 /**
122  * @brief Aborts recording with the specified MovieMaker.
123  * @note This is used automatically by \ref grcMovieMakerClose.
124  * @note This will throw an error if \ref grcMovieMakerStart was not used previously, with the flag used for this being cleared afterwards on success.
125  * @param m \ref GrcMovieMaker
126  */
128 
129 /**
130  * @brief Starts recording with the specified MovieMaker and \ref GrcOffscreenRecordingParameter.
131  * @param m \ref GrcMovieMaker
132  * @param[in] param \ref GrcOffscreenRecordingParameter
133  */
135 
136 /**
137  * @brief Finishes recording with the specified MovieMaker.
138  * @note This automatically uses \ref grcMovieMakerAbort on error.
139  * @note The recorded video will not be accessible via the Album-applet since it's stored separately from other Album data.
140  * @param m \ref GrcMovieMaker
141  * @param width Width for the thumbnail, must be 1280.
142  * @param height Height for the thumbnail, must be 720.
143  * @param[in] userdata UserData input buffer for the JPEG thumbnail. Optional, can be NULL.
144  * @param[in] userdata_size Size of the UserData input buffer. Optional, can be 0. Must be <=0x400.
145  * @param[in] thumbnail RGBA8 image buffer containing the thumbnail. Optional, can be NULL.
146  * @param[in] thumbnail_size Size of the thumbnail buffer. Optional, can be 0.
147  * @param[out] entry Output \ref CapsApplicationAlbumEntry for the recorded video. Optional, can be NULL. Only available on [7.0.0+], if this is not NULL on pre-7.0.0 an error is thrown.
148  */
149 Result grcMovieMakerFinish(GrcMovieMaker *m, s32 width, s32 height, const void* userdata, size_t userdata_size, const void* thumbnail, size_t thumbnail_size, CapsApplicationAlbumEntry *entry);
150 
151 /**
152  * @brief Gets the recording error with the specified MovieMaker.
153  * @param m \ref GrcMovieMaker
154  */
156 
157 /**
158  * @brief Encodes audio sample data with the specified MovieMaker.
159  * @note This waits on the event and uses the cmd repeatedly until the entire input buffer is handled.
160  * @note If you don't use this the recorded video will be missing audio.
161  * @param m \ref GrcMovieMaker
162  * @param[in] buffer Audio buffer.
163  * @param[in] size Size of the buffer.
164  */
165 Result grcMovieMakerEncodeAudioSample(GrcMovieMaker *m, const void* buffer, size_t size);
166 
167 ///@}
168 
169 ///@name grc:d
170 ///@{
171 
172 /// Initialize grc:d.
173 Result grcdInitialize(void);
174 
175 /// Exit grc:d.
176 void grcdExit(void);
177 
178 /// Gets the Service for grc:d.
180 
181 /// Begins streaming. This must not be called more than once, even from a different service session: otherwise the sysmodule will assert.
182 Result grcdBegin(void);
183 
184 /**
185  * @brief Retrieves stream data from the continuous recorder in use (from the video recording of the currently running application).
186  * @note This will block until data is available. This will hang if there is no application running which has video capture enabled.
187  * @param[in] stream \ref GrcStream
188  * @param[out] buffer Output buffer.
189  * @param[in] size Max size of the output buffer.
190  * @param[out] num_frames num_frames
191  * @param[out] data_size Actual output data size.
192  * @param[out] start_timestamp Start timestamp.
193  */
194 Result grcdTransfer(GrcStream stream, void* buffer, size_t size, u32 *num_frames, u32 *data_size, u64 *start_timestamp);
195 
196 ///@}
197 
GrcMovieMaker::layer_open
bool layer_open
Whether OpenOffscreenLayer was used successfully, indicating that CloseOffscreenLayer should be used ...
Definition: grc.h:37
grcTrimGameMovie
Result grcTrimGameMovie(GrcGameMovieId *dst_movieid, const GrcGameMovieId *src_movieid, size_t tmem_size, const void *thumbnail, s32 start, s32 end)
Creates a GrcGameMovieTrimmer using appletCreateGameMovieTrimmer, uses the cmds from it to trim the s...
GrcOffscreenRecordingParameter::video_framerate
s32 video_framerate
VideoFrameRate, must match 30 or 60. Default value is 30.
Definition: grc.h:55
GrcOffscreenRecordingParameter::audio_bitrate
s32 audio_bitrate
AudioBitRate. Default value is 128000 ([5.0.0-5.1.0] 1536000).
Definition: grc.h:58
GrcGameMovieId
GameMovieId.
Definition: grc.h:42
GrcOffscreenRecordingParameter
OffscreenRecordingParameter.
Definition: grc.h:48
GrcMovieMaker::s
Service s
grc IMovieMaker
Definition: grc.h:30
GrcStream_Audio
@ GrcStream_Audio
Audio stream with PcmFormat_Int16, 2 channels, and samplerate = 48000Hz. Official sw uses buffer size...
Definition: grc.h:18
GrcOffscreenRecordingParameter::audio_sample_format
s32 audio_sample_format
PcmFormat AudioSampleFormat. Must match PcmFormat_Int16, which is the default value.
Definition: grc.h:61
grcdExit
void grcdExit(void)
Exit grc:d.
u8
uint8_t u8
8-bit unsigned integer.
Definition: types.h:19
Event
Kernel-mode event structure.
Definition: event.h:13
GrcMovieMaker::a
Service a
applet IMovieMaker
Definition: grc.h:29
TransferMemory
Transfer memory information structure.
Definition: tmem.h:13
grcMovieMakerAbort
Result grcMovieMakerAbort(GrcMovieMaker *m)
Aborts recording with the specified MovieMaker.
s32
int32_t s32
32-bit signed integer.
Definition: types.h:27
GrcMovieMaker
IMovieMaker.
Definition: grc.h:28
CapsAlbumFileId
AlbumEntryId.
Definition: caps.h:91
grcMovieMakerClose
void grcMovieMakerClose(GrcMovieMaker *m)
Closes a GrcMovieMaker.
GrcMovieMaker::win
NWindow win
NWindow
Definition: grc.h:35
grcdTransfer
Result grcdTransfer(GrcStream stream, void *buffer, size_t size, u32 *num_frames, u32 *data_size, u64 *start_timestamp)
Retrieves stream data from the continuous recorder in use (from the video recording of the currently ...
grcMovieMakerGetError
Result grcMovieMakerGetError(GrcMovieMaker *m)
Gets the recording error with the specified MovieMaker.
GrcStream_Video
@ GrcStream_Video
Video stream with H.264 NAL units. Official sw uses buffer size 0x32000.
Definition: grc.h:17
GrcMovieMaker::video_proxy
Service video_proxy
IHOSBinderDriver VideoProxy.
Definition: grc.h:31
GrcOffscreenRecordingParameter::video_width
s32 video_width
VideoWidth, must match 1280 or 1920. Default value is 1280.
Definition: grc.h:53
u32
uint32_t u32
32-bit unsigned integer.
Definition: types.h:21
GrcMovieMaker::recording_event
Event recording_event
Output Event from GetOffscreenLayerRecordingFinishReadyEvent with autoclear=false.
Definition: grc.h:32
grcCreateOffscreenRecordingParameter
void grcCreateOffscreenRecordingParameter(GrcOffscreenRecordingParameter *param)
Creates a GrcOffscreenRecordingParameter with the default values, see GrcOffscreenRecordingParameter ...
GrcStream
GrcStream
Stream type values for grcdTransfer.
Definition: grc.h:16
GrcOffscreenRecordingParameter::video_imageOrientation
s32 video_imageOrientation
AlbumImageOrientation VideoImageOrientation. Default value is AlbumImageOrientation_Unknown0.
Definition: grc.h:63
grcMovieMakerGetNWindow
static NWindow * grcMovieMakerGetNWindow(GrcMovieMaker *m)
Gets the NWindow for the specified MovieMaker.
Definition: grc.h:117
u64
uint64_t u64
64-bit unsigned integer.
Definition: types.h:22
GrcMovieMaker::started_flag
bool started_flag
Whether grcMovieMakerStart was used successfully. This is also used by grcMovieMakerAbort.
Definition: grc.h:38
GrcGameMovieTrimmer::s
Service s
IGameMovieTrimmer.
Definition: grc.h:23
Result
u32 Result
Function error code result type.
Definition: types.h:44
GrcGameMovieTrimmer
GameMovieTrimmer.
Definition: grc.h:22
GrcGameMovieId::file_id
CapsAlbumFileId file_id
CapsAlbumFileId
Definition: grc.h:43
grcMovieMakerStart
Result grcMovieMakerStart(GrcMovieMaker *m, const GrcOffscreenRecordingParameter *param)
Starts recording with the specified MovieMaker and GrcOffscreenRecordingParameter.
grcdBegin
Result grcdBegin(void)
Begins streaming. This must not be called more than once, even from a different service session: othe...
NWindow
Native window structure.
Definition: native_window.h:17
GrcMovieMaker::layer_handle
u64 layer_handle
LayerHandle.
Definition: grc.h:36
CapsApplicationAlbumEntry
ApplicationAlbumEntry.
Definition: caps.h:106
grcdGetServiceSession
Service * grcdGetServiceSession(void)
Gets the Service for grc:d.
GrcOffscreenRecordingParameter::unk_x10
u32 unk_x10
Unknown. Must match value 0x103, which is the default value.
Definition: grc.h:50
GrcOffscreenRecordingParameter::audio_samplerate
s32 audio_samplerate
AudioSampleRate, 0 is invalid. Default value is 48000.
Definition: grc.h:59
GrcMovieMaker::tmem
TransferMemory tmem
TransferMemory.
Definition: grc.h:34
grcCreateMovieMaker
Result grcCreateMovieMaker(GrcMovieMaker *m, size_t size)
Creates a GrcMovieMaker using appletCreateMovieMaker, and does the required initialization.
GrcOffscreenRecordingParameter::audio_channel_count
s32 audio_channel_count
AudioChannelCount. Must match 2, which is the default value.
Definition: grc.h:60
Service
Service object structure.
Definition: service.h:13
GrcOffscreenRecordingParameter::video_height
s32 video_height
VideoHeight, must match 720 or 1080. Default value is 720.
Definition: grc.h:54
GrcMovieMaker::audio_event
Event audio_event
Output Event from GetOffscreenLayerAudioEncodeReadyEvent with autoclear=false.
Definition: grc.h:33
GrcGameMovieTrimmer::tmem
TransferMemory tmem
TransferMemory.
Definition: grc.h:24
grcMovieMakerEncodeAudioSample
Result grcMovieMakerEncodeAudioSample(GrcMovieMaker *m, const void *buffer, size_t size)
Encodes audio sample data with the specified MovieMaker.
grcMovieMakerFinish
Result grcMovieMakerFinish(GrcMovieMaker *m, s32 width, s32 height, const void *userdata, size_t userdata_size, const void *thumbnail, size_t thumbnail_size, CapsApplicationAlbumEntry *entry)
Finishes recording with the specified MovieMaker.
GrcOffscreenRecordingParameter::video_bitrate
s32 video_bitrate
VideoBitRate, 0 is invalid. Default value is 8000000.
Definition: grc.h:52
GrcOffscreenRecordingParameter::video_keyFrameInterval
s32 video_keyFrameInterval
VideoKeyFrameInterval, 0 is invalid. Default value is 30.
Definition: grc.h:56
grcdInitialize
Result grcdInitialize(void)
Initialize grc:d.