Finalized X-Ram.

Source/OpenTK/OpenAL/History.txt

@@ -38,6 +38,9 @@ Alpha v0.95
 -full cleanup of AL class documentation
 -added *.Bind* helpers.
 
+Alpha v0.96
+- Cleaned up X-Ram, improved docu, hide some previously public things. No more Console.WriteLines
+
 
 Todo for beta:
 - Identify: AL_FILTER_FIRST_PARAMETER, AL_FILTER_LAST_PARAMETER

Source/OpenTK/OpenAL/XRamExtension.cs

@@ -8,14 +8,16 @@
 #endregion
 
 using System;
+using System.Diagnostics;
 using System.Runtime.InteropServices;
 
 namespace OpenTK.OpenAL
 {
 
+    /// <summary>The X-Ram Extension is provided on the top-end Sound Blaster X-Fi solutions (Sound Blaster X-Fi Fatal1ty, Sound Blaster X-Fi Elite Pro, or later). These products feature 64MB of X-Ram that can only be used for audio purposes, which can be controlled by this Extension.</summary>
     public class XRamExtension
     {
-        #region instance state
+        #region Instance state
 
         private bool _valid = false;
 
@@ -25,16 +27,16 @@ namespace OpenTK.OpenAL
             get { return _valid; }
         }
 
-        #endregion instance state
+        #endregion Instance state
 
         #region X-RAM Function pointer definitions
 
         [CLSCompliant(false)]
-        public unsafe delegate bool Delegate_SetBufferMode( int n,ref uint buffers,int value );
+        private delegate bool Delegate_SetBufferMode( int n,ref uint buffers,int value );
         //typedef ALboolean (__cdecl *EAXSetBufferMode)(ALsizei n, ALuint *buffers, ALint value);
 
         [CLSCompliant(false)]
-        public delegate int Delegate_GetBufferMode( uint buffer,out int value );
+        private delegate int Delegate_GetBufferMode( uint buffer,IntPtr value );
         //typedef ALenum    (__cdecl *EAXGetBufferMode)(ALuint buffer, ALint *value);
 
         //[CLSCompliant(false)]
@@ -65,7 +67,7 @@ namespace OpenTK.OpenAL
             AL_STORAGE_HARDWARE = AL.GetEnumValue("AL_STORAGE_HARDWARE");
             AL_STORAGE_ACCESSIBLE = AL.GetEnumValue("AL_STORAGE_ACCESSIBLE");
 
-            Console.WriteLine("RamSize: {0} RamFree: {1} StorageAuto: {2} StorageHW: {3} StorageAccess: {4}",AL_EAX_RAM_SIZE,AL_EAX_RAM_FREE,AL_STORAGE_AUTOMATIC,AL_STORAGE_HARDWARE,AL_STORAGE_ACCESSIBLE);
+            // Console.WriteLine("RamSize: {0} RamFree: {1} StorageAuto: {2} StorageHW: {3} StorageAccess: {4}",AL_EAX_RAM_SIZE,AL_EAX_RAM_FREE,AL_STORAGE_AUTOMATIC,AL_STORAGE_HARDWARE,AL_STORAGE_ACCESSIBLE);
 
             if ( AL_EAX_RAM_SIZE == 0 ||
                  AL_EAX_RAM_FREE == 0 ||
@@ -73,11 +75,11 @@ namespace OpenTK.OpenAL
                  AL_STORAGE_HARDWARE == 0 ||
                  AL_STORAGE_ACCESSIBLE == 0 )
             {
-                Console.WriteLine("Token values could not be retrieved.");
+                Trace.WriteLine("Token values could not be retrieved.");
                 return;
             }
 
-            Console.WriteLine("Free Ram: {0} / {1}",GetRamFree( ),GetRamSize( ));
+            // Console.WriteLine("Free Ram: {0} / {1}",GetRamFree( ),GetRamSize( ));
 
             try
             {
@@ -85,7 +87,7 @@ namespace OpenTK.OpenAL
                 Imported_SetBufferMode = (Delegate_SetBufferMode) Marshal.GetDelegateForFunctionPointer(AL.GetProcAddress("EAXSetBufferMode"),typeof(Delegate_SetBufferMode));
             } catch ( Exception e )
             {
-                Console.WriteLine("Attempt to marshal AL.GetProcAddress failed. " + e.ToString( ));
+                Trace.WriteLine("Attempt to marshal function pointers with AL.GetProcAddress failed. " + e.ToString( ));
                 return;
             }
 
@@ -96,59 +98,62 @@ namespace OpenTK.OpenAL
 
         #region Public Methods
 
-        /// <summary>Query total amount of X-RAM.</summary>
+        /// <summary>Query total amount of X-RAM in bytes.</summary>
         public int GetRamSize( )
         {
             return AL.Get((Enums.ALGetInteger) AL_EAX_RAM_SIZE);
         }
 
-        /// <summary>Query free X-RAM available.</summary>
+        /// <summary>Query free X-RAM available in bytes.</summary>
         public int GetRamFree( )
         {
             return AL.Get((Enums.ALGetInteger) AL_EAX_RAM_FREE);
         }
 
+        /// <summary>This enum is used to abstract the need of using AL.GetEnumValue() with the Extension. The values do NOT correspond to AL_STORAGE_* tokens!</summary>
         public enum XRamStorage : byte
         {
-            /// <summary>Put an Open AL Buffer into X-RAM if memory is available, otherwise use host RAM.  This is the default mode.
+            /// <summary>Put an Open AL Buffer into X-RAM if memory is available, otherwise use host RAM.  This is the default mode.</summary>
-            /// alGenBuffers(1, &uiBuffer);
+            Automatic = 0,
-            /// eaxSetBufferMode(1, &uiBuffer, alGetEnumValue("AL_STORAGE_AUTOMATIC"));
+            /// <summary>Force an Open AL Buffer into X-RAM (good for non-streaming buffers)</summary>
-            /// alBufferData(...);</summary>
-            Automatic,
-            /// <summary>Force an Open AL Buffer into X-RAM (good for non-streaming buffers)
-            // alGenBuffers(1, &uiBuffer);
-            // eaxSetBufferMode(1, &uiBuffer, alGetEnumValue("AL_STORAGE_HARDWARE"));
-            // alBufferData(...);</summary>
             Hardware = 1,
-            /// <summary>Force an Open AL Buffer into 'accessible' (currently host) RAM (good for streaming buffers)
+            /// <summary>Force an Open AL Buffer into 'accessible' (currently host) RAM (good for streaming buffers)</summary>
-            /// alGenBuffers(1, &uiBuffer);
+            Accessible = 2,
-            /// eaxSetBufferMode(1, &uiBuffer, alGetEnumValue("AL_STORAGE_ACCESSIBLE"));
-            /// alBufferData(...);</summary>
-            Acessible = 2,
         }
 
+        /// <summary>This function is used to set the storage Mode of an array of OpenAL Buffers.</summary>
+        /// <param name="n">The number of OpenAL Buffers pointed to by buffer.</param>
+        /// <param name="buffer">An array of OpenAL Buffer handles.</param>
+        /// <param name="mode">The storage mode that should be used for all the given buffers. Should be the value of one of the following enum names: XRamStorage.Automatic, XRamStorage.Hardware, XRamStorage.Accessible</param>
+        /// <returns>True if all the Buffers were successfully set to the requested storage mode, False otherwise.</returns>
         [CLSCompliant(false)]
-        public void SetBufferMode( int n,ref uint buffer,XRamStorage mode )
+        public bool SetBufferMode( int n,ref uint buffer,XRamStorage mode )
         {
             switch ( mode )
             {
-            case XRamStorage.Acessible:
+            case XRamStorage.Accessible:
-                Imported_SetBufferMode(1,ref buffer,AL_STORAGE_ACCESSIBLE);
+                return Imported_SetBufferMode(n,ref buffer,AL_STORAGE_ACCESSIBLE);
-                break;
             case XRamStorage.Hardware:
-                Imported_SetBufferMode(1,ref buffer,AL_STORAGE_HARDWARE);
+                return Imported_SetBufferMode(n,ref buffer,AL_STORAGE_HARDWARE);
-                break;
             default:
-                Imported_SetBufferMode(1,ref buffer,AL_STORAGE_AUTOMATIC);
+                return Imported_SetBufferMode(n,ref buffer,AL_STORAGE_AUTOMATIC);
-                break;
             }
         }
 
+        /// <summary>This function is used to retrieve the storage Mode of a single OpenAL Buffer.</summary>
+        /// <param name="buffer">The handle of an OpenAL Buffer.</param>
+        /// <returns>The current Mode of the Buffer.</returns>
         [CLSCompliant(false)]
         public XRamStorage GetBufferMode( ref uint buffer )
         {
-            int t; // this is improper, find sample codes using it and figure out what 2nd param does.
+            int tempresult= Imported_GetBufferMode(buffer,IntPtr.Zero); // IntPtr.Zero due to the parameter being unused/reserved atm
-            return (XRamStorage) Imported_GetBufferMode(buffer,out t);
+
+            if ( tempresult == AL_STORAGE_ACCESSIBLE )
+                return XRamStorage.Accessible;
+            if ( tempresult == AL_STORAGE_HARDWARE )
+                return XRamStorage.Hardware;
+            // default:
+            return XRamStorage.Automatic;
         }
 
         #endregion Public Methods