Unaffiliated

Home Documentation & Help
Steamworks Documentation
ISteamScreenshots Interface
Functions for adding screenshots to the user's screenshot library.

See Steam Screenshots for more information.

Member Functions

Member functions for ISteamScreenshots are called through the global accessor function SteamScreenshots().

AddScreenshotToLibrary

ScreenshotHandle AddScreenshotToLibrary( const char *pchFilename, const char *pchThumbnailFilename, int nWidth, int nHeight );
NameTypeDescription
pchFilenameconst char *The absolute file path to the JPG, PNG, or TGA screenshot.
pchThumbnailFilenameconst char *The absolute file path to an optional thumbnail image. This must be 200px wide, as described by k_ScreenshotThumbWidth and the same aspect ratio. Pass NULL if there is no thumbnail, one will be created automatically.
nWidthintThe width of the screenshot.
nHeightintThe height of the screenshot.

Adds a screenshot to the user's Steam screenshot library from disk.

Returns: ScreenshotHandle
Triggers a ScreenshotReady_t callback.
The handle to this screenshot that is valid for the duration of the game process and can be used to apply tags.
Returns INVALID_SCREENSHOT_HANDLE if the file could not be saved.

This call is asynchronous, a ScreenshotReady_t callback will be sent when the screenshot has finished writing to disk.

AddVRScreenshotToLibrary

ScreenshotHandle AddVRScreenshotToLibrary( EVRScreenshotType eType, const char *pchFilename, const char *pchVRFilename );
NameTypeDescription
eTypeEVRScreenshotTypeThe type of VR screenshot that this is.
pchFilenameconst char *The absolute file path to a 2D JPG, PNG, or TGA version of the screenshot for the library view.
pchVRFilenameconst char *The absolute file path to the VR screenshot, this should be the same type of screenshot specified in eType.

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

Returns: ScreenshotHandle
Triggers a ScreenshotReady_t callback.
The handle to this screenshot that is valid for the duration of the game process and can be used to apply tags.
Returns INVALID_SCREENSHOT_HANDLE if the file could not be saved.

This call is asynchronous, a ScreenshotReady_t callback will be sent when the screenshot has finished writing to disk.

HookScreenshots

void HookScreenshots( bool bHook );
NameTypeDescription
bHookboolEnable (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 ScreenshotRequested_t callback will be sent if the user presses the hotkey or when TriggerScreenshot is called, and then the game is expected to call WriteScreenshot or AddScreenshotToLibrary in response.

You can check if hooking is enabled with IsScreenshotsHooked.

IsScreenshotsHooked

bool IsScreenshotsHooked();
Checks if the app is hooking screenshots, or if the Steam Overlay is handling them.

This can be toggled with HookScreenshots.

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

SetLocation

bool SetLocation( ScreenshotHandle hScreenshot, const char *pchLocation );
NameTypeDescription
hScreenshotScreenshotHandleThe handle to the screenshot to tag.
pchLocationconst char *The location in the game where this screenshot was taken. This can not be longer than k_cubUFSTagValueMax.

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 ScreenshotReady_t callback or via the WriteScreenshot, AddScreenshotToLibrary, AddVRScreenshotToLibrary calls.

Returns: bool
true if the location was successfully added to the screenshot.
false if hScreenshot was invalid, or pchLocation is invalid or too long.

TagPublishedFile

bool TagPublishedFile( ScreenshotHandle hScreenshot, PublishedFileId_t unPublishedFileID );
NameTypeDescription
hScreenshotScreenshotHandleThe handle to the screenshot to tag.
unPublishedFileIDPublishedFileId_tThe 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 k_nScreenshotMaxTaggedPublishedFiles 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 ScreenshotReady_t callback or via the WriteScreenshot, AddScreenshotToLibrary, AddVRScreenshotToLibrary calls.

Returns: bool

TagUser

bool TagUser( ScreenshotHandle hScreenshot, CSteamID steamID );
NameTypeDescription
hScreenshotScreenshotHandleThe handle to the screenshot to tag.
steamIDCSteamIDThe 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 k_nScreenshotMaxTaggedUsers 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 ScreenshotReady_t callback or via the WriteScreenshot, AddScreenshotToLibrary, AddVRScreenshotToLibrary calls.

Returns: bool

TriggerScreenshot

void 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.

Returns: void
Triggers a ScreenshotRequested_t callback.
Triggers a ScreenshotReady_t callback.
Only causes ScreenshotRequested_t if hooking has been enabled with HookScreenshots. Otherwise ScreenshotReady_t will be called when the screenshot has been saved and added to the library.

WriteScreenshot

ScreenshotHandle WriteScreenshot( void *pubRGB, uint32 cubRGB, int nWidth, int nHeight );
NameTypeDescription
pubRGBvoid *The buffer containing the raw RGB data from the screenshot.
cubRGBuint32The size of pubRGB in bytes.
nWidthintThe width of the screenshot in pixels.
nHeightintThe height of the screenshot in pixels.

Writes a screenshot to the user's Steam screenshot library given the raw image data, which must be in RGB format.

Returns: ScreenshotHandle
Triggers a ScreenshotReady_t callback.
The handle to this screenshot that is valid for the duration of the game process and can be used to apply tags.
Returns INVALID_SCREENSHOT_HANDLE if the file could not be saved.

This call is asynchronous, the ScreenshotReady_t callback will be sent when the screenshot has finished writing to disk.

Callbacks

These are callbacks which can be fired by calling SteamAPI_RunCallbacks. Many of these will be fired directly in response to the member functions of ISteamScreenshots.

ScreenshotReady_t

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

NameTypeDescription
m_hLocalScreenshotHandleThe screenshot handle that has been written.
m_eResultEResultThe result of the operation. Possible values:

Associated Functions: WriteScreenshot, AddScreenshotToLibrary, TriggerScreenshot, AddVRScreenshotToLibrary

ScreenshotRequested_t

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.

This callback has no fields.

Associated Functions: TriggerScreenshot

Enums

These are enums which are defined for use with ISteamScreenshots.

EVRScreenshotType

Describes the type of VR screenshots.

NameValueDescription
k_EVRScreenshotType_None0
k_EVRScreenshotType_Mono1
k_EVRScreenshotType_Stereo2
k_EVRScreenshotType_MonoCubemap3
k_EVRScreenshotType_MonoPanorama4
k_EVRScreenshotType_StereoPanorama5

Typedefs

These are typedefs which are defined for use with ISteamScreenshots.

NameBase typeDescription
ScreenshotHandleuint32Handle to a screenshot. This will be valid for the lifetime of your process, but no longer.

Constants

These are constants which are defined for use with ISteamScreenshots.

NameTypeValueDescription
INVALID_SCREENSHOT_HANDLEint0An invalid screenshot handle, this is returned when writing or adding a screenshot has failed.
k_cubUFSTagTypeMaxint255Unused.
k_cubUFSTagValueMaxint255The maximum length in bytes of a location metadata string set on a screenshot using SetLocation.
k_nScreenshotMaxTaggedPublishedFilesuint3232The maximum number of workshop items that can be tagged in a screenshot using TagPublishedFile.
k_nScreenshotMaxTaggedUsersuint3232The maximum number of users that can be tagged in a screenshot using TagUser.
k_ScreenshotThumbWidthint200Required with of a thumbnail provided to AddScreenshotToLibrary. If you do not provide a thumbnail then one will be generated automatically.
STEAMSCREENSHOTS_INTERFACE_VERSIONconst char *"STEAMSCREENSHOTS_INTERFACE_VERSION003"