From 85d763f47eb6eb38a526c0c383f78eb936f5d61a Mon Sep 17 00:00:00 2001 From: Charu Kalani Date: Tue, 23 Jan 2018 11:10:36 -0800 Subject: Push GfeSDK #173 --- doc/html/_c_h_a_n_g_e_l_o_g_8md_source.html | 2 +- doc/html/_m_a_i_n_p_a_g_e_8md_source.html | 2 +- doc/html/config_8h_source.html | 6 ++--- doc/html/files.html | 6 ++--- doc/html/files.js | 2 +- doc/html/gfe3__product__version_8h_source.html | 6 ++--- doc/html/highlights__types__cpp_8h_source.html | 24 ++++++++++---------- doc/html/ihighlights__cpp_8h_source.html | 14 ++++++------ doc/html/ihighlights__cpp__impl_8h_source.html | 18 +++++++-------- doc/html/index.html | 26 +++++++++++----------- doc/html/navtreedata.js | 2 +- doc/html/navtreeindex0.js | 20 ++++++++--------- doc/html/navtreeindex1.js | 1 + doc/html/sdk__types__ipc_8h_source.html | 6 ++--- doc/html/section_changelog.html | 8 ++++++- ..._d_k_1_1_get_number_of_highlights_response.html | 2 +- ...t_gfe_s_d_k_1_1_get_user_settings_response.html | 2 +- doc/html/struct_gfe_s_d_k_1_1_group_view.html | 2 +- ...gfe_s_d_k_1_1_highlight_close_group_params.html | 2 +- ...ruct_gfe_s_d_k_1_1_highlight_config_params.html | 2 +- ...gfe_s_d_k_1_1_highlight_definition-members.html | 11 ++++----- .../struct_gfe_s_d_k_1_1_highlight_definition.js | 1 + ..._gfe_s_d_k_1_1_highlight_open_group_params.html | 2 +- ...truct_gfe_s_d_k_1_1_highlight_user_setting.html | 2 +- ..._gfe_s_d_k_1_1_screenshot_highlight_params.html | 2 +- doc/html/struct_gfe_s_d_k_1_1_summary_params.html | 2 +- ...truct_gfe_s_d_k_1_1_video_highlight_params.html | 2 +- 27 files changed, 92 insertions(+), 83 deletions(-) (limited to 'doc/html') diff --git a/doc/html/_c_h_a_n_g_e_l_o_g_8md_source.html b/doc/html/_c_h_a_n_g_e_l_o_g_8md_source.html index ca64837..23b013a 100644 --- a/doc/html/_c_h_a_n_g_e_l_o_g_8md_source.html +++ b/doc/html/_c_h_a_n_g_e_l_o_g_8md_source.html @@ -85,7 +85,7 @@ $(document).ready(function(){initNavTree('_c_h_a_n_g_e_l_o_g_8md.html','');});
C:/u/workspace/dev/sdkwinauto/doc/CHANGELOG.md
-
1 # Changelog {#section_changelog}
2 
3 ## NVIDIA GfeSDK 1.0 (2018-01-16)
4 
5 ### Features for GFE 3.13+
6 * **UWP Support** Add support to Universal Windows Platform games
7 * **Target PID** Add support for whitelisted apps to record another process's PID
8 
9 ### API Changes
10 * **Target PID** Added to NVGSDK_Create call
11 * **Unannounced Highlight Type** To prevent showing Highlights notifications for certain applications
12 
13 ### Improvements
14 * **UWP Sample App** Add a new sample MarbleMaze app that demostrates a full Highlights integration
15 
16 ### Bug Fixes
17 * **Fix Crash** Was occasionally crashing when communication with the backend could not be established
18 
19 ## NVIDIA GfeSDK 1.0 (2017-08-01)
20 
21 ### API Changes
22 * **Timeout:** Was returning NVGSDK_ERR_GENERIC when IPC call timed now. Now returning NVGSDK_ERR_IPC_FAILED
23 * **windows.h:** Removed windows.h from public includes
24 * **globals:** Removed macros from global namespace
25 * **stdint:** Standardize on stdint types
26 * **stdbool:** Use stdbool in C API instead of integer 0/1
27 * **namespace:** Renamed namespace from gfesdk to GfeSDK, and wrapped C API in namespace when using C++ bindings
28 * **Highlights split:** Split all Highlights features into their own headers
29 * **C++ Bindings RAII:** Update C++ bindings to follow recognized C++ idioms
30 * **package structure:** Standardize package structure to look like other GameWorks packages
31 * **Typed Callbacks:** Return typed callback data instead of void*
32 * **Naming:** Match naming standard to other GameWorks packages
33 
34 ### Improvements
35 * **Thread Model**: Improve thread model. Prevent callbacks from occurring after Release. Allow Polling of callbacks
36 * **Documentation**: Improved and expanded documentation
37 
38 ### Bug Fixes
39 * **Whitelist:** Fix error causing ShadowPlay to not whitelist game correctly.
40 * **Fix crash:** Was crashing when the same game ran twice.
41 * **Input validation:** Added input validation to return an error for C++ create instead of crash
42 * **Timeout return value:** Was returning NVGSDK_ERR_GENERIC instead of NVGSDK_ERR_IPC_FAILED
43 
44 ### Features for GFE 3.9+
45 * **In-Game Overlay Notification:** Notify the app when the in-game overlay opens or closes.
46 
47 ## NVIDIA GfeSDK 1.0 (2017-07-10)
48 
49 ### Features for GFE 3.8+
50 
51 * **ShadowPlay Highlights** Help Gamers automatically capture their most exciting gaming moments.
52 
+
1 # Changelog {#section_changelog}
2 
3 ## NVIDIA GfeSDK 1.1 (2018-01-22)
4 
5 ### API Changes
6 * **SDK version incremented to 1.1** Allows old SDK clients to work with upcoming 3.13 GFE
7 * **Highlights Config parameters validation** Rejects Highlights of invalid type and significance
8 
9 ## NVIDIA GfeSDK 1.0 (2018-01-16)
10 
11 ### Features for GFE 3.13+
12 * **UWP Support** Add support to Universal Windows Platform games
13 * **Target PID** Add support for whitelisted apps to record another process's PID
14 
15 ### API Changes
16 * **Target PID** Added to NVGSDK_Create call
17 * **Unannounced Highlight Type** To prevent showing Highlights notifications for certain applications
18 
19 ### Improvements
20 * **UWP Sample App** Add a new sample MarbleMaze app that demostrates a full Highlights integration
21 
22 ### Bug Fixes
23 * **Fix Crash** Was occasionally crashing when communication with the backend could not be established
24 
25 ## NVIDIA GfeSDK 1.0 (2017-08-01)
26 
27 ### API Changes
28 * **Timeout:** Was returning NVGSDK_ERR_GENERIC when IPC call timed now. Now returning NVGSDK_ERR_IPC_FAILED
29 * **windows.h:** Removed windows.h from public includes
30 * **globals:** Removed macros from global namespace
31 * **stdint:** Standardize on stdint types
32 * **stdbool:** Use stdbool in C API instead of integer 0/1
33 * **namespace:** Renamed namespace from gfesdk to GfeSDK, and wrapped C API in namespace when using C++ bindings
34 * **Highlights split:** Split all Highlights features into their own headers
35 * **C++ Bindings RAII:** Update C++ bindings to follow recognized C++ idioms
36 * **package structure:** Standardize package structure to look like other GameWorks packages
37 * **Typed Callbacks:** Return typed callback data instead of void*
38 * **Naming:** Match naming standard to other GameWorks packages
39 
40 ### Improvements
41 * **Thread Model**: Improve thread model. Prevent callbacks from occurring after Release. Allow Polling of callbacks
42 * **Documentation**: Improved and expanded documentation
43 
44 ### Bug Fixes
45 * **Whitelist:** Fix error causing ShadowPlay to not whitelist game correctly.
46 * **Fix crash:** Was crashing when the same game ran twice.
47 * **Input validation:** Added input validation to return an error for C++ create instead of crash
48 * **Timeout return value:** Was returning NVGSDK_ERR_GENERIC instead of NVGSDK_ERR_IPC_FAILED
49 
50 ### Features for GFE 3.9+
51 * **In-Game Overlay Notification:** Notify the app when the in-game overlay opens or closes.
52 
53 ## NVIDIA GfeSDK 1.0 (2017-07-10)
54 
55 ### Features for GFE 3.8+
56 
57 * **ShadowPlay Highlights** Help Gamers automatically capture their most exciting gaming moments.
58 
diff --git a/doc/html/_m_a_i_n_p_a_g_e_8md_source.html b/doc/html/_m_a_i_n_p_a_g_e_8md_source.html index f55c858..3d2be66 100644 --- a/doc/html/_m_a_i_n_p_a_g_e_8md_source.html +++ b/doc/html/_m_a_i_n_p_a_g_e_8md_source.html @@ -85,7 +85,7 @@ $(document).ready(function(){initNavTree('_m_a_i_n_p_a_g_e_8md.html','');});
MAINPAGE.md
-
1 # Development Guide # {#mainpage}
2 
3 # NVIDIA GeForce Experience SDK # {#section_main}
4 
5 * Version: 1.0.168.8a267a87
6 * GeForce Experience minimum version: 3.8
7 * See [Changelog](\ref section_changelog)
8 
9 ## At a Glance {#section_glance}
10 
11 The GeForce SDK (GfeSDK) is a means for games to integrate with ShadowPlay Highlights allowing them to capture videos
12 and screenshots and present the resulting highlights back to users for viewing and sharing. GfeSDK will add other features
13 over time that benefit from games and applications working in concert with GFE functionality.
14 
15 ![Shadowplay Highlights](/img/gfesdk_highlights.png)
16 
17 ### Software Stack {#section_stack}
18 
19 ![Software Stack](/img/gfesdk_block.png)
20 
21 An application integrates with the GfeSDK via either the provided Unreal Engine 4 plug-in, C++ interface, or C interface. This integration, via the SDK, calls a compatible GFE 3.0 release.
22 
23 The developer (or associated publisher) distributes the application (including associated SDK libraries).
24 
25 NVIDIA distributes a GfeSDK package coupled with GfeSDK-compatible GFE releases. GFE maintains backwards SDK-compatibility; games integrated with older SDKs work with newer GFE releases.
26 
27 ### GfeSDK Package {#section_package}
28 
29 The distribution will look like the following
30 ```
31 .
32 +-- README.md
33 +-- LICENSE
34 +-- doc
35 | +-- index.html # Points to the deeper index.html
36 | +-- html
37 | | +-- index.html
38 | | ...
39 +-- include
40 | +-- gfesdk
41 | | +-- bindings
42 | | | +-- cpp # C++ bindings that sit on top of C API
43 | | +-- isdk.h
44 | | ...
45 +-- lib
46 | +-- win32
47 | | +-- GfeSDK.lib # x86 Import library for linking
48 | +-- win64
49 | | +-- GfeSDK.lib # x64 Import library for linking
50 +-- redist
51 | +-- assets
52 | | +-- img
53 | | | +-- xxxx.png # Images the game may redistribute
54 | +-- win32
55 | | +-- GfeSDK.dll # x86 DLL to be shipped with the game
56 | +-- win64
57 | | +-- GfeSDK.dll # x64 DLL to be shipped with the game
58 +-- samples
59 | +-- bin
60 | | +-- UnrealDemo # Binary game that demonstrates GfeSDK + Highlights
61 ```
62 
63 ### Compiling And Linking {#section_compiling}
64 
65 To compile, add the ./include (not the ./include/gfesdk) directory to the compiler's list of includes. The import libraries
66 are found in the ./lib folder and can be used to link the symbols into the game's executable. The proper GfeSDK.dll file
67 will need to be distributed with the game in a place that the game can find it.
68 
69 The C++ bindings are currently distributed in header-only form to avoid ABI incompatibilities between different compiler
70 versions. The linking and include steps are the same.
71 
72 ## Using GfeSDK ## {#section_using}
73 
74 Creation and destruction of an SDK instance is a prerequisite to making calls
75 to the SDK. The means of creating and destroying an instance depend on which
76 integration mechanism the client employs:
77 
78 See [Core header documentation](\ref isdk.h)
79 
80 See [Highlights header documentation](\ref ihighlights.h)
81 
82 ### Creation and Release {#section_example_create}
83 
84 #### C++ Bindings
85 
86 \snippet GfeSDKDemo.cpp Creation CPP
87 
88 // After using GfeSDK
89 
90 \snippet GfeSDKDemo.cpp Release CPP
91 
92 #### C API
93 
94 \snippet GfeSDKDemo.cpp Creation
95 
96 // After using GfeSDK
97 
98 \snippet GfeSDKDemo.cpp Release
99 
100 ### Request Permissions {#section_example_permission}
101 
102 The Create call will inform the app if one or more scopes require user
103 permission. If so, make this call. It will display the overlay UI.
104 
105 #### C++ Bindings
106 
107 \snippet GfeSDKDemo.cpp Permissions CPP
108 
109 #### C API
110 
111 \snippet GfeSDKDemo.cpp Permissions
112 
113 ### Configure Highlights {#section_example_highlightsconfigure}
114 
115 This only needs to happen once ever. It is persistent. It could even happen
116 during game installation.
117 
118 #### C++ Bindings
119 
120 \snippet GfeSDKDemo.cpp ConfigureHighlights CPP
121 
122 #### C API
123 
124 \snippet GfeSDKDemo.cpp ConfigureHighlights
125 
126 ### Groups and Saving Highlights {#section_Example_highlights}
127 
128 #### C++ Bindings
129 
130 \snippet GfeSDKDemo.cpp OpenGroup CPP
131 \snippet GfeSDKDemo.cpp SaveVideo CPP
132 \snippet GfeSDKDemo.cpp CloseGroup CPP
133 
134 #### C API
135 
136 \snippet GfeSDKDemo.cpp OpenGroup
137 \snippet GfeSDKDemo.cpp SaveVideo
138 \snippet GfeSDKDemo.cpp CloseGroup
139 
140 ### Open Highlight Summary {#section_example_summary}
141 
142 #### C++ Bindings
143 
144 \snippet GfeSDKDemo.cpp OpenSummary CPP
145 
146 #### C API
147 
148 \snippet GfeSDKDemo.cpp OpenSummary
149 
150 ## Concepts {#section_concepts}
151 
152 The GfeSDK is composed of two parts, the client/app, and the backend/server.
153 This distribution contains GfeSDK.dll which represents the client/app part.
154 The end-user downloads GFE onto their machine. The GFE package includes the
155 backend pieces necessary to support the calls coming from the client. See
156 \ref section_version for more information regarding this communication.
157 
158 Calls made will be serialized. Therefore, if the app makes two consecutive
159 calls to NVGSDK_Highlights_OpenGroup and then either
160 NVGSDK_Highlights_SetVideoHighlight or NVGSDK_Highlights_SetScreenshotHighlight,
161 before receiving the callback from open group, the set highlight call will
162 function normally. If open group succeeded, then the set highlights calls will
163 succeed as well. If it failed, the set highlights calls will fail, as there
164 will be no valid group to assign them to.
165 
166 ### Strings {#section_strings}
167 All strings are to be provided in single-byte width, UTF-8 encoded.
168 
169 ### Versioning {#section_version}
170 Because there are two different parts, and the client / user's machine may
171 be mismatched at times, the game should be aware of the versioning system.
172 It's GfeSDK's goal to make this as seamless as possible, but there could still
173 be compatibility issues to be aware of.
174 
175 The GfeSDK version contains 4 parts, MAJOR.MINOR.BUILD.HASH. The BUILD and HASH
176 components are descriptive and don't have any effect on functionality. The
177 MAJOR component identifies overall compatibility. If the client and server
178 mismatch on the major version number, no communication is possible. **There
179 are no current plans to update from 1, breaking communication**. The major
180 version number gives a way to show incompatibility if the fundamental
181 architecture of GFE ever changes. The minor version number indicates feature
182 compatibility. When a new feature gets added / modified on the SDK, the minor
183 version number will be bumped. This means that for older games / newer GFE
184 installations, the game is simply missing out on newer features. This will
185 generally not be a problem. For a game with a newer version of the GfeSDK,
186 and a user with an older installation of GFE, some features may not function,
187 and the user should be encouraged to update GFE.
188 
189 With that in mind, here are the possible return values from \ref NVGSDK_Create,
190 with regards to versioning:
191 * **NVGSDK_SUCCESS** - Perfect version match
192 * **NVGSDK_SUCCESS_OLD_GFE** - Minor version mismatch. User has an older
193 version of GFE installed. Newer features distributed by the game will not
194 function properly until the user upgrades.
195 * **NVGSDK_SUCCESS_OLD_SDK** - Minor version mismatch.
196 Game is distributing an older version of GfeSDK.
197 Game could be missing out on latest features, but no compatibily issue.
198 * **NVGSDK_ERR_GFE_VERSION** - Major version mismatch. User has a GFE
199 installation that predates the GfeSDK. User must upgrade to get functionality.
200 * **NVGSDK_ERR_SDK_VERSION** - Major version mismatch. GFE has changed
201 fundamentally. **There are no plans to do this. This is to cover all bases**
202 
203 ### Permissions {#section_permissions}
204 Certain actions require permission from the user. For example, recording video
205 for Highlights requires the user to agree to the recording. To achieve this,
206 the app must know what features it wishes to enable. It will pass these
207 "scopes" into the NVGSDK_Create call via NVGSDK_CreateInputParams. Consider
208 the typical Highlights case as an example. The app will pass in a list of
209 the scopes NVGSDK_SCOPE_HIGHLIGHTS, NVGSDK_SCOPE_HIGHLIGHTS_VIDEO, and
210 NVGSDK_SCOPE_SCREENSHOT. The first of these is required in order for any
211 of the NVGSDK_Highlights_* calls to succeed and send a message to the server.
212 It will allocate the resources required in the DLL and on the server in order
213 to achieve this. The second of these permissions is required in order to
214 capture video of the gameplay, and the final is to capture a screenshot.
215 
216 The first time the user runs the game, and the game calls NVGSDK_Create(...),
217 and passes in these three permissions, the game might receive back that
218 NVGSDK_SCOPE_HIGHLIGHTS has been granted permission implicitly, but that
219 NVGSDK_SCOPE_HIGHLIGHTS_VIDEO and NVGSDK_SCOPE_HIGHLIGHTS_SCREENSHOT
220 currently have "must ask" permission. In other words, the game must ask
221 GFE for permission to record video before it will succeed in doing so. To
222 achieve this, the game will call NVGSDK_RequestPermissionsAsync with two
223 scopes in the list, NVGSDK_SCOPE_HIGHLIGHTS_VIDEO and
224 NVGSDK_SCOPE_HIGHLIGHTS_SCREENSHOT. It's not necessary to request permission
225 for a scope that has implicitly been granted permission already.
226 
227 The call to NVGSDK_RequestPermissions is required because it will trigger
228 GFE to put up an \ref section_igo. The game might not want this to occur
229 during NVGSDK_Create time. Once called, the user will see the overlay
230 pop up, asking them for permission.
231 
232 ![Highlights Permission](/img/permission.png)
233 
234 The async callback will be triggered as soon as the message is processed
235 by the GFE backend. The user will be able to accept, deny, or defer the
236 request. If the user accepts or denies the request, the app will recieve
237 a \ref NVGSDK_NOTIFICATION_PERMISSIONS_CHANGED notification with the results.
238 If \ref NVGSDK_RequestPermissionsAsync is called again when the permission is
239 already granted or denied, the overlay will not be displayed a second time.
240 The user can reverse their decision in either case later on in GFE3 on
241 the games details page.
242 
243 ### Asynchronous Calls {#section_async}
244 Most of the calls to GfeSDK are asynchronous. This is due to the client/server
245 architecture described in \ref section_concepts. For each asynchronous call, a
246 callback and an opaque void* context are passed in as arguments. If the app
247 does not care or desire to know what happens to the call, is it fine to pass
248 in NULL. If the app does care, supply a callback of the proper type, and
249 optionally a pointer as a context to receive back during the callback.
250 
251 The callbacks are properly typed. For callbacks that return nothing but the
252 return value and context, a \ref NVGSDK_EmptyCallback is passed in. For
253 versions that do return data, a typed callback is passed in, such as
254 \ref NVGSDK_GetUILanguageCallback.
255 
256 The callback will be called on one of three threads, depending on the
257 situation. If NVGSDK_CreateInputParams::pollForCallbacks is set to false
258 during creation, the callback will always occur on a GfeSDK controller thread.
259 If the app desires callback to occur on their own thread, true is passed in
260 instead. In that case, the callback will occur on the thread that calls
261 \ref NVGSDK_Poll. The exception is that during \ref NVGSDK_Destroy, GfeSDK
262 pushes out all remaining callbacks. If the app is awaiting any callbacks
263 during this time, they will be called on the same thread that called
264 NVGSDK_Destroy. Usually, this will be the same thread that calls NVGSDK_Poll,
265 so it shouldn't cause any surprises, but it's something to be aware of. See
266 \ref section_threading for more information
267 
268 **Note:** There is currently a limitation in the GfeSDK backend that depends
269 on game frames being rendered during certain API calls. Therefore, the game
270 cannot block the render loop while awaiting an asynchronous callback. Doing
271 so will result in a deadlock.
272 
273 ### Notifications ### {#section_notifications}
274 
275 In addition to the async callbacks that most of the APIs accept as an argument,
276 the app can also register to recieve unsolicited notifications when certain
277 events occur. For example, the app might want to know when the user can
278 given / removed permission for recording video from the app, either through
279 the permissions dialog, or via GFE3. See \ref NVGSDK_CreateInputParams and
280 \ref NVGSDK_NotificationType
281 
282 This notification will get called on either the GfeSDK callback thread, or
283 the thread that calls \ref NVGSDK_Poll, depending on params passed in to
284 \ref NVGSDK_Create. See \ref section_threading for more information.
285 
286 ### Threading {#section_threading}
287 There are two different threading models that may be used. The model used
288 depends on the value passed in to \ref NVGSDK_CreateInputParams
289 
290 ##### GfeSDK Controller Callback Model
291 In this model, all callbacks will occur as soon as they are processed on the
292 internal GfeSDK callback thread.
293 
294 ##### Polling Model
295 The app can choose to use this model if it wants to take action during the
296 callback that depend on being on the game loop. Callbacks are queued up, and
297 executed when the app calls \ref NVGSDK_Poll. This means that callbacks will
298 be blocked indefinitely if that API is never called.
299 
300 The exception occurs during \ref NVGSDK_Destroy. Because the normal case is
301 to make NVGSDK_Destroy and NVGSDK_Poll calls from the same thread, GfeSDK
302 can't block and wait for another poll call. All remaining callbacks will be
303 executed during \ref NVGSDK_Destroy. See \ref section_async for more info.
304 
305 ### In Game Overlay {#section_igo}
306 ![In Game Overlay](/img/igo.png)
307 
308 The In-Game overlay can be used by the user to change Highlights settings, and
309 view Highlights that have been saved to the gallery. It's also used to display
310 the permissions dialog from \ref NVGSDK_RequestPermissionsAsync, and the
311 group summary from \ref NVGSDK_OpenGroupSummaryAsync. The user can open it
312 up by themselves using the default keybinding Alt+Z
313 
314 ## UX Guidance {#section_ux}
315 
316 ### Highlights Summary
317 
318 Many times a button is used to display the Highlights Summary. Suggested UX:
319 "View \%d highlights" or "\%d new highlights". Include an icon to the left of
320 the text. The icon to use is located in
321 GfeSDK/redist/assets/img/img_logo_experience_512.png
322 
323 ## Logging {#section_log}
324 By default, GfeSDK stores its own logs for problem triage in
325 \%LOCALAPPDATA\%\\NVIDIA Corporation\\GfeSDK. This behavior can be adjusted by
326 the following calls:
327 
328 * \ref NVGSDK_SetLogLevel
329 * \ref NVGSDK_AttachLogListener
330 * \ref NVGSDK_SetListenerLogLevel
+
1 # Development Guide # {#mainpage}
2 
3 # NVIDIA GeForce Experience SDK # {#section_main}
4 
5 * Version: 1.1.173.5d889305
6 * GeForce Experience minimum version: 3.8
7 * See [Changelog](\ref section_changelog)
8 
9 ## At a Glance {#section_glance}
10 
11 The GeForce SDK (GfeSDK) is a means for games to integrate with ShadowPlay Highlights allowing them to capture videos
12 and screenshots and present the resulting highlights back to users for viewing and sharing. GfeSDK will add other features
13 over time that benefit from games and applications working in concert with GFE functionality.
14 
15 ![Shadowplay Highlights](/img/gfesdk_highlights.png)
16 
17 ### Software Stack {#section_stack}
18 
19 ![Software Stack](/img/gfesdk_block.png)
20 
21 An application integrates with the GfeSDK via either the provided Unreal Engine 4 plug-in, C++ interface, or C interface. This integration, via the SDK, calls a compatible GFE 3.0 release.
22 
23 The developer (or associated publisher) distributes the application (including associated SDK libraries).
24 
25 NVIDIA distributes a GfeSDK package coupled with GfeSDK-compatible GFE releases. GFE maintains backwards SDK-compatibility; games integrated with older SDKs work with newer GFE releases.
26 
27 ### GfeSDK Package {#section_package}
28 
29 The distribution will look like the following
30 ```
31 .
32 +-- README.md
33 +-- LICENSE
34 +-- doc
35 | +-- index.html # Points to the deeper index.html
36 | +-- html
37 | | +-- index.html
38 | | ...
39 +-- include
40 | +-- gfesdk
41 | | +-- bindings
42 | | | +-- cpp # C++ bindings that sit on top of C API
43 | | +-- isdk.h
44 | | ...
45 +-- lib
46 | +-- win32
47 | | +-- GfeSDK.lib # x86 Import library for linking
48 | +-- win64
49 | | +-- GfeSDK.lib # x64 Import library for linking
50 +-- redist
51 | +-- assets
52 | | +-- img
53 | | | +-- xxxx.png # Images the game may redistribute
54 | +-- win32
55 | | +-- GfeSDK.dll # x86 DLL to be shipped with the game
56 | +-- win64
57 | | +-- GfeSDK.dll # x64 DLL to be shipped with the game
58 +-- samples
59 | +-- bin
60 | | +-- UnrealDemo # Binary game that demonstrates GfeSDK + Highlights
61 ```
62 
63 ### Compiling And Linking {#section_compiling}
64 
65 To compile, add the ./include (not the ./include/gfesdk) directory to the compiler's list of includes. The import libraries
66 are found in the ./lib folder and can be used to link the symbols into the game's executable. The proper GfeSDK.dll file
67 will need to be distributed with the game in a place that the game can find it.
68 
69 The C++ bindings are currently distributed in header-only form to avoid ABI incompatibilities between different compiler
70 versions. The linking and include steps are the same.
71 
72 ## Using GfeSDK ## {#section_using}
73 
74 Creation and destruction of an SDK instance is a prerequisite to making calls
75 to the SDK. The means of creating and destroying an instance depend on which
76 integration mechanism the client employs:
77 
78 See [Core header documentation](\ref isdk.h)
79 
80 See [Highlights header documentation](\ref ihighlights.h)
81 
82 ### Creation and Release {#section_example_create}
83 
84 #### C++ Bindings
85 
86 \snippet GfeSDKDemo.cpp Creation CPP
87 
88 // After using GfeSDK
89 
90 \snippet GfeSDKDemo.cpp Release CPP
91 
92 #### C API
93 
94 \snippet GfeSDKDemo.cpp Creation
95 
96 // After using GfeSDK
97 
98 \snippet GfeSDKDemo.cpp Release
99 
100 ### Request Permissions {#section_example_permission}
101 
102 The Create call will inform the app if one or more scopes require user
103 permission. If so, make this call. It will display the overlay UI.
104 
105 #### C++ Bindings
106 
107 \snippet GfeSDKDemo.cpp Permissions CPP
108 
109 #### C API
110 
111 \snippet GfeSDKDemo.cpp Permissions
112 
113 ### Configure Highlights {#section_example_highlightsconfigure}
114 
115 This only needs to happen once ever. It is persistent. It could even happen
116 during game installation.
117 
118 #### C++ Bindings
119 
120 \snippet GfeSDKDemo.cpp ConfigureHighlights CPP
121 
122 #### C API
123 
124 \snippet GfeSDKDemo.cpp ConfigureHighlights
125 
126 ### Groups and Saving Highlights {#section_Example_highlights}
127 
128 #### C++ Bindings
129 
130 \snippet GfeSDKDemo.cpp OpenGroup CPP
131 \snippet GfeSDKDemo.cpp SaveVideo CPP
132 \snippet GfeSDKDemo.cpp CloseGroup CPP
133 
134 #### C API
135 
136 \snippet GfeSDKDemo.cpp OpenGroup
137 \snippet GfeSDKDemo.cpp SaveVideo
138 \snippet GfeSDKDemo.cpp CloseGroup
139 
140 ### Open Highlight Summary {#section_example_summary}
141 
142 #### C++ Bindings
143 
144 \snippet GfeSDKDemo.cpp OpenSummary CPP
145 
146 #### C API
147 
148 \snippet GfeSDKDemo.cpp OpenSummary
149 
150 ## Concepts {#section_concepts}
151 
152 The GfeSDK is composed of two parts, the client/app, and the backend/server.
153 This distribution contains GfeSDK.dll which represents the client/app part.
154 The end-user downloads GFE onto their machine. The GFE package includes the
155 backend pieces necessary to support the calls coming from the client. See
156 \ref section_version for more information regarding this communication.
157 
158 Calls made will be serialized. Therefore, if the app makes two consecutive
159 calls to NVGSDK_Highlights_OpenGroup and then either
160 NVGSDK_Highlights_SetVideoHighlight or NVGSDK_Highlights_SetScreenshotHighlight,
161 before receiving the callback from open group, the set highlight call will
162 function normally. If open group succeeded, then the set highlights calls will
163 succeed as well. If it failed, the set highlights calls will fail, as there
164 will be no valid group to assign them to.
165 
166 ### Strings {#section_strings}
167 All strings are to be provided in single-byte width, UTF-8 encoded.
168 
169 ### Versioning {#section_version}
170 Because there are two different parts, and the client / user's machine may
171 be mismatched at times, the game should be aware of the versioning system.
172 It's GfeSDK's goal to make this as seamless as possible, but there could still
173 be compatibility issues to be aware of.
174 
175 The GfeSDK version contains 4 parts, MAJOR.MINOR.BUILD.HASH. The BUILD and HASH
176 components are descriptive and don't have any effect on functionality. The
177 MAJOR component identifies overall compatibility. If the client and server
178 mismatch on the major version number, no communication is possible. **There
179 are no current plans to update from 1, breaking communication**. The major
180 version number gives a way to show incompatibility if the fundamental
181 architecture of GFE ever changes. The minor version number indicates feature
182 compatibility. When a new feature gets added / modified on the SDK, the minor
183 version number will be bumped. This means that for older games / newer GFE
184 installations, the game is simply missing out on newer features. This will
185 generally not be a problem. For a game with a newer version of the GfeSDK,
186 and a user with an older installation of GFE, some features may not function,
187 and the user should be encouraged to update GFE.
188 
189 With that in mind, here are the possible return values from \ref NVGSDK_Create,
190 with regards to versioning:
191 * **NVGSDK_SUCCESS** - Perfect version match
192 * **NVGSDK_SUCCESS_OLD_GFE** - Minor version mismatch. User has an older
193 version of GFE installed. Newer features distributed by the game will not
194 function properly until the user upgrades.
195 * **NVGSDK_SUCCESS_OLD_SDK** - Minor version mismatch.
196 Game is distributing an older version of GfeSDK.
197 Game could be missing out on latest features, but no compatibily issue.
198 * **NVGSDK_ERR_GFE_VERSION** - Major version mismatch. User has a GFE
199 installation that predates the GfeSDK. User must upgrade to get functionality.
200 * **NVGSDK_ERR_SDK_VERSION** - Major version mismatch. GFE has changed
201 fundamentally. **There are no plans to do this. This is to cover all bases**
202 
203 ### Permissions {#section_permissions}
204 Certain actions require permission from the user. For example, recording video
205 for Highlights requires the user to agree to the recording. To achieve this,
206 the app must know what features it wishes to enable. It will pass these
207 "scopes" into the NVGSDK_Create call via NVGSDK_CreateInputParams. Consider
208 the typical Highlights case as an example. The app will pass in a list of
209 the scopes NVGSDK_SCOPE_HIGHLIGHTS, NVGSDK_SCOPE_HIGHLIGHTS_VIDEO, and
210 NVGSDK_SCOPE_SCREENSHOT. The first of these is required in order for any
211 of the NVGSDK_Highlights_* calls to succeed and send a message to the server.
212 It will allocate the resources required in the DLL and on the server in order
213 to achieve this. The second of these permissions is required in order to
214 capture video of the gameplay, and the final is to capture a screenshot.
215 
216 The first time the user runs the game, and the game calls NVGSDK_Create(...),
217 and passes in these three permissions, the game might receive back that
218 NVGSDK_SCOPE_HIGHLIGHTS has been granted permission implicitly, but that
219 NVGSDK_SCOPE_HIGHLIGHTS_VIDEO and NVGSDK_SCOPE_HIGHLIGHTS_SCREENSHOT
220 currently have "must ask" permission. In other words, the game must ask
221 GFE for permission to record video before it will succeed in doing so. To
222 achieve this, the game will call NVGSDK_RequestPermissionsAsync with two
223 scopes in the list, NVGSDK_SCOPE_HIGHLIGHTS_VIDEO and
224 NVGSDK_SCOPE_HIGHLIGHTS_SCREENSHOT. It's not necessary to request permission
225 for a scope that has implicitly been granted permission already.
226 
227 The call to NVGSDK_RequestPermissions is required because it will trigger
228 GFE to put up an \ref section_igo. The game might not want this to occur
229 during NVGSDK_Create time. Once called, the user will see the overlay
230 pop up, asking them for permission.
231 
232 ![Highlights Permission](/img/permission.png)
233 
234 The async callback will be triggered as soon as the message is processed
235 by the GFE backend. The user will be able to accept, deny, or defer the
236 request. If the user accepts or denies the request, the app will recieve
237 a \ref NVGSDK_NOTIFICATION_PERMISSIONS_CHANGED notification with the results.
238 If \ref NVGSDK_RequestPermissionsAsync is called again when the permission is
239 already granted or denied, the overlay will not be displayed a second time.
240 The user can reverse their decision in either case later on in GFE3 on
241 the games details page.
242 
243 ### Asynchronous Calls {#section_async}
244 Most of the calls to GfeSDK are asynchronous. This is due to the client/server
245 architecture described in \ref section_concepts. For each asynchronous call, a
246 callback and an opaque void* context are passed in as arguments. If the app
247 does not care or desire to know what happens to the call, is it fine to pass
248 in NULL. If the app does care, supply a callback of the proper type, and
249 optionally a pointer as a context to receive back during the callback.
250 
251 The callbacks are properly typed. For callbacks that return nothing but the
252 return value and context, a \ref NVGSDK_EmptyCallback is passed in. For
253 versions that do return data, a typed callback is passed in, such as
254 \ref NVGSDK_GetUILanguageCallback.
255 
256 The callback will be called on one of three threads, depending on the
257 situation. If NVGSDK_CreateInputParams::pollForCallbacks is set to false
258 during creation, the callback will always occur on a GfeSDK controller thread.
259 If the app desires callback to occur on their own thread, true is passed in
260 instead. In that case, the callback will occur on the thread that calls
261 \ref NVGSDK_Poll. The exception is that during \ref NVGSDK_Destroy, GfeSDK
262 pushes out all remaining callbacks. If the app is awaiting any callbacks
263 during this time, they will be called on the same thread that called
264 NVGSDK_Destroy. Usually, this will be the same thread that calls NVGSDK_Poll,
265 so it shouldn't cause any surprises, but it's something to be aware of. See
266 \ref section_threading for more information
267 
268 **Note:** There is currently a limitation in the GfeSDK backend that depends
269 on game frames being rendered during certain API calls. Therefore, the game
270 cannot block the render loop while awaiting an asynchronous callback. Doing
271 so will result in a deadlock.
272 
273 ### Notifications ### {#section_notifications}
274 
275 In addition to the async callbacks that most of the APIs accept as an argument,
276 the app can also register to recieve unsolicited notifications when certain
277 events occur. For example, the app might want to know when the user can
278 given / removed permission for recording video from the app, either through
279 the permissions dialog, or via GFE3. See \ref NVGSDK_CreateInputParams and
280 \ref NVGSDK_NotificationType
281 
282 This notification will get called on either the GfeSDK callback thread, or
283 the thread that calls \ref NVGSDK_Poll, depending on params passed in to
284 \ref NVGSDK_Create. See \ref section_threading for more information.
285 
286 ### Threading {#section_threading}
287 There are two different threading models that may be used. The model used
288 depends on the value passed in to \ref NVGSDK_CreateInputParams
289 
290 ##### GfeSDK Controller Callback Model
291 In this model, all callbacks will occur as soon as they are processed on the
292 internal GfeSDK callback thread.
293 
294 ##### Polling Model
295 The app can choose to use this model if it wants to take action during the
296 callback that depend on being on the game loop. Callbacks are queued up, and
297 executed when the app calls \ref NVGSDK_Poll. This means that callbacks will
298 be blocked indefinitely if that API is never called.
299 
300 The exception occurs during \ref NVGSDK_Destroy. Because the normal case is
301 to make NVGSDK_Destroy and NVGSDK_Poll calls from the same thread, GfeSDK
302 can't block and wait for another poll call. All remaining callbacks will be
303 executed during \ref NVGSDK_Destroy. See \ref section_async for more info.
304 
305 ### In Game Overlay {#section_igo}
306 ![In Game Overlay](/img/igo.png)
307 
308 The In-Game overlay can be used by the user to change Highlights settings, and
309 view Highlights that have been saved to the gallery. It's also used to display
310 the permissions dialog from \ref NVGSDK_RequestPermissionsAsync, and the
311 group summary from \ref NVGSDK_OpenGroupSummaryAsync. The user can open it
312 up by themselves using the default keybinding Alt+Z
313 
314 ## UX Guidance {#section_ux}
315 
316 ### Highlights Summary
317 
318 Many times a button is used to display the Highlights Summary. Suggested UX:
319 "View \%d highlights" or "\%d new highlights". Include an icon to the left of
320 the text. The icon to use is located in
321 GfeSDK/redist/assets/img/img_logo_experience_512.png
322 
323 ## Logging {#section_log}
324 By default, GfeSDK stores its own logs for problem triage in
325 \%LOCALAPPDATA\%\\NVIDIA Corporation\\GfeSDK. This behavior can be adjusted by
326 the following calls:
327 
328 * \ref NVGSDK_SetLogLevel
329 * \ref NVGSDK_AttachLogListener
330 * \ref NVGSDK_SetListenerLogLevel
diff --git a/doc/html/config_8h_source.html b/doc/html/config_8h_source.html index 971fe45..365fad0 100644 --- a/doc/html/config_8h_source.html +++ b/doc/html/config_8h_source.html @@ -6,7 +6,7 @@ -NVIDIAGeForceExperienceSDK: C:/u/workspace/dev/sdkwinauto/_build/sys-msvc141-uwp_x64_RelWithDebInfo/sdk/include/gfesdk/config.h Source File +NVIDIAGeForceExperienceSDK: C:/u/workspace/dev/sdkwinauto/_build/p4-msvc120_x86_RelWithDebInfo/sdk/include/gfesdk/config.h Source File @@ -85,13 +85,13 @@ $(document).ready(function(){initNavTree('config_8h_source.html','');});
config.h
-
1 /* Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
2  *
3  * NVIDIA CORPORATION and its licensors retain all intellectual property
4  * and proprietary rights in and to this software, related documentation
5  * and any modifications thereto. Any use, reproduction, disclosure or
6  * distribution of this software and related documentation without an express
7  * license agreement from NVIDIA CORPORATION is strictly prohibited.
8  */
9 
10 // Warning: This file is generated. Do not edit
11 
12 #ifndef _NVGSDK_CONFIG_H_
13 #define _NVGSDK_CONFIG_H_
14 
15 #include "gfe3_product_version.h"
16 
17 #define NVGSDK_PROJECT_NAME "GfeSDK"
18 
19 #define NVGSDK_VERSION_MAJOR 1
20 #define NVGSDK_VERSION_MINOR 0
21 #define NVGSDK_BUILD_NUMBER 168
22 #define NVGSDK_BUILD_HASH 8a267a87
23 #define NVGSDK_BUILD_HASH_STR "8a267a87"
24 
25 #endif // _NVGSDK_CONFIG_H_
+
1 /* Copyright (c) 2016, NVIDIA CORPORATION. All rights reserved.
2  *
3  * NVIDIA CORPORATION and its licensors retain all intellectual property
4  * and proprietary rights in and to this software, related documentation
5  * and any modifications thereto. Any use, reproduction, disclosure or
6  * distribution of this software and related documentation without an express
7  * license agreement from NVIDIA CORPORATION is strictly prohibited.
8  */
9 
10 // Warning: This file is generated. Do not edit
11 
12 #ifndef _NVGSDK_CONFIG_H_
13 #define _NVGSDK_CONFIG_H_
14 
15 #include "gfe3_product_version.h"
16 
17 #define NVGSDK_PROJECT_NAME "GfeSDK"
18 
19 #define NVGSDK_VERSION_MAJOR 1
20 #define NVGSDK_VERSION_MINOR 1
21 #define NVGSDK_BUILD_NUMBER 173
22 #define NVGSDK_BUILD_HASH 5d889305
23 #define NVGSDK_BUILD_HASH_STR "5d889305"
24 
25 #endif // _NVGSDK_CONFIG_H_