Screenshots

Functions for adding screenshots to the user's screenshot library. See Steam Screenshots for more information.

Only available in the main GodotSteam branches

Functions

addScreenshotToLibrary

addScreenshotToLibrary( string filename, string thumbnail_filename, int width, int height )

Parameter	Type	Notes
filename	string	The absolute file path to the JPG, PNG, or TGA screenshot.
thumbnail_filename	string	The absolute file path to an optional thumbnail image. This must be 200px wide, as described by SCREENSHOT_THUMB_WIDTH and the same aspect ratio. Pass NULL if there is no thumbnail, one will be created automatically.
width	int	The width of the screenshot.
height	int	The height of the screenshot.

Adds a screenshot to the user's screenshot library from disk. If a thumbnail is provided, it must be 200 pixels wide and the same aspect ratio as the screenshot, otherwise a thumbnail will be generated if the user uploads the screenshot.

The screenshots must be in either JPEG or TGA format. The return value is a handle that is valid for the duration of the game process and can be used to apply tags; if that handle is 0 then the screenshot could not be saved. JPEG, TGA, and PNG formats are supported.

The given path must be an absolute path to the file.

Returns: uint32_t

Returns a screenshot handle that is valid for the duration of the game process and can be used to apply tags. May return SCREENSHOT_INVALID_HANDLE if the file could not be found.

Triggers

screenshot_ready callback

addVRScreenshotToLibrary

addVRScreenshotToLibrary( VRScreenshotType type, string filename, string vr_filename )

Parameter	Type	Notes
type	VRScreenshotType enum	The type of VR screenshot that this is.
filename	string	The absolute file path to a 2D JPG, PNG, or TGA version of the screenshot for the library view.
vr_filename	string	The absolute file path to the VR screenshot, this should be the same type of screenshot specified in type.

Adds a VR screenshot to the user's Steam screenshot library from disk in the supported type.

Returns: uint32_t

Returns a screenshot handle that is valid for the duration of the game process and can be used to apply tags. May return SCREENSHOT_INVALID_HANDLE if the file could not be found.

Triggers

screenshot_ready callback

hookScreenshots

hookScreenshots( bool hook )

Parameter	Type	Notes
hook	bool	Enable (true) or disable (false) hooking?

Toggles whether the overlay handles screenshots when the user presses the screenshot hotkey, or if the game handles them.

Hooking is disabled by default, and only ever enabled if you do so with this function.

If the hooking is enabled, then the screenshot_requested callback will be sent if the user presses the hotkey or when triggerScreenshot is called. Then the game is expected to call writeScreenshot or addScreenshotToLibrary in response.

You can check if hooking is enabled with isScreenshotsHooked.

Returns: void

isScreenshotsHooked

isScreenshotsHooked( )

Checks if the app is hooking screenshots.

Returns: bool

Returns true if the game is hooking screenshots and is expected to handle them; otherwise, false.

setLocation

setLocation( uint32_t screenshot, string location )

Parameter	Type	Notes
screenshot	uint32_t	The handle to the screenshot to tag.
location	string	The location in the game where this screenshot was taken. This can not be longer than UFS_TAG_VALUE_MAX.

Sets optional metadata about a screenshot's location. For example, the name of the map it was taken on.

You can get the handle to tag the screenshot once it has been successfully saved from the screenshot_ready callback or via the [writeScreenshot](#writescreenshot, addScreenshotToLibrary, addVRScreenshotToLibrary calls.

Returns: bool

Returns true if the location was successfully added to the screenshot; otherwise, false if screenshot was invalid, or location is invalid or too long.

tagPublishedFile

tagPublishedFile( uint32_t screenshot, uint64_t file_id )

Parameter	Type	Notes
screenshot	uint32_t	The handle to the screenshot to tag.
file_id	uint64_t	The workshop item ID that is in the screenshot.

Tags a published file as being visible in the screenshot.

You can tag up to the value declared by MAX_TAGGED_PUBLISHED_FILES in a single screenshot. Tagging more items than that will just be discarded.

This function has a built in delay before saving the tag which allows you to call it repeatedly for each item.

You can get the handle to tag the screenshot once it has been successfully saved from the screenshot_ready callback or via the [writeScreenshot](#writescreenshot, addScreenshotToLibrary, addVRScreenshotToLibrary calls.

Returns: bool

tagUser

tagUser( uint32_t screenshot, uint64_t steam_id )

Parameter	Type	Notes
screenshot	uint32_t	The handle to the screenshot to tag.
steam_id	uint64_t	The Steam ID of a user that is in the screenshot.

Tags a Steam user as being visible in the screenshot. You can tag up to the value declared by MAX_TAGGED_USERS in a single screenshot. Tagging more users than that will just be discarded. This function has a built in delay before saving the tag which allows you to call it repeatedly for each item.

You can get the handle to tag the screenshot once it has been successfully saved from the screenshot_ready callback or via the writeScreenshot, addScreenshotToLibrary, addVRScreenshotToLibrary calls.

Returns: bool

triggerScreenshot

triggerScreenshot( )

Either causes the Steam Overlay to take a screenshot, or tells your screenshot manager that a screenshot needs to be taken. Depending on the value of isScreenshotsHooked. Triggers a screenshot_requested callback if hooking has been enabled with hookScreenshots. Otherwise screenshot_ready will be called when the screenshot has been saved and added to the library.

Returns: void

Triggers

screenshot_ready callback
screenshot_requested callback

writeScreenshot

writeScreenshot( PoolByteArray rgb, int width, int height )

Parameter	Type	Notes
rgb	PoolByteArray	The buffer containing the raw RGB data from the screenshot.
width	int	The width of the screenshot in pixels.
height	int	The height of the screenshot in pixels.

Writes a screenshot to the user's screenshot library given the raw image data, which must be in RGB format. The return value is a handle that is valid for the duration of the game process and can be used to apply tags.

Returns: uint32_t

Returns a screenshot handle that is valid for the duration of the game process and can be used to apply tags. May return SCREENSHOT_INVALID_HANDLE if the file could not be found.

Triggers

screenshot_ready callback

Signals

These callbacks require you to setup one of the three callback methods to receive them.

screenshot_ready

A screenshot successfully written or otherwise added to the library and can now be tagged.

Returns

Key	Type	Notes
handle	uint32_t	The screenshot handle that has been written.
result	Result enum	The result of the operation. Possible values are: RESULT_OK if the screenshot was successfully added to the user's library. RESULT_FAIL if the screenshot could not be loaded or parsed. RESULT_OF_FAILURE if screenshot could not be saved to disk.

screenshot_requested

A screenshot has been requested by the user from the Steam screenshot hotkey. This will only be called if hookScreenshots has been enabled, in which case Steam will not take the screenshot itself.

Returns

Nothing.

Constants

Name	SDK Name	Value	Details
MAX_TAGGED_PUBLISHED_FILES	k_nScreenshotMaxTaggedPublishedFiles	32	The maximum number of workshop items that can be tagged in a screenshot using tagPublishedFile.
MAX_TAGGED_USERS	k_nScreenshotMaxTaggedUsers	32	The maximum number of users that can be tagged in a screenshot using tagUser.
SCREENSHOT_INVALID_HANDLE	INVALID_SCREENSHOT_HANDLE	0	An invalid screenshot handle, this is returned when writing or adding a screenshot has failed.
SCREENSHOT_THUMB_WIDTH	k_ScreenshotThumbWidth	200	Required width of a thumbnail provided to addScreenshotToLibrary. If you do not provide a thumbnail then one will be generated automatically.
UFS_TAG_TYPE_MAX	k_cubUFSTagTypeMax	255	Unused.
UFS_TAG_VALUE_MAX	k_cubUFSTagValueMax	255	The maximum length in bytes of a location metadata string set on a screenshot using setLocation.

Enums

VRScreenshotType

Enumerator	SDK Name	Value	Notes
VR_SCREENSHOT_TYPE_NONE	k_EVRScreenshotType_None	0	-
VR_SCREENSHOT_TYPE_MONO	k_EVRScreenshotType_Mono	1	-
VR_SCREENSHOT_TYPE_STEREO	k_EVRScreenshotType_Stereo	2	-
VR_SCREENSHOT_TYPE_MONO_CUBE_MAP	k_EVRScreenshotType_MonoCubemap	3	-
VR_SCREENSHOT_TYPE_MONO_PANORAMA	k_EVRScreenshotType_MonoPanorama	4	-
VR_SCREENSHOT_TYPE_STEREO_PANORAMA	k_EVRScreenshotType_StereoPanorama	5	-