source/mupen64plus-core/doc/emuwiki-api-doc/Mupen64Plus_v2.0_Core_Video_Extension.txt

   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