Mupen64Plus v2.0 Core Video Extension

Mupen64Plus v2.0 API

Mupen64Plus v2.0 Video Extension API

Most libmupen64plus functions return an m64p_error return code, which is an enumerated type defined in m64p_types.h. Plugin code should check the return value of each call to a libmupen64plus function.

All of these functions should only be called from within the video plugin; they should not be called from the front-end.

Startup/Shutdown Functions

Prototype	m64p_error VidExt_Init(void)
Input Parameters	N/A
Requirements	This function should be called before any other Video Extension functions.
Usage	This function should be called from within the RomOpen() video plugin function call. The default SDL implementation of this function simply calls SDL_InitSubSystem(SDL_INIT_VIDEO). It does not open a rendering window or switch video modes.

Prototype	m64p_error VidExt_Quit(void)
Input Parameters	N/A
Usage	This function closes any open rendering window and shuts down the video system. The default SDL implementation of this function calls SDL_QuitSubSystem(SDL_INIT_VIDEO). This function should be called from within the RomClosed() video plugin function.

Screen Handling Functions

Prototype	m64p_error VidExt_ListFullscreenModes(m64p_2d_size *SizeArray, int *NumSizes)
Input Parameters	SizeArray Pointer to an array of m64p_2d_size objects, defined in m64p_types.h NumSizes Pointer to an integer which contains the size of SizeArray for input, and the number of size objects stored for output.
Requirements	The video extension must be initialized before calling this function.
Usage	This function is used to enumerate the available resolutions for fullscreen video modes. An array SizeArray is passed into the function, which is then filled (up to *NumSizes objects) with resolution sizes. The number of sizes actually written is stored in the integer which is pointed to by NumSizes.

Prototype	m64p_error VidExt_ListFullscreenRates(m64p_2d_size Size, int *NumRates, int *Rates)
Input Parameters	Size m64p_2d_size object, defined in m64p_types.h of the resolution you want to retrieve the fullscreen refresh rates from. NumRates Pointer to an integer which contains the size of Rates for input, and the number of size objects stored for output. Rates Pointer to an array of integers which will contain the refresh rates.
Requirements	The video extension must be initialized before calling this function.
Usage	This function is used to enumerate the available refresh rates for a given resolution. An m64p_2d_size object is passed into the function, which will contain the resolution of the refresh rates you want to retrieve, an array Rates is passed into the function, which is then filled (up to *NumRates objects) with resolution sizes. The number of sizes actually written is stored in the integer which is pointed to by NumSizes.

Prototype	m64p_error VidExt_SetVideoMode(int Width, int Height, int BitsPerPixel, m64p_video_mode ScreenMode, m64p_video_flags Flags)
Input Parameters	Width Horizontal resolution in pixels of desired video window Height Vertical resolution in pixels of desired video window BitsPerPixel Pixel color resolution of desired video window. This value must be 16, 24, or 32 ScreenMode Either M64VIDEO_WINDOWED or M64VIDEO_FULLSCREEN Flags Logical-OR combination of flags which describes the video plugin's capabilities.
Requirements	The video extension must be initialized before calling this function.
Usage	This function creates a rendering window or switches into a fullscreen video mode. Any desired OpenGL attributes should be set before calling this function.

Prototype	m64p_error VidExt_SetVideoModeWithRate(int Width, int Height, int RefreshRate, int BitsPerPixel, m64p_video_mode ScreenMode, m64p_video_flags Flags)
Input Parameters	Width Horizontal resolution in pixels of desired video window Height Vertical resolution in pixels of desired video window RefreshRate Fullscreen refresh rate BitsPerPixel Pixel color resolution of desired video window. This value must be 16, 24, or 32 ScreenMode Either M64VIDEO_WINDOWED or M64VIDEO_FULLSCREEN Flags Logical-OR combination of flags which describes the video plugin's capabilities.
Requirements	The video extension must be initialized before calling this function.
Usage	This function creates a rendering window or switches into a fullscreen video mode. Any desired OpenGL attributes should be set before calling this function.

Prototype	m64p_error VidExt_SetCaption(const char *Title)
Input Parameters	Title Pointer to a NULL-terminated string containing the desired title text of the emulator rendering window
Requirements	The video extension must be initialized before calling this function.
Usage	This function sets the caption text of the emulator rendering window.

Prototype	m64p_error VidExt_ToggleFullScreen(void)
Input Parameters	N/A
Requirements	The video extension must be initialized before calling this function. The rendering window should already be created.
Usage	This function toggles between fullscreen and windowed rendering modes.

Prototype	m64p_error VidExt_ResizeWindow(int Width, int Height)
Input Parameters	Width Horizontal resolution of resized window in pixels Height Vertical resolution of resized window in pixels
Requirements	The video extension must be initialized before calling this function. The rendering window should already be created.
Usage	This function is called when the video plugin has resized its OpenGL output viewport in response to a ResizeVideoOutput() call, and requests that the window manager update the OpenGL rendering window size to match. If a front-end application does not support resizable windows and never sets the M64CORE_VIDEO_SIZE core variable with the M64CMD_CORE_STATE_SET command, then this function should not be called.

Window Resizing

The window resizing functionality is particularly complicated, so here is a high-level description of the events which make it happen:

Without video extension:

1. In VidExt_SetVideoMode(), check if M64VIDEOFLAG_SUPPORT_RESIZING is set
   • if True, create SDL window with RESIZABLE attribute
2. Core receives SDL_RESIZE messages in SDL event loop
3. If present, Core calls ResizeVideoOutput function in video plugin
4. Video Plugin calls ResizeWindow function in Video Extension
   • Core calls SDL_SetVideoMode()
5. Core emits M64CORE_VIDEO_SIZE state changed callback

With video extension:

1. in Front-end SetVideoMode() callback
   • if M64VIDEOFLAG_SUPPORT_RESIZING is set, create resizable window frame
2. Front-end GUI gets window resize notification
3. Front-end calls CoreDoCommand w/ M64CMD_CORE_STATE_SET, w/ M64CORE_VIDEO_SIZE
4. If present, Core calls ResizeVideoOutput function in video plugin
5. Video Plugin calls ResizeWindow function in Video Extension
6. Core emits M64CORE_VIDEO_SIZE state changed callback

In the Core Video Extension function ResizeWindow, the SDL function SetVideoMode() is called. This function will destroy the current OpenGL context and create a new one. For this reason, any video plugin which supports resizable windows must completely reset its OpenGL state including uploading any textures, FBOs, programs, etc after calling the VidExt_ResizeWindow function.

OpenGL Functions

Prototype	void * VidExt_GL_GetProcAddress(const char* Proc)
Input Parameters	Proc Pointer to a NULL-terminated string containing the name of the desired OpenGL extension function.
Requirements	The video extension must be initialized before calling this function.
Usage	This function is used to get a pointer to an OpenGL extension function. This is only necessary on the Windows platform, because the OpenGL implementation shipped with Windows only supports OpenGL version 1.1.

Prototype	m64p_error VidExt_GL_SetAttribute(m64p_GLattr Attr, int Value)
Input Parameters	Attr Enumerated type (defined in m64p_types.h) specifying which OpenGL attribute to set Value Value to set for the attribute
Requirements	The video extension must be initialized before calling this function. The desired attributes should be set before calling VidExt_SetVideoMode
Usage	This function is used to set certain OpenGL attributes which must be specified before creating the rendering window with VidExt_SetVideoMode.

Prototype	m64p_error VidExt_GL_GetAttribute(m64p_GLattr Attr, int *pValue)
Input Parameters	Attr Enumerated type (defined in m64p_types.h) specifying OpenGL attribute of which to get value pValue Pointer to integer Value which will be set to attribute's value
Requirements	The video extension must be initialized before calling this function.
Usage	This function may be used to check that OpenGL attributes where successfully set to the rendering window after the VidExt_SetVideoMode function call.

Prototype	m64p_error VidExt_GL_SwapBuffers(void)
Input Parameters	N/A
Requirements	The video extension must be initialized before calling this function. The rendering window should already be created.
Usage	This function is used to swap the front/back buffers after rendering an output video frame.

Prototype	uint32_t VidExt_GL_GetDefaultFramebuffer(void)
Input Parameters	N/A
Requirements	The video extension must be initialized before calling this function. The rendering window should already be created.
Usage	On some platforms (for instance, iOS) the default framebuffer object depends on the surface being rendered to, and might be different from 0. This function should be called to retrieve the name of the default FBO. Calling this function may have performance implications and it should not be called every time the default FBO is bound.