Duckstation/dep/rainterface/RA_Interface.h
2022-08-22 19:33:00 +10:00

387 lines
14 KiB
C

#ifndef RA_INTERFACE_H
#define RA_INTERFACE_H
#include <wtypes.h> /* HWND */
#ifdef __cplusplus
extern "C" {
#endif
/******************************
* Initialization *
******************************/
/**
* Loads and initializes the DLL.
*
* Must be called before using any of the other functions. Will automatically download the DLL
* if not found, or prompt the user to upgrade if a newer version is available
*
* @param hMainHWND the handle of the main window
* @param nEmulatorID the unique idenfier of the emulator
* @param sClientVersion the current version of the emulator (will be validated against the minimum version for the specified emulator ID)
*/
extern void RA_Init(HWND hMainHWND, int nEmulatorID, const char* sClientVersion);
/**
* Loads and initializes the DLL.
*
* Must be called before using any of the other functions. Will automatically download the DLL
* if not found, or prompt the user to upgrade if a newer version is available
*
* @param hMainHWND the handle of the main window
* @param sClientName the name of the client, displayed in the title bar and included in the User-Agent for API calls
* @param sClientVersion the current version of the client
*/
extern void RA_InitClient(HWND hMainHWND, const char* sClientName, const char* sClientVersion);
/**
* Defines callbacks that the DLL can use to interact with the client.
*
* @param fpUnusedIsActive [no longer used] returns non-zero if a game is running
* @param fpCauseUnpause unpauses the emulator
* @param fpCausePause pauses the emulator
* @param fpRebuildMenu notifies the client that the popup menu has changed (@see RA_CreatePopupMenu)
* @param fpEstimateTitle gets a short description for the game being loaded (parameter is a 256-byte buffer to fill)
* @param fpResetEmulator resets the emulator
* @param fpLoadROM [currently unused] tells the emulator to load a specific game
*/
extern void RA_InstallSharedFunctions(int (*fpUnusedIsActive)(void),
void (*fpCauseUnpause)(void), void (*fpCausePause)(void), void (*fpRebuildMenu)(void),
void (*fpEstimateTitle)(char*), void (*fpResetEmulator)(void), void (*fpLoadROM)(const char*));
/**
* Tells the DLL to use UpdateWindow instead of InvalidateRect when the UI needs to be repainted. This is primarily
* necessary when integrating with an emulator using the SDL library as it keeps the message queue flooded so the
* InvalidateRect messages never get turned into WM_PAINT messages.
*
* @param bEnable non-zero if InvalidateRect calls should be replaced with UpdateWindow
*/
extern void RA_SetForceRepaint(int bEnable);
/**
* Creates a popup menu that can be appended to the main menu of the emulator.
*
* @return handle to the menu. if not attached to the program menu, caller must destroy it themselves.
*/
extern HMENU RA_CreatePopupMenu(void);
/* Resource values for menu items - needed by MFC ON_COMMAND_RANGE macros or WM_COMMAND WndProc handlers
* they're not all currently used, allowing additional items without forcing recompilation of the emulators
*/
#define IDM_RA_MENUSTART 1700
#define IDM_RA_MENUEND 1739
typedef struct RA_MenuItem
{
LPCWSTR sLabel;
LPARAM nID;
int bChecked;
} RA_MenuItem;
/**
* Gets items for building a popup menu.
*
* @param pItems Pre-allocated array to populate [should contain space for at least 32 items]
* @return Number of items populated in the items array
*/
extern int RA_GetPopupMenuItems(RA_MenuItem *pItems);
/**
* Called when a menu item in the popup menu is selected.
*
* @param nID the ID of the menu item (will be between IDM_RA_MENUSTART and IDM_RA_MENUEND)
*/
extern void RA_InvokeDialog(LPARAM nID);
/**
* Provides additional information to include in the User-Agent string for API calls.
*
* This is primarily used to identify dependencies or configurations (such as libretro core versions)
*
* @param sDetail the additional information to include
*/
extern void RA_SetUserAgentDetail(const char* sDetail);
/**
* Attempts to log in to the retroachievements.org site.
*
* Prompts the user for their login credentials and performs the login. If they've previously logged in and have
* chosen to store their credentials, the login occurs without prompting.
*
* @param bBlocking if zero, control is returned to the calling process while the login request is processed by the server.
*/
extern void RA_AttemptLogin(int bBlocking);
/**
* Specifies the console associated to the emulator.
*
* May be called just before loading a game if the emulator supports multiple consoles.
*
* @param nConsoleID the unique identifier of the console associated to the game being loaded.
*/
extern void RA_SetConsoleID(unsigned int nConsoleID);
/**
* Resets memory references created by previous calls to RA_InstallMemoryBank.
*/
extern void RA_ClearMemoryBanks(void);
typedef unsigned char (RA_ReadMemoryFunc)(unsigned int nAddress);
typedef void (RA_WriteMemoryFunc)(unsigned int nAddress, unsigned char nValue);
/**
* Exposes a block of memory to the DLL.
*
* The blocks of memory expected by the DLL are unique per console ID. To identify the correct map for a console,
* view the consoleinfo.c file in the rcheevos repository.
*
* @param nBankID the index of the bank to update. will replace any existing bank at that index.
* @param pReader a function to read from the bank. parameter is the offset within the bank to read from.
* @param pWriter a function to write to the bank. parameters are the offset within the bank to write to and an 8-bit value to write.
* @param nBankSize the size of the bank.
*/
extern void RA_InstallMemoryBank(int nBankID, RA_ReadMemoryFunc pReader, RA_WriteMemoryFunc pWriter, int nBankSize);
typedef unsigned int (RA_ReadMemoryBlockFunc)(unsigned int nAddress, unsigned char* pBuffer, unsigned int nBytes);
extern void RA_InstallMemoryBankBlockReader(int nBankID, RA_ReadMemoryBlockFunc pReader);
/**
* Deinitializes and unloads the DLL.
*/
extern void RA_Shutdown(void);
/******************************
* Overlay *
******************************/
/**
* Determines if the overlay is fully visible.
*
* Precursor check before calling RA_NavigateOverlay
*
* @return non-zero if the overlay is fully visible, zero if it is not.
*/
extern int RA_IsOverlayFullyVisible(void);
/**
* Called to show or hide the overlay.
*
* @param bIsPaused true to show the overlay, false to hide it.
*/
extern void RA_SetPaused(bool bIsPaused);
struct ControllerInput
{
int m_bUpPressed;
int m_bDownPressed;
int m_bLeftPressed;
int m_bRightPressed;
int m_bConfirmPressed; /* Usually C or A */
int m_bCancelPressed; /* Usually B */
int m_bQuitPressed; /* Usually Start */
};
/**
* Passes controller input to the overlay.
*
* Does nothing if the overlay is not fully visible.
*
* @param pInput pointer to a ControllerInput structure indicating which inputs are active.
*/
extern void RA_NavigateOverlay(struct ControllerInput* pInput);
/**
* [deprecated] Updates the overlay for a single frame.
*
* This function just calls RA_NavigateOverlay. Updating and rendering is now handled internally to the DLL.
*/
extern void RA_UpdateRenderOverlay(HDC, struct ControllerInput* pInput, float, RECT*, bool, bool);
/**
* Updates the handle to the main window.
*
* The main window handle is used to anchor the overlay. If the client recreates the handle as the result of switching
* from windowed mode to full screen, or for any other reason, it should call this to reattach the overlay.
*
* @param hMainHWND the new handle of the main window
*/
extern void RA_UpdateHWnd(HWND hMainHWND);
/******************************
* Game Management *
******************************/
/**
* Identifies the game associated to a block of memory.
*
* The block of memory is the fully buffered game file. If more complicated identification is required, the caller
* needs to link against rcheevos/rhash directly to generate the hash, and call RA_IdentifyHash with the result.
* Can be called when switching discs to ensure the additional discs are still associated to the loaded game.
*
* @param pROMData the contents of the game file
* @param nROMSize the size of the game file
* @return the unique identifier of the game, 0 if no association available.
*/
extern unsigned int RA_IdentifyRom(BYTE* pROMData, unsigned int nROMSize);
/**
* Identifies the game associated to a pre-generated hash.
*
* Used when the hash algorithm is something other than full file.
* Can be called when switching discs to ensure the additional discs are still associated to the loaded game.
*
* @param sHash the hash generated by rcheevos/rhash
* @return the unique identifier of the game, 0 if no association available.
*/
extern unsigned int RA_IdentifyHash(const char* sHash);
/**
* Fetches all retroachievements related data for the specified game.
*
* @param nGameId the unique identifier of the game to activate
*/
extern void RA_ActivateGame(unsigned int nGameId);
/**
* Identifies and activates the game associated to a block of memory.
*
* Functions as a call to RA_IdentifyRom followed by a call to RA_ActivateGame.
*
* @param pROMData the contents of the game file
* @param nROMSize the size of the game file
*/
extern void RA_OnLoadNewRom(BYTE* pROMData, unsigned int nROMSize);
/**
* Called before unloading the game to allow the user to save any changes they might have.
*
* @param bIsQuitting non-zero to change the messaging to indicate the emulator is closing.
* @return zero to abort the unload. non-zero to continue.
*/
extern int RA_ConfirmLoadNewRom(int bIsQuitting);
/******************************
* Runtime Functionality *
******************************/
/**
* Does all achievement-related processing for a single frame.
*/
extern void RA_DoAchievementsFrame(void);
/**
* Temporarily disables forced updating of tool windows.
*
* Primarily used while fast-forwarding.
*/
extern void RA_SuspendRepaint(void);
/**
* Resumes forced updating of tool windows.
*/
extern void RA_ResumeRepaint(void);
/**
* [deprecated] Used to be used to ensure the asynchronous server calls are processed on the UI thread.
* That's all managed within the DLL now. Calling this function does nothing.
*/
extern void RA_HandleHTTPResults(void);
/**
* Adds flavor text to the application title bar.
*
* Application title bar is managed by the DLL. Value will be "ClientName - Version - Flavor Text - Username"
*
* @param sCustomMessage the flavor text to include in the title bar.
*/
extern void RA_UpdateAppTitle(const char* sCustomMessage);
/**
* Get the user name of the currently logged in user.
*
* @return user name of the currently logged in user, empty if no user is logged in.
*/
const char* RA_UserName(void);
/**
* Determines if the user is currently playing with hardcore enabled.
*
* The client should disable any features that would give the player an unfair advantage if this returns non-zero.
* Things like loading states, using cheats, modifying RAM, disabling rendering layers, viewing decoded tilemaps, etc.
*
* @return non-zero if hardcore mode is currently active.
*/
extern int RA_HardcoreModeIsActive(void);
/**
* Warns the user they're about to do something that will disable hardcore mode.
*
* @param sActivity what the user is about to do (i.e. "load a state").
* @return non-zero if the user disabled hardcore and the activity is allowed.
* zero if the user declined to disable hardcore and the activity should be aborted.
*/
extern int RA_WarnDisableHardcore(const char* sActivity);
/**
* Disables hardcore mode without prompting or notifying the user.
*
* Should only be called if the client does its own prompting/notification.
* Typically used when an activity cannot be aborted.
*/
extern void RA_DisableHardcore(void);
/**
* Notifies the DLL that the game has been reset.
*
* Disables active leaderboards and resets hit counts on all active achievements.
*/
extern void RA_OnReset(void);
/**
* Notifies the DLL that a save state has been created.
*
* Creates a .rap file next to the state file that contains achievement-related information for the save state.
*
* @param sFilename full path to the save state file.
*/
extern void RA_OnSaveState(const char* sFilename);
/**
* Notifies the DLL that a save state has been loaded.
*
* Loads the .rap file next to the state file that contains achievement-related information for the save state being loaded.
*
* @param sFilename full path to the save state file.
*/
extern void RA_OnLoadState(const char* sFilename);
/**
* Captures the current state of the achievement runtime for inclusion in a save state.
*
* @param pBuffer buffer to write achievement state information to
* @param nBufferSize the size of the buffer
* @return the number of bytes needed to capture the achievement state. if less than nBufferSize, pBuffer
* will not be populated. the function should be called again with a larger buffer.
*/
extern int RA_CaptureState(char* pBuffer, int nBufferSize);
/**
* Restores the state of the achievement runtime from a previously captured state.
*
* @param pBuffer buffer containing previously serialized achievement state information
*/
extern void RA_RestoreState(const char* pBuffer);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif // !RA_INTERFACE_H