| 1 | [[Mupen64Plus v2.0 Core API v1.0|Mupen64Plus v2.0 API]] |
| 2 | |
| 3 | = Mupen64Plus v2.0 Video Extension API = |
| 4 | |
| 5 | Most libmupen64plus functions return an <tt>m64p_error</tt> return code, which is an enumerated type defined in [[Mupen64Plus v2.0 headers#m64p_types.h|m64p_types.h]]. Plugin code should check the return value of each call to a libmupen64plus function. |
| 6 | |
| 7 | All of these functions should only be called from within the video plugin; they should not be called from the front-end. |
| 8 | |
| 9 | == Startup/Shutdown Functions == |
| 10 | {| border="1" |
| 11 | |Prototype |
| 12 | |'''<tt>m64p_error VidExt_Init(void)</tt>''' |
| 13 | |- |
| 14 | |Input Parameters |
| 15 | |N/A |
| 16 | |- |
| 17 | |Requirements |
| 18 | |This function should be called before any other Video Extension functions. |
| 19 | |- |
| 20 | |Usage |
| 21 | |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. |
| 22 | |} |
| 23 | <br /> |
| 24 | {| border="1" |
| 25 | |Prototype |
| 26 | |'''<tt>m64p_error VidExt_Quit(void)</tt>''' |
| 27 | |- |
| 28 | |Input Parameters |
| 29 | |N/A |
| 30 | |- |
| 31 | |Usage |
| 32 | |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. |
| 33 | |} |
| 34 | <br /> |
| 35 | |
| 36 | == Screen Handling Functions == |
| 37 | {| border="1" |
| 38 | |Prototype |
| 39 | |'''<tt>m64p_error VidExt_ListFullscreenModes(m64p_2d_size *SizeArray, int *NumSizes)</tt>''' |
| 40 | |- |
| 41 | |Input Parameters |
| 42 | |'''<tt>SizeArray</tt>''' Pointer to an array of <tt>m64p_2d_size</tt> objects, defined in [[Mupen64Plus v2.0 headers#m64p_types.h|m64p_types.h]]<br /> |
| 43 | '''<tt>NumSizes</tt>''' Pointer to an integer which contains the size of '''<tt>SizeArray</tt>''' for input, and the number of size objects stored for output. |
| 44 | |- |
| 45 | |Requirements |
| 46 | |The video extension must be initialized before calling this function. |
| 47 | |- |
| 48 | |Usage |
| 49 | |This function is used to enumerate the available resolutions for fullscreen video modes. An array '''<tt>SizeArray</tt>''' is passed into the function, which is then filled (up to <tt>*'''NumSizes'''</tt> objects) with resolution sizes. The number of sizes actually written is stored in the integer which is pointed to by '''<tt>NumSizes</tt>'''. |
| 50 | |} |
| 51 | <br /> |
| 52 | {| border="1" |
| 53 | |Prototype |
| 54 | |'''<tt>m64p_error VidExt_SetVideoMode(int Width, int Height, int BitsPerPixel, m64p_video_mode ScreenMode, m64p_video_flags Flags)</tt>''' |
| 55 | |- |
| 56 | |Input Parameters |
| 57 | |'''<tt>Width</tt>''' Horizontal resolution in pixels of desired video window<br /> |
| 58 | '''<tt>Height</tt>''' Vertical resolution in pixels of desired video window<br /> |
| 59 | '''<tt>BitsPerPixel</tt>''' Pixel color resolution of desired video window. This value must be 16, 24, or 32<br /> |
| 60 | '''<tt>ScreenMode</tt>''' Either <tt>M64VIDEO_WINDOWED</tt> or <tt>M64VIDEO_FULLSCREEN</tt><br /> |
| 61 | '''<tt>Flags</tt>''' Logical-OR combination of flags which describes the video plugin's capabilities. |
| 62 | |- |
| 63 | |Requirements |
| 64 | |The video extension must be initialized before calling this function. |
| 65 | |- |
| 66 | |Usage |
| 67 | |This function creates a rendering window or switches into a fullscreen video mode. Any desired OpenGL attributes should be set before calling this function. |
| 68 | |} |
| 69 | <br /> |
| 70 | {| border="1" |
| 71 | |Prototype |
| 72 | |'''<tt>m64p_error VidExt_SetCaption(const char *Title)</tt>''' |
| 73 | |- |
| 74 | |Input Parameters |
| 75 | |'''<tt>Title</tt>''' Pointer to a NULL-terminated string containing the desired title text of the emulator rendering window |
| 76 | |- |
| 77 | |Requirements |
| 78 | |The video extension must be initialized before calling this function. |
| 79 | |- |
| 80 | |Usage |
| 81 | |This function sets the caption text of the emulator rendering window. |
| 82 | |} |
| 83 | <br /> |
| 84 | {| border="1" |
| 85 | |Prototype |
| 86 | |'''<tt>m64p_error VidExt_ToggleFullScreen(void)</tt>''' |
| 87 | |- |
| 88 | |Input Parameters |
| 89 | |N/A |
| 90 | |- |
| 91 | |Requirements |
| 92 | |The video extension must be initialized before calling this function. The rendering window should already be created. |
| 93 | |- |
| 94 | |Usage |
| 95 | |This function toggles between fullscreen and windowed rendering modes. |
| 96 | |} |
| 97 | <br /> |
| 98 | {| border="1" |
| 99 | |Prototype |
| 100 | |'''<tt>m64p_error VidExt_ResizeWindow(int Width, int Height)</tt>''' |
| 101 | |- |
| 102 | |Input Parameters |
| 103 | |'''<tt>Width</tt>''' Horizontal resolution of resized window in pixels<br /> |
| 104 | '''<tt>Height</tt>''' Vertical resolution of resized window in pixels |
| 105 | |- |
| 106 | |Requirements |
| 107 | |The video extension must be initialized before calling this function. The rendering window should already be created. |
| 108 | |- |
| 109 | |Usage |
| 110 | |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. |
| 111 | |} |
| 112 | <br /> |
| 113 | |
| 114 | ===Window Resizing=== |
| 115 | The window resizing functionality is particularly complicated, so here is a high-level description of the events which make it happen: |
| 116 | |
| 117 | ====Without video extension:==== |
| 118 | # In VidExt_SetVideoMode(), check if M64VIDEOFLAG_SUPPORT_RESIZING is set |
| 119 | #* if True, create SDL window with RESIZABLE attribute |
| 120 | # Core receives SDL_RESIZE messages in SDL event loop |
| 121 | # If present, Core calls ResizeVideoOutput function in video plugin |
| 122 | # Video Plugin calls ResizeWindow function in Video Extension |
| 123 | #* Core calls SDL_SetVideoMode() |
| 124 | # Core emits M64CORE_VIDEO_SIZE state changed callback |
| 125 | |
| 126 | ====With video extension:==== |
| 127 | # in Front-end SetVideoMode() callback |
| 128 | #* if M64VIDEOFLAG_SUPPORT_RESIZING is set, create resizable window frame |
| 129 | # Front-end GUI gets window resize notification |
| 130 | # Front-end calls CoreDoCommand w/ M64CMD_CORE_STATE_SET, w/ M64CORE_VIDEO_SIZE |
| 131 | # If present, Core calls ResizeVideoOutput function in video plugin |
| 132 | # Video Plugin calls ResizeWindow function in Video Extension |
| 133 | # Core emits M64CORE_VIDEO_SIZE state changed callback |
| 134 | |
| 135 | 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. |
| 136 | |
| 137 | == OpenGL Functions == |
| 138 | {| border="1" |
| 139 | |Prototype |
| 140 | |'''<tt>void * VidExt_GL_GetProcAddress(const char* Proc)</tt>''' |
| 141 | |- |
| 142 | |Input Parameters |
| 143 | |'''<tt>Proc</tt>''' Pointer to a NULL-terminated string containing the name of the desired OpenGL extension function. |
| 144 | |- |
| 145 | |Requirements |
| 146 | |The video extension must be initialized before calling this function. |
| 147 | |- |
| 148 | |Usage |
| 149 | |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. |
| 150 | |} |
| 151 | <br /> |
| 152 | {| border="1" |
| 153 | |Prototype |
| 154 | |'''<tt>m64p_error VidExt_GL_SetAttribute(m64p_GLattr Attr, int Value)</tt>''' |
| 155 | |- |
| 156 | |Input Parameters |
| 157 | |'''<tt>Attr</tt>''' Enumerated type (defined in [[Mupen64Plus v2.0 headers#m64p_types.h|m64p_types.h]]) specifying which OpenGL attribute to set<br /> |
| 158 | '''<tt>Value</tt>''' Value to set for the attribute |
| 159 | |- |
| 160 | |Requirements |
| 161 | |The video extension must be initialized before calling this function. The desired attributes should be set before calling '''<tt>VidExt_SetVideoMode</tt>''' |
| 162 | |- |
| 163 | |Usage |
| 164 | |This function is used to set certain OpenGL attributes which must be specified before creating the rendering window with '''<tt>VidExt_SetVideoMode</tt>'''. |
| 165 | |} |
| 166 | <br /> |
| 167 | {| border="1" |
| 168 | |Prototype |
| 169 | |'''<tt>m64p_error VidExt_GL_GetAttribute(m64p_GLattr Attr, int *pValue)</tt>''' |
| 170 | |- |
| 171 | |Input Parameters |
| 172 | |'''<tt>Attr</tt>''' Enumerated type (defined in [[Mupen64Plus v2.0 headers#m64p_types.h|m64p_types.h]]) specifying OpenGL attribute of which to get value<br /> |
| 173 | '''<tt>pValue</tt>''' Pointer to integer Value which will be set to attribute's value |
| 174 | |- |
| 175 | |Requirements |
| 176 | |The video extension must be initialized before calling this function. |
| 177 | |- |
| 178 | |Usage |
| 179 | |This function may be used to check that OpenGL attributes where successfully set to the rendering window after the '''<tt>VidExt_SetVideoMode</tt>''' function call. |
| 180 | |} |
| 181 | <br /> |
| 182 | {| border="1" |
| 183 | |Prototype |
| 184 | |'''<tt>m64p_error VidExt_GL_SwapBuffers(void)</tt>''' |
| 185 | |- |
| 186 | |Input Parameters |
| 187 | |N/A |
| 188 | |- |
| 189 | |Requirements |
| 190 | |The video extension must be initialized before calling this function. The rendering window should already be created. |
| 191 | |- |
| 192 | |Usage |
| 193 | |This function is used to swap the front/back buffers after rendering an output video frame. |
| 194 | |} |
| 195 | <br /> |
| 196 | |