diff --git a/src/SDL2.cs b/src/SDL2.cs index cc4fecd..3bf7ca8 100644 --- a/src/SDL2.cs +++ b/src/SDL2.cs @@ -36,11 +36,16 @@ using System.Runtime.InteropServices; namespace SDL2 { + /// + /// Entry point for all SDL-related (non-extension) types and methods + /// public static class SDL { #region SDL2# Variables - /* Used by DllImport to load the native library. */ + /// + /// Used by DllImport to load the native library. + /// private const string nativeLibName = "SDL2.dll"; #endregion @@ -68,6 +73,12 @@ namespace SDL2 * the phrase "THIS IS AN RWops FUNCTION!" */ + /// + /// Use this function to create a new SDL_RWops structure for reading from and/or writing to a named file. + /// + /// a UTF-8 string representing the filename to open + /// an ASCII string representing the mode to be used for opening the file; see Remarks for details + /// Returns a pointer to the SDL_RWops structure that is created, or NULL on failure; call SDL_GetError() for more information. [DllImport(nativeLibName, EntryPoint = "SDL_RWFromFile", CallingConvention = CallingConvention.Cdecl)] internal static extern IntPtr INTERNAL_SDL_RWFromFile( [In()] [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler))] @@ -80,6 +91,9 @@ namespace SDL2 #region SDL_main.h + /// + /// Use this function to circumvent failure of SDL_Init() when not using SDL_main() as an entry point. + /// [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_SetMainReady(); @@ -100,18 +114,67 @@ namespace SDL2 SDL_INIT_GAMECONTROLLER ); + /// + /// Use this function to initialize the SDL library. + /// This must be called before using any other SDL function. + /// + /// subsystem initialization flags; see Remarks for details + /// Returns 0 on success or a negative error code on failure. + /// Call for more information. + /// The Event Handling, File I/O, and Threading subsystems are initialized by default. + /// You must specifically initialize other subsystems if you use them in your application. + /// Unless the SDL_INIT_NOPARACHUTE flag is set, it will install cleanup signal handlers + /// for some commonly ignored fatal signals (like SIGSEGV). [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_Init(uint flags); + /// + /// Use this function to initialize specific SDL subsystems. + /// + /// any of the flags used by SDL_Init(); see Remarks for details + /// Returns 0 on success or a negative error code on failure. + /// Call for more information. + /// After SDL has been initialized with you may initialize + /// uninitialized subsystems with . + /// If you want to initialize subsystems separately you would call + /// followed by with the desired subsystem flag. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_InitSubSystem(uint flags); + /// + /// Use this function to clean up all initialized subsystems. + /// You should call it upon all exit conditions. + /// + /// You should call this function even if you have already shutdown each initialized + /// subsystem with . + /// If you start a subsystem using a call to that subsystem's init function (for example + /// ) instead of or , + /// then you must use that subsystem's quit function () to shut it down + /// before calling . + /// You can use this function with atexit() to ensure that it is run when your application is + /// shutdown, but it is not wise to do this from a library or other dynamically loaded code. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_Quit(); + /// + /// Use this function to shut down specific SDL subsystems. + /// + /// any of the flags used by ; see Remarks for details + /// If you start a subsystem using a call to that subsystem's init function (for example + /// ) instead of or , + /// then you must use that subsystem's quit function () to shut it down + /// before calling . + /// You can use this function with atexit() to en + /// You still need to call even if you close all open subsystems with SDL_QuitSubSystem(). [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_QuitSubSystem(uint flags); + /// + /// Use this function to return a mask of the specified subsystems which have previously been initialized. + /// + /// any of the flags used by ; see Remarks for details + /// If flags is 0 it returns a mask of all initialized subsystems, otherwise it returns the + /// initialization status of the specified subsystems. The return value does not include SDL_INIT_NOPARACHUTE. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern uint SDL_WasInit(uint flags); @@ -157,9 +220,19 @@ namespace SDL2 SDL_HINT_OVERRIDE } + /// + /// Use this function to clear all hints. + /// + /// This function is automatically called during . [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_ClearHints(); + /// + /// Use this function to get the value of a hint. + /// + /// the hint to query; see the list of hints on + /// CategoryHints for details + /// Returns the string value of a hint or NULL if the hint isn't set. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] [return : MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler), MarshalCookie = LPUtf8StrMarshaler.LeaveAllocated)] public static extern string SDL_GetHint( @@ -167,6 +240,16 @@ namespace SDL2 string name ); + /// + /// Use this function to set a hint with normal priority. + /// + /// the hint to query; see the list of hints on + /// CategoryHints for details + /// the value of the hint variable + /// Returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. + /// Hints will not be set if there is an existing override hint or environment + /// variable that takes precedence. You can use to set the hint with + /// override priority instead. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern SDL_bool SDL_SetHint( [In()] [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler))] @@ -175,6 +258,17 @@ namespace SDL2 string value ); + /// + /// Use this function to set a hint with a specific priority. + /// + /// the hint to query; see the list of hints on + /// CategoryHints for details + /// the value of the hint variable + /// the level for the hint + /// Returns SDL_TRUE if the hint was set, SDL_FALSE otherwise. + /// The priority controls the behavior when setting a hint that already has a value. + /// Hints will replace existing hints of their priority and lower. Environment variables are + /// considered to have override priority. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern SDL_bool SDL_SetHintWithPriority( [In()] [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler))] @@ -188,13 +282,32 @@ namespace SDL2 #region SDL_error.h + /// + /// Use this function to clear any previous error message. + /// [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_ClearError(); + /// + /// Use this function to retrieve a message about the last error that occurred. + /// + /// Returns a message with information about the specific error that occurred, + /// or an empty string if there hasn't been an error since the last call to . + /// Without calling , the message is only applicable when an SDL function + /// has signaled an error. You must check the return values of SDL function calls to determine + /// when to appropriately call . + /// This string is statically allocated and must not be freed by the application. + /// It is possible for multiple errors to occur before calling SDL_GetError(). Only the last error is returned. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] [return : MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler), MarshalCookie = LPUtf8StrMarshaler.LeaveAllocated)] public static extern string SDL_GetError(); + /// + /// Use this function to set the SDL error string. + /// + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// Calling this function will replace any previous error message that was set. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_SetError( [In()] [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler))] @@ -240,6 +353,9 @@ namespace SDL2 public const int SDL_LOG_CATEGORY_CUSTOM = 19; /* End nameless enum SDL_LOG_CATEGORY */ + /// + /// An enumeration of the predefined log priorities. + /// public enum SDL_LogPriority { SDL_LOG_PRIORITY_VERBOSE = 1, @@ -251,6 +367,15 @@ namespace SDL2 SDL_NUM_LOG_PRIORITIES } + /// + /// Used as a callback for and + /// + /// what was passed as userdata to + /// the category of the message; see Remarks for details + /// the priority of the message; see Remarks for details + /// the message being output + /// The category can be one of SDL_LOG_CATEGORY* + /// The priority can be one of SDL_LOG_PRIORITY* [UnmanagedFunctionPointer(CallingConvention.Cdecl)] public delegate void SDL_LogOutputFunction( IntPtr userdata, // void* @@ -259,6 +384,11 @@ namespace SDL2 IntPtr message // const char* ); + /// + /// Use this function to log a message with SDL_LOG_CATEGORY_APPLICATION and SDL_LOG_PRIORITY_INFO. + /// + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_Log( [In()] [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler))] @@ -266,6 +396,13 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with SDL_LOG_PRIORITY_VERBOSE. + /// + /// the category of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogVerbose( int category, @@ -274,6 +411,13 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with SDL_LOG_PRIORITY_DEBUG. + /// + /// the category of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogDebug( int category, @@ -282,6 +426,13 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with SDL_LOG_PRIORITY_INFO. + /// + /// the category of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogInfo( int category, @@ -290,6 +441,13 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with SDL_LOG_PRIORITY_WARN. + /// + /// the category of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogWarn( int category, @@ -298,6 +456,13 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with SDL_LOG_PRIORITY_ERROR. + /// + /// the category of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogError( int category, @@ -306,6 +471,13 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with SDL_LOG_PRIORITY_CRITICAL. + /// + /// the category of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogCritical( int category, @@ -314,6 +486,15 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with the specified category and priority. + /// + /// the category of the message; see Remarks for details + /// the priority of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any + /// The category can be one of SDL_LOG_CATEGORY* + /// The priority can be one of SDL_LOG_PRIORITY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogMessage( int category, @@ -323,6 +504,14 @@ namespace SDL2 __arglist ); + /// + /// Use this function to log a message with the specified category and priority. + /// This version of uses a stdarg variadic argument list. + /// + /// the category of the message; see Remarks for details + /// the priority of the message; see Remarks for details + /// a printf() style message format string + /// additional parameters matching % tokens in the fmt string, if any [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogMessageV( int category, @@ -332,26 +521,53 @@ namespace SDL2 __arglist ); + /// + /// Use this function to get the priority of a particular log category. + /// + /// the category to query; see Remarks for details + /// Returns the for the requested category; see Remarks for details. + /// The category can be one of SDL_LOG_CATEGORY* + /// The returned priority will be one of SDL_LOG_PRIORITY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern SDL_LogPriority SDL_LogGetPriority( int category ); + /// + /// Use this function to set the priority of a particular log category. + /// + /// the category to query; see Remarks for details + /// the of the message; see Remarks for details + /// The category can be one of SDL_LOG_CATEGORY* + /// The priority can be one of SDL_LOG_PRIORITY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogSetPriority( int category, SDL_LogPriority priority ); + /// + /// Use this function to set the priority of all log categories. + /// + /// the of the message; see Remarks for details + /// The priority can be one of SDL_LOG_PRIORITY* [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogSetAllPriority( SDL_LogPriority priority ); + /// + /// Use this function to reset all priorities to default. + /// + /// This is called in . [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogResetPriorities(); - /* userdata refers to a void* */ + /// + /// Use this function to get the current log output function. + /// + /// a pointer filled in with the current log callback; see Remarks for details + /// a pointer filled in with the pointer that is passed to callback (refers to void*) [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogGetOutputFunction( out SDL_LogOutputFunction callback, @@ -359,6 +575,11 @@ namespace SDL2 ); /* userdata refers to a void* */ + /// + /// Use this function to replace the default log output function with one of your own. + /// + /// the function to call instead of the default; see Remarks for details + /// a pointer that is passed to callback (refers to void*) [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_LogSetOutputFunction( SDL_LogOutputFunction callback, @@ -427,29 +648,41 @@ namespace SDL2 private struct INTERNAL_SDL_MessageBoxData { public SDL_MessageBoxFlags flags; - public IntPtr window; /* Parent window, can be NULL */ - public IntPtr title; /* UTF-8 title */ - public IntPtr message; /* UTF-8 message text */ + public IntPtr window; /* Parent window, can be NULL */ + public IntPtr title; /* UTF-8 title */ + public IntPtr message; /* UTF-8 message text */ public int numbuttons; public IntPtr buttons; - public IntPtr colorScheme; /* Can be NULL to use system settings */ + public IntPtr colorScheme; /* Can be NULL to use system settings */ } [StructLayout(LayoutKind.Sequential)] public struct SDL_MessageBoxData { public SDL_MessageBoxFlags flags; - public IntPtr window; /* Parent window, can be NULL */ - public string title; /* UTF-8 title */ - public string message; /* UTF-8 message text */ + public IntPtr window; /* Parent window, can be NULL */ + public string title; /* UTF-8 title */ + public string message; /* UTF-8 message text */ public int numbuttons; public SDL_MessageBoxButtonData[] buttons; - public SDL_MessageBoxColorScheme? colorScheme; /* Can be NULL to use system settings */ + public SDL_MessageBoxColorScheme? colorScheme; /* Can be NULL to use system settings */ } + /// + /// + /// + /// + /// + /// [DllImport(nativeLibName, EntryPoint = "SDL_ShowMessageBox", CallingConvention = CallingConvention.Cdecl)] private static extern int INTERNAL_SDL_ShowMessageBox([In()] ref INTERNAL_SDL_MessageBoxData messageboxdata, out int buttonid); + /// + /// + /// + /// + /// + /// public static unsafe int SDL_ShowMessageBox([In()] ref SDL_MessageBoxData messageboxdata, out int buttonid) { var utf8 = LPUtf8StrMarshaler.GetInstance(null); @@ -498,7 +731,14 @@ namespace SDL2 return result; } - /* window refers to an SDL_Window* */ + /// + /// Use this function to display a simple message box. + /// + /// An ; see Remarks for details; + /// UTF-8 title text + /// UTF-8 message text + /// the parent window, or NULL for no parent (refers to a + /// 0 on success or a negative error code on failure; call SDL_GetError() for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_ShowSimpleMessageBox( SDL_MessageBoxFlags flags, @@ -527,6 +767,14 @@ namespace SDL2 SDL_PATCHLEVEL ); + /// + /// A structure that contains information about the version of SDL in use. + /// + /// Represents the library's version as three levels: + /// major revision (increments with massive changes, additions, and enhancements) + /// minor revision (increments with backwards-compatible changes to the major revision), and + /// patchlevel (increments with fixes to the minor revision) + /// can be used to populate this structure with information [StructLayout(LayoutKind.Sequential)] public struct SDL_version { @@ -535,6 +783,10 @@ namespace SDL2 public byte patch; } + /// + /// Use this macro to determine the SDL version your program was compiled against. + /// + /// an structure to initialize public static void SDL_VERSION(out SDL_version x) { x.major = SDL_MAJOR_VERSION; @@ -542,23 +794,59 @@ namespace SDL2 x.patch = SDL_PATCHLEVEL; } + /// + /// Use this macro to convert separate version components into a single numeric value. + /// + /// major version; reported in thousands place + /// minor version; reported in hundreds place + /// update version (patchlevel); reported in tens and ones places + /// + /// This assumes that there will never be more than 100 patchlevels. + /// Example: SDL_VERSIONNUM(1,2,3) -> (1203) public static int SDL_VERSIONNUM(int X, int Y, int Z) { return (X * 1000) + (Y * 100) + Z; } + /// + /// Use this macro to determine whether the SDL version compiled against is at least as new as the specified version. + /// + /// major version + /// minor version + /// update version (patchlevel) + /// This macro will evaluate to true if compiled with SDL version at least X.Y.Z. public static bool SDL_VERSION_ATLEAST(int X, int Y, int Z) { return (SDL_COMPILEDVERSION >= SDL_VERSIONNUM(X, Y, Z)); } + /// + /// Use this function to get the version of SDL that is linked against your program. + /// + /// the structure that contains the version information + /// This function may be called safely at any time, even before SDL_Init(). [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] private static extern void SDL_GetVersion(out SDL_version ver); + /// + /// Use this function to get the code revision of SDL that is linked against your program. + /// + /// Returns an arbitrary string, uniquely identifying the exact revision + /// of the SDL library in use. + /// The revision is a string including sequential revision number that is + /// incremented with each commit, and a hash of the last code change. + /// Example: hg-5344:94189aa89b54 + /// This value is the revision of the code you are linked with and may be + /// different from the code you are compiling with, which is found in the constant SDL_REVISION. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] [return : MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler), MarshalCookie = LPUtf8StrMarshaler.LeaveAllocated)] public static extern string SDL_GetRevision(); + /// + /// Use this function to get the revision number of SDL that is linked against your program. + /// + /// Returns a number uniquely identifying the exact revision of the SDL library in use. + /// This is an incrementing number based on commits to hg.libsdl.org. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetRevisionNumber(); @@ -567,6 +855,9 @@ namespace SDL2 #region SDL_video.h /* Actually, this is from SDL_blendmode.h */ + /// + /// An enumeration of blend modes used in SDL_RenderCopy() and drawing operations. + /// [Flags] public enum SDL_BlendMode { @@ -576,6 +867,9 @@ namespace SDL2 SDL_BLENDMODE_MOD = 0x00000004 } + /// + /// An enumeration of OpenGL configuration attributes. + /// public enum SDL_GLattr { SDL_GL_RED_SIZE, @@ -603,6 +897,9 @@ namespace SDL2 SDL_GL_SHARE_WITH_CURRENT_CONTEXT } + /// + /// An enumeration of OpenGL profiles. + /// [Flags] public enum SDL_GLprofile { @@ -611,6 +908,9 @@ namespace SDL2 SDL_GL_CONTEXT_PROFILE_ES = 0x0004 } + /// + /// An enumeration of window events. + /// public enum SDL_WindowEventID : byte { SDL_WINDOWEVENT_NONE, @@ -630,6 +930,9 @@ namespace SDL2 SDL_WINDOWEVENT_CLOSE, } + /// + /// An enumeration of window states. + /// [Flags] public enum SDL_WindowFlags { @@ -674,6 +977,9 @@ namespace SDL2 return (X & 0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK; } + /// + /// A structure that describes a display mode. + /// [StructLayout(LayoutKind.Sequential)] public struct SDL_DisplayMode { @@ -684,7 +990,18 @@ namespace SDL2 public IntPtr driverdata; // void* } - /* IntPtr refers to an SDL_Window* */ + /// + /// Use this function to create a window with the specified position, dimensions, and flags. + /// + /// the title of the window, in UTF-8 encoding + /// the x position of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED + /// the y position of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED + /// the width of the window + /// the height of the window + /// 0, or one or more OR'd together; + /// see Remarks for details + /// Returns the window that was created or NULL on failure; call + /// for more information. (refers to an ) [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern IntPtr SDL_CreateWindow( [In()] [MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler))] @@ -696,7 +1013,15 @@ namespace SDL2 SDL_WindowFlags flags ); - /* window and renderer refer to an SDL_Window* and SDL_Renderer* */ + /// + /// Use this function to create a window and default renderer. + /// + /// The width of the window + /// The height of the window + /// The flags used to create the window (see ) + /// A pointer filled with the window, or NULL on error () + /// A pointer filled with the renderer, or NULL on error + /// Returns 0 on success, or -1 on error; call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_CreateWindowAndRenderer( int width, @@ -706,21 +1031,51 @@ namespace SDL2 out IntPtr renderer ); - /* IntPtr refers to an SDL_Window*. data is a void* pointer. */ + /// + /// Use this function to create an SDL window from an existing native window. + /// + /// a pointer to driver-dependent window creation data, typically your native window cast to a void* + /// Returns the window () that was created or NULL on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern IntPtr SDL_CreateWindowFrom(IntPtr data); - /* window refers to an SDL_Window* */ + /// + /// Use this function to destroy a window. + /// + /// the window to destroy () [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_DestroyWindow(IntPtr window); + /// + /// Use this function to prevent the screen from being blanked by a screen saver. + /// + /// If you disable the screensaver, it is automatically re-enabled when SDL quits. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_DisableScreenSaver(); + /// + /// Use this function to allow the screen to be blanked by a screen saver. + /// [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern void SDL_EnableScreenSaver(); /* IntPtr refers to an SDL_DisplayMode. Just use closest. */ + /// + /// Use this function to get the closest match to the requested display mode. + /// + /// the index of the display to query + /// an structure containing the desired display mode + /// an structure filled in with + /// the closest match of the available display modes + /// Returns the passed in value closest or NULL if no matching video mode was available; + /// (refers to a ) + /// call for more information. + /// The available display modes are scanned and closest is filled in with the closest mode + /// matching the requested mode and returned. The mode format and refresh rate default to the desktop + /// mode if they are set to 0. The modes are scanned with size being first priority, format being + /// second priority, and finally checking the refresh rate. If all the available modes are too small, + /// then NULL is returned. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern IntPtr SDL_GetClosestDisplayMode( int displayIndex, @@ -728,28 +1083,75 @@ namespace SDL2 out SDL_DisplayMode closest ); + /// + /// Use this function to get information about the current display mode. + /// + /// the index of the display to query + /// an structure filled in with the current display mode + /// Returns 0 on success or a negative error code on failure; + /// call for more information. + /// There's a difference between this function and when SDL + /// runs fullscreen and has changed the resolution. In that case this function will return the + /// current display mode, and not the previous native display mode. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetCurrentDisplayMode( int displayIndex, out SDL_DisplayMode mode ); + /// + /// Use this function to return the name of the currently initialized video driver. + /// + /// Returns the name of the current video driver or NULL if no driver has been initialized. + /// There's a difference between this function and when SDL + /// runs fullscreen and has changed the resolution. In that case this function will return the + /// previous native display mode, and not the current display mode. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] [return : MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler), MarshalCookie = LPUtf8StrMarshaler.LeaveAllocated)] public static extern string SDL_GetCurrentVideoDriver(); + /// + /// Use this function to get information about the desktop display mode. + /// + /// the index of the display to query + /// an structure filled in with the current display mode + /// Returns 0 on success or a negative error code on failure; + /// call for more information. + /// There's a difference between this function and when SDL + /// runs fullscreen and has changed the resolution. In that case this function will return the + /// previous native display mode, and not the current display mode. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetDesktopDisplayMode( int displayIndex, out SDL_DisplayMode mode ); + /// + /// Use this function to get the desktop area represented by a display, with the primary display located at 0,0. + /// + /// the index of the display to query + /// the structure filled in with the display bounds + /// Returns 0 on success or a negative error code on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetDisplayBounds( int displayIndex, out SDL_Rect rect ); + /// + /// Use this function to get information about a specific display mode. + /// + /// the index of the display to query + /// the index of the display mode to query + /// an structure filled in with the mode at modeIndex + /// Returns 0 on success or a negative error code on failure; + /// call for more information. + /// The display modes are sorted in this priority: + /// bits per pixel -> more colors to fewer colors + /// width -> largest to smallest + /// height -> largest to smallest + /// refresh rate -> highest to lowest [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetDisplayMode( int displayIndex, @@ -757,30 +1159,61 @@ namespace SDL2 out SDL_DisplayMode mode ); + /// + /// Use this function to return the number of available display modes. + /// + /// the index of the display to query + /// Returns a number >= 1 on success or a negative error code on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetNumDisplayModes( int displayIndex ); + /// + /// Use this function to return the number of available video displays. + /// + /// Returns a number >= 1 or a negative error code on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetNumVideoDisplays(); + /// + /// Use this function to get the number of video drivers compiled into SDL. + /// + /// Returns a number >= 1 on success or a negative error code on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetNumVideoDrivers(); + /// + /// Use this function to get the name of a built in video driver. + /// + /// the index of a video driver + /// Returns the name of the video driver with the given index. + /// The video drivers are presented in the order in which they are normally checked during initialization. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] [return : MarshalAs(UnmanagedType.CustomMarshaler, MarshalTypeRef = typeof(LPUtf8StrMarshaler), MarshalCookie = LPUtf8StrMarshaler.LeaveAllocated)] public static extern string SDL_GetVideoDriver( int index ); - /* window refers to an SDL_Window* */ + /// + /// Use this function to get the brightness (gamma correction) for a window. + /// + /// the window to query () + /// Returns the brightness for the window where 0.0 is completely dark and 1.0 is normal brightness. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern float SDL_GetWindowBrightness( IntPtr window ); - /* IntPtr refers to void* data. window refers to an SDL_Window*. */ + /// + /// Use this function to retrieve the data pointer associated with a window. + /// + /// the window to query () + /// the name of the pointer + /// Returns the value associated with name. (void*) [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern IntPtr SDL_GetWindowData( IntPtr window, @@ -788,24 +1221,45 @@ namespace SDL2 string name ); - /* window refers to an SDL_Window* */ + /// + /// Use this function to get the index of the display associated with a window. + /// + /// the window to query () + /// Returns the index of the display containing the center of the window + /// on success or a negative error code on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetWindowDisplayIndex( IntPtr window ); - /* window refers to an SDL_Window* */ + /// + /// Use this function to fill in information about the display mode to use when a window is visible at fullscreen. + /// + /// the window to query () + /// an structure filled in with the fullscreen display mode + /// Returns 0 on success or a negative error code on failure; + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern int SDL_GetWindowDisplayMode( IntPtr window, out SDL_DisplayMode mode ); - /* window refers to an SDL_Window* */ + /// + /// Use this function to get the window flags. + /// + /// the window to query () + /// Returns a mask of the associated with window; see Remarks for details. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern uint SDL_GetWindowFlags(IntPtr window); - /* IntPtr refers to an SDL_Window* */ + /// + /// Use this function to get a window from a stored ID. + /// + /// the ID of the window + /// Returns the window associated with id or NULL if it doesn't exist (); + /// call for more information. [DllImport(nativeLibName, CallingConvention = CallingConvention.Cdecl)] public static extern IntPtr SDL_GetWindowFromID(uint id);