ShuriZma
/
BizHawk
mirror of https://github.com/TASEmulators/BizHawk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve exception docs in BizHawk.Client.EmuHawk

This commit is contained in:
YoshiRulz 2020-01-02 06:06:48 +10:00
parent 3bab282e8d
commit 060255471b
No known key found for this signature in database
GPG Key ID: C4DE31C245353FB7
21 changed files with 78 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
BizHawk.Client.EmuHawk/AVOut/AVSync.cs
View File

@ -14,6 +14,10 @@ namespace BizHawk.Client.EmuHawk
private long _soundRemainder; // audio timekeeping for video dumping
/// <exception cref="InvalidOperationException">
/// <paramref name="asyncSoundProvider"/>'s mode is not <see cref="SyncSoundMode.Async"/>, or
/// A/V parameters haven't been set (need to call <see cref="SetAudioParameters"/> and <see cref="SetMovieParameters"/>)
/// </exception>
public void DumpAV(IVideoProvider v, ISoundProvider asyncSoundProvider, out short[] samples, out int samplesprovided)
{
// Sound refactor TODO: we could try set it here, but we want the client to be responsible for mode switching? There may be non-trivial complications with when to switch modes that we don't want this object worrying about
@ -78,6 +82,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="InvalidOperationException"><paramref name="syncSoundProvider"/>'s mode is not <see cref="SyncSoundMode.Sync"/></exception>
public void DumpAV(IVideoProvider v, ISoundProvider syncSoundProvider, out short[] samples, out int samplesprovided)
{
// Sound refactor TODO: we could just set it here, but we want the client to be responsible for mode switching? There may be non-trivial complications with when to switch modes that we don't want this object worrying about
@ -140,7 +145,7 @@ namespace BizHawk.Client.EmuHawk
protected int bits;
protected bool aset = false;
/// <exception cref="InvalidOperationException">already set</exception>
public new virtual void SetMovieParameters(int fpsnum, int fpsden)
{
if (vset)
@ -155,6 +160,7 @@ namespace BizHawk.Client.EmuHawk
base.SetMovieParameters(fpsnum, fpsden);
}
/// <exception cref="InvalidOperationException">already set, or <paramref name="bits"/> is not <c>16</c></exception>
public new virtual void SetAudioParameters(int sampleRate, int channels, int bits)
{
if (aset)
@ -180,11 +186,13 @@ namespace BizHawk.Client.EmuHawk
// this writer will never support this capability
}
/// <exception cref="InvalidOperationException">always</exception>
public new virtual void AddFrame(IVideoProvider source)
{
throw new InvalidOperationException("Must call AddAV()!");
}
/// <exception cref="InvalidOperationException">always</exception>
public new virtual void AddSamples(short[] samples)
{
throw new InvalidOperationException("Must call AddAV()!");

29
BizHawk.Client.EmuHawk/AVOut/AviWriter.cs
View File

@ -30,9 +30,8 @@ namespace BizHawk.Client.EmuHawk
_currSegment?.Dispose();
}
/// <summary>
/// sets the codec token to be used for video compression
/// </summary>
/// <summary>sets the codec token to be used for video compression</summary>
/// <exception cref="ArgumentException"><paramref name="token"/> does not inherit <see cref="AviWriter.CodecToken"/></exception>
public void SetVideoCodecToken(IDisposable token)
{
if (token is CodecToken)
@ -133,10 +132,8 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <summary>
/// opens an avi file for recording with the supplied enumerator used to name files.
/// set a video codec token first.
/// </summary>
/// <summary>opens an avi file for recording, with <paramref name="nameProvider"/> being used to name files</summary>
/// <exception cref="InvalidOperationException">no video codec token set</exception>
public void OpenFile(IEnumerator<string> nameProvider)
{
_nameProvider = nameProvider;
@ -158,6 +155,7 @@ namespace BizHawk.Client.EmuHawk
_currSegment = null;
}
/// <exception cref="Exception">worker thrread died</exception>
public void AddFrame(IVideoProvider source)
{
while (!threadQ.TryAdd(new VideoCopy(source), 1000))
@ -181,6 +179,7 @@ namespace BizHawk.Client.EmuHawk
_currSegment.AddFrame(source);
}
/// <exception cref="Exception">worker thrread died</exception>
public void AddSamples(short[] samples)
{
// as MainForm.cs is written now, samples is all ours (nothing else will use it for anything)
@ -316,6 +315,8 @@ namespace BizHawk.Client.EmuHawk
public bool has_audio;
public int a_samplerate, a_channels, a_bits;
/// <exception cref="InvalidOperationException"><see cref="a_bits"/> is not <c>8</c> or <c>16</c>, or <see cref="a_channels"/> is not in range <c>1..2</c></exception>
public void PopulateWAVEFORMATEX(ref AVIWriterImports.WAVEFORMATEX wfex)
{
const int WAVE_FORMAT_PCM = 1;
@ -640,6 +641,8 @@ namespace BizHawk.Client.EmuHawk
}
Parameters parameters;
/// <exception cref="InvalidOperationException">unmanaged call failed</exception>
public void OpenFile(string destPath, Parameters parameters, CodecToken videoCodecToken)
{
static int mmioFOURCC(string str) => (
@ -700,9 +703,8 @@ namespace BizHawk.Client.EmuHawk
}
/// <summary>
/// Acquires a video codec configuration from the user
/// </summary>
/// <summary>acquires a video codec configuration from the user</summary>
/// <exception cref="InvalidOperationException">no file open (need to call <see cref="OpenFile"/>)</exception>
public IDisposable AcquireVideoCodecToken(IntPtr hwnd, CodecToken lastCodecToken)
{
if (!IsOpen)
@ -741,9 +743,8 @@ namespace BizHawk.Client.EmuHawk
return null;
}
/// <summary>
/// begin recording
/// </summary>
/// <summary>begin recording</summary>
/// <exception cref="InvalidOperationException">no video codec token set (need to call <see cref="OpenFile"/>), or unmanaged call failed</exception>
public void OpenStreams()
{
if (currVideoCodecToken == null)
@ -882,6 +883,7 @@ namespace BizHawk.Client.EmuHawk
outStatus.audio_buffered_shorts = 0;
}
/// <exception cref="InvalidOperationException">attempted frame resize during encoding</exception>
public unsafe void AddFrame(IVideoProvider source)
{
const int AVIIF_KEYFRAME = 0x00000010;
@ -965,6 +967,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="Exception">no default codec token in config</exception>
public void SetDefaultVideoCodecToken()
{
CodecToken ct = CodecToken.DeSerialize(Global.Config.AVICodecToken);

7
BizHawk.Client.EmuHawk/AVOut/FFmpegWriter.cs
View File

@ -174,7 +174,7 @@ namespace BizHawk.Client.EmuHawk
return s.ToString();
}
/// <exception cref="Exception">FFmpeg call failed</exception>
public void AddFrame(IVideoProvider source)
{
if (source.BufferWidth != width || source.BufferHeight != height)
@ -206,7 +206,8 @@ namespace BizHawk.Client.EmuHawk
{
return FFmpegWriterForm.DoFFmpegWriterDlg(hwnd);
}
/// <exception cref="ArgumentException"><paramref name="token"/> does not inherit <see cref="FFmpegWriterForm.FormatPreset"/></exception>
public void SetVideoCodecToken(IDisposable token)
{
if (token is FFmpegWriterForm.FormatPreset)
@ -261,6 +262,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="Exception">FFmpeg call failed</exception>
public void AddSamples(short[] samples)
{
if (_ffmpeg.HasExited)
@ -285,6 +287,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="ArgumentOutOfRangeException"><paramref name="bits"/> is not <c>16</c></exception>
public void SetAudioParameters(int sampleRate, int channels, int bits)
{
if (bits != 16)

1
BizHawk.Client.EmuHawk/AVOut/GifWriter.cs
View File

@ -82,6 +82,7 @@ namespace BizHawk.Client.EmuHawk
private GifToken _token;
/// <exception cref="ArgumentException"><paramref name="token"/> does not inherit <see cref="GifWriter.GifToken"/></exception>
public void SetVideoCodecToken(IDisposable token)
{
if (token is GifToken gifToken)

12
BizHawk.Client.EmuHawk/AVOut/JMDWriter.cs
View File

@ -178,6 +178,8 @@ namespace BizHawk.Client.EmuHawk
/// underlying bytestream that is being written to
/// </summary>
Stream f;
/// <exception cref="ArgumentException"><paramref name="f"/> cannot be written to</exception>
public JMDfile(Stream f, int fpsnum, int fpsden, int audiosamplerate, bool stereo)
{
if (!f.CanWrite)
@ -535,9 +537,8 @@ namespace BizHawk.Client.EmuHawk
// we have no unmanaged resources
}
/// <summary>
/// sets the codec token to be used for video compression
/// </summary>
/// <summary>sets the codec token to be used for video compression</summary>
/// <exception cref="ArgumentException"><paramref name="token"/> does not inherit <see cref="JMDWriter.CodecToken"/></exception>
public void SetVideoCodecToken(IDisposable token)
{
if (token is CodecToken)
@ -589,9 +590,8 @@ namespace BizHawk.Client.EmuHawk
// each frame is dumped independently with its own resolution tag, so we don't care to store this
}
/// <summary>
/// set audio parameters. cannot change later
/// </summary>
/// <summary>set audio parameters, cannot change later</summary>
/// <exception cref="ArgumentException"><paramref name="sampleRate"/> is outside range <c>8000..96000</c>, <paramref name="channels"/> is outside range <c>1..2</c>, or <paramref name="bits"/> is not <c>16</c></exception>
public void SetAudioParameters(int sampleRate, int channels, int bits)
{
// the sampleRate limits are arbitrary, just to catch things which are probably silly-wrong

17
BizHawk.Client.EmuHawk/AVOut/NutMuxer.cs
View File

@ -66,6 +66,7 @@ namespace BizHawk.Client.EmuHawk
return GetBufferInternal(length, zerofill, a => a.Length >= length && a.Length / (float)length <= 2.0f);
}
/// <exception cref="ArgumentException"><paramref name="buffer"/> is not in use</exception>
public void ReleaseBuffer(T[] buffer)
{
if (!_inuse.Remove(buffer))
@ -580,16 +581,16 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <summary>
/// write a video frame to the stream
/// </summary>
/// <summary>write a video frame to the stream</summary>
/// <param name="data">raw video data; if length 0, write EOR</param>
/// <exception cref="Exception">internal error, possible A/V desync</exception>
/// <exception cref="InvalidOperationException">already written EOR</exception>
public void WriteVideoFrame(int[] video)
{
if (videodone)
throw new InvalidOperationException("Can't write data after end of relevance!");
if (audioqueue.Count > 5)
throw new Exception("A\\V Desync?");
throw new Exception("A/V Desync?");
int datalen = video.Length * sizeof(int);
byte[] data = _bufferpool.GetBufferAtLeast(datalen);
Buffer.BlockCopy(video, 0, data, 0, datalen);
@ -603,16 +604,16 @@ namespace BizHawk.Client.EmuHawk
audioqueue.Dequeue().WriteData(output);
}
/// <summary>
/// write an audio frame to the stream
/// </summary>
/// <summary>write an audio frame to the stream</summary>
/// <param name="data">raw audio data; if length 0, write EOR</param>
/// <exception cref="Exception">internal error, possible A/V desync</exception>
/// <exception cref="InvalidOperationException">already written EOR</exception>
public void WriteAudioFrame(short[] samples)
{
if (audiodone)
throw new Exception("Can't write audio after end of relevance!");
if (videoqueue.Count > 5)
throw new Exception("A\\V Desync?");
throw new Exception("A/V Desync?");
int datalen = samples.Length * sizeof(short);
byte[] data = _bufferpool.GetBufferAtLeast(datalen);
Buffer.BlockCopy(samples, 0, data, 0, datalen);

1
BizHawk.Client.EmuHawk/AVOut/NutWriter.cs
View File

@ -108,6 +108,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="ArgumentOutOfRangeException"><paramref name="bits"/> is not <c>16</c></exception>
public void SetAudioParameters(int sampleRate, int channels, int bits)
{
if (bits != 16)

12
BizHawk.Client.EmuHawk/AVOut/Quantize/OctreeQuantizer.cs
View File

@ -38,17 +38,11 @@ namespace BizHawk.Client.EmuHawk
/// </summary>
private int _maxColors;
/// <summary>
/// Construct the octree quantizer
/// </summary>
/// <remarks>
/// The Octree quantizer is a two pass algorithm. The initial pass sets up the octree,
/// the second pass quantizes a color based on the nodes in the tree
/// </remarks>
/// <param name="maxColors">The maximum number of colors to return</param>
/// <param name="maxColorBits">The number of significant bits</param>
public OctreeQuantizer(int maxColors, int maxColorBits)
: base(false)
/// <exception cref="ArgumentOutOfRangeException"><paramref name="maxColors"/> &ge; <c>256</c> or <paramref name="maxColorBits"/> outside range <c>1..8</c></exception>
/// <remarks>The Octree quantizer is a two pass algorithm. The initial pass sets up the octree, the second pass quantizes a color based on the nodes in the tree.</remarks>
public OctreeQuantizer(int maxColors, int maxColorBits) : base(false)
{
if (maxColors > 255)
throw new ArgumentOutOfRangeException(nameof(maxColors), maxColors, "The number of colors should be less than 256");

2
BizHawk.Client.EmuHawk/AVOut/WavWriter.cs
View File

@ -184,6 +184,7 @@ namespace BizHawk.Client.EmuHawk
/// <param name="ss">WavWriter now owns any of these streams that it enumerates</param>
/// <param name="samplerate">sampling rate in HZ</param>
/// <param name="numchannels">number of audio channels</param>
/// <exception cref="ArgumentException"><paramref name="ss"/> cannot be progressed</exception>
public WavWriter(IEnumerator<Stream> ss, int samplerate, int numchannels)
{
this.samplerate = samplerate;
@ -228,6 +229,7 @@ namespace BizHawk.Client.EmuHawk
return new WavWriterVToken();
}
/// <exception cref="ArgumentOutOfRangeException"><paramref name="bits"/> is not <c>16</c></exception>
public void SetAudioParameters(int sampleRate, int channels, int bits)
{
this.sampleRate = sampleRate;

1
BizHawk.Client.EmuHawk/ArgParser.cs
View File

@ -35,6 +35,7 @@ namespace BizHawk.Client.EmuHawk
public string URL_post = null;
public bool? audiosync = null;
/// <exception cref="ArgParserException"><c>--socket_ip</c> passed without specifying <c>--socket_port</c> or vice-versa</exception>
public void ParseArguments(string[] args)
{
for (int i = 0; i < args.Length; i++)

14
BizHawk.Client.EmuHawk/CustomControls/MsgBox.cs
View File

@ -52,23 +52,15 @@ namespace BizHawk.Client.EmuHawk.CustomControls
messageLbl.MaximumSize = new Size(MaximumSize.Width - _msgIcon.Width - UIHelper.ScaleX(25), MaximumSize.Height);
}
/// <summary>
/// Create up to 3 buttons with given DialogResult values.
/// </summary>
/// <param name="names">Array of button names. Must of length 1-3.</param>
/// <param name="results">Array of DialogResult values. Must be same length as names.</param>
public void SetButtons(string[] names, DialogResult[] results)
{
SetButtons(names, results, 1);
}
/// <summary>
/// Create up to 3 buttons with given DialogResult values.
/// </summary>
/// <param name="names">Array of button names. Must of length 1-3.</param>
/// <param name="results">Array of DialogResult values. Must be same length as names.</param>
/// <param name="def">Default Button number. Must be 1-3.</param>
public void SetButtons(string[] names, DialogResult[] results, int def)
/// <exception cref="ArgumentException">length of <paramref name="names"/> is not in range <c>1..3</c></exception>
/// <exception cref="ArgumentNullException"><paramref name="names"/> is null</exception>
public void SetButtons(string[] names, DialogResult[] results, int def = 1)
{
if (names == null)
{

12
BizHawk.Client.EmuHawk/DisplayManager/DisplayManager.cs
View File

@ -483,8 +483,10 @@ namespace BizHawk.Client.EmuHawk
public int BufferHeight { get; set; }
public int BackgroundColor { get; set; }
/// <exception cref="InvalidOperationException">always</exception>
public int VsyncNumerator => throw new InvalidOperationException();
/// <exception cref="InvalidOperationException">always</exception>
public int VsyncDenominator => throw new InvalidOperationException();
}
@ -968,9 +970,8 @@ namespace BizHawk.Client.EmuHawk
return null;
}
/// <summary>
/// Locks the requested lua surface name
/// </summary>
/// <summary>locks the lua surface called <paramref name="name"/></summary>
/// <exception cref="InvalidOperationException">already locked, or unknown surface</exception>
public DisplaySurface LockLuaSurface(string name, bool clear=true)
{
if (MapNameToLuaSurface.ContainsKey(name))
@ -1037,9 +1038,8 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <summary>
/// Unlocks this DisplaySurface which had better have been locked as a lua surface
/// </summary>
/// <summary>unlocks this DisplaySurface which had better have been locked as a lua surface</summary>
/// <exception cref="InvalidOperationException">already unlocked</exception>
public void UnlockLuaSurface(DisplaySurface surface)
{
if (!MapLuaSurfaceToName.ContainsKey(surface))

2
BizHawk.Client.EmuHawk/Extensions/ControlExtensions.cs
View File

@ -14,6 +14,7 @@ namespace BizHawk.Client.EmuHawk.WinFormExtensions
{
public static class ControlExtensions
{
/// <exception cref="ArgumentException"><typeparamref name="T"/> does not inherit <see cref="Enum"/></exception>
public static void PopulateFromEnum<T>(this ComboBox box, object enumVal)
where T : struct, IConvertible
{
@ -213,6 +214,7 @@ namespace BizHawk.Client.EmuHawk.WinFormExtensions
return sb.ToString();
}
/// <exception cref="Win32Exception">unmanaged call failed</exception>
public static void SetSortIcon(this ListView listViewControl, int columnIndex, SortOrder order)
{
const int LVM_GETHEADER = 4127;

1
BizHawk.Client.EmuHawk/GLManager.cs
View File

@ -20,6 +20,7 @@ namespace BizHawk.Client.EmuHawk
public static GLManager Instance { get; private set; }
/// <exception cref="InvalidOperationException">instance already created</exception>
public static void CreateInstance()
{
if (Instance != null)

1
BizHawk.Client.EmuHawk/MainForm.cs
View File

@ -2208,6 +2208,7 @@ namespace BizHawk.Client.EmuHawk
return FormatFilter(items.ToArray());
}
/// <exception cref="ArgumentException"><paramref name="args"/> contains unpaired element</exception>
public static string FormatFilter(params string[] args)
{
var sb = new StringBuilder();

3
BizHawk.Client.EmuHawk/Sound/Utilities/BufferedAsync.cs
View File

@ -58,6 +58,7 @@ namespace BizHawk.Client.EmuHawk
BaseSoundProvider.DiscardSamples();
}
/// <exception cref="InvalidOperationException"><see cref="BaseSoundProvider"/>.<see cref="ISoundProvider.SyncMode"/> is not <see cref="SyncSoundMode.Async"/></exception>
public void GetSamplesAsync(short[] samples)
{
int samplesToGenerate = SamplesInOneFrame;
@ -97,6 +98,7 @@ namespace BizHawk.Client.EmuHawk
get { return SyncSoundMode.Async; }
}
/// <exception cref="NotSupportedException"><paramref name="mode"/> is not <see cref="SyncSoundMode.Async"/></exception>
public void SetSyncMode(SyncSoundMode mode)
{
if (mode != SyncSoundMode.Async)
@ -105,6 +107,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="InvalidOperationException">always</exception>
public void GetSamplesSync(out short[] samples, out int nsamp)
{
throw new InvalidOperationException("Sync mode is not supported.");

3
BizHawk.Client.EmuHawk/Sound/Utilities/SoundOutputProvider.cs
View File

@ -63,6 +63,7 @@ namespace BizHawk.Client.EmuHawk
ResetBuffer();
}
/// <exception cref="InvalidOperationException">(from setter) constructed in standalone mode</exception>
public int MaxSamplesDeficit
{
get { return _maxSamplesDeficit; }
@ -124,6 +125,7 @@ namespace BizHawk.Client.EmuHawk
get { return SampleRate / Global.Emulator.VsyncRate(); }
}
/// <exception cref="InvalidOperationException">not constructed in standalone mode</exception>
public void GetSamples(short[] samples)
{
if (!_standaloneMode) throw new InvalidOperationException();
@ -132,6 +134,7 @@ namespace BizHawk.Client.EmuHawk
GetSamplesFromBuffer(samples, returnSampleCount);
}
/// <exception cref="InvalidOperationException">constructed in standalone mode</exception>
public void GetSamples(int idealSampleCount, out short[] samples, out int sampleCount)
{
if (_standaloneMode) throw new InvalidOperationException();

2
BizHawk.Client.EmuHawk/Sound/Utilities/SyncToAsyncProvider.cs
View File

@ -28,6 +28,7 @@ namespace BizHawk.Client.EmuHawk
get { return SyncSoundMode.Async; }
}
/// <exception cref="NotSupportedException"><paramref name="mode"/> is not <see cref="SyncSoundMode.Async"/></exception>
public void SetSyncMode(SyncSoundMode mode)
{
if (mode != SyncSoundMode.Async)
@ -36,6 +37,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="InvalidOperationException">always</exception>
public void GetSamplesSync(out short[] samples, out int nsamp)
{
throw new InvalidOperationException("Sync mode is not supported.");

1
BizHawk.Client.EmuHawk/tools/Lua/Libraries/EmuLuaLibrary.Forms.cs
View File

@ -1302,6 +1302,7 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="Exception">misformatted colour</exception>
[LuaMethodExample("forms.setproperty( 332, \"Property\", \"Property value\" );")]
[LuaMethod("setproperty", "Attempts to set the given property of the widget with the given value. Note: not all properties will be able to be represented for the control to accept")]
public void SetProperty(int handle, string property, object value)

2
BizHawk.Client.EmuHawk/tools/MultiDiskBundler/MultiDiskBundler.cs
View File

@ -255,6 +255,8 @@ namespace BizHawk.Client.EmuHawk
}
}
/// <exception cref="ArgumentException">running on Windows host, and unmanaged call failed</exception>
/// <exception cref="FileNotFoundException">running on Windows host, and either path is not a regular file or directory</exception>
/// <remarks>Algorithm for Windows taken from https://stackoverflow.com/a/485516/7467292</remarks>
public static string GetRelativePath(string fromPath, string toPath)
{

1
BizHawk.Client.EmuHawk/tools/VirtualPads/schema/NesSchema.cs
View File

@ -14,6 +14,7 @@ namespace BizHawk.Client.EmuHawk
// ReSharper disable once UnusedMember.Global
public class NesSchema : IVirtualPadSchema
{
/// <exception cref="Exception">found <c>ControllerSNES</c></exception>
public IEnumerable<PadSchema> GetPadSchemas(IEmulator core)
{
if (core is NES || core is SubNESHawk)