Difference between revisions of "Mupen64Plus v2.0 Core Video Extension"

From Mupen64Plus Wiki
Jump to: navigation, search
(Created page with "Mupen64Plus v2.0 API = Mupen64Plus v2.0 Video Extension API = Most libmupen64plus functions return an <tt>m64p_error</tt> return code, whi...")
(No difference)

Revision as of 21:48, 21 July 2015

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


Retrieved from "https://mupen64plus.org/wiki/index.php?title=Mupen64Plus_v2.0_Core_Video_Extension&oldid=11"