Paradice Software

Since releasing the Paradice Five Hundred game all those years ago, one of the most consistent pieces of feedback I receive is that the AI partners and opponents don’t play optimally.

This.. is very likely true. I’m limited in that I can only design a computer player that plays as well as I know how to play, I’m not the best player by any means, and to be honest, I don’t have any group of players in my current city that I could even play with to get any better.

Previously, commenters have offered to assist me in improving the AI, but the advice has turned out to be in the form of vague statements involving things like ‘common sense’ or “why doesn’t it do X” which are, without the context of the hand, are quite simply not specific enough to program! So I would like to issue a challenge. I’ve created a Decision Tree diagram that represents how the AI currently makes it’s decisions; here it is:

Help me make this better!

If you’d like to play Five Hundred against computer opponents, but you’re frustrated by the way they currently play, I encourage you to click into and scroll around the current diagram.

Where you find errors in how the AI plays – feel free to write create a new section of logic (ideally draw it as a similar diagram, but I’ll settle for anything readable) and make it really clear EXACTLY where in the decision tree you’re replacing, and make sure every scenario from that point downwards is covered. Once I receive something, I’ll update the back-end code and release a new version, which you can then play!

To make the above decision tree, I used a tool called SmartDraw (free 7 day trial online), but really, you could use Powerpoint, Excel, or even just use Paint and edit the existing image.

If you’ve created something, leave a comment below with somewhere you’ve uploaded the image, or just your email address and I’ll get in touch.

I’m currently designing a minimalistic user interface in FPC (Freepascal), and I wanted it to blend in with the existing Windows desktop. So naturally, I started looking for how to obtain the user’s chosen accent color (I’m deliberately alternating American and British spelling of colour/color to help anyone that needs this to be able to google it successfully!)

Knowing Microsoft, I knew obtaining this probably wasn’t going to be as easy as back in the old Win32 days, where there was a simple API like GetSysColor(COLOR_ACTIVECAPTION), but I still had hopes that it wasn’t going to be too difficult.

As is often the case, the best reference I could find on how to do this was in Raymond Chen’s blog. Helpfully, he even demonstrates how to obtain this value in “raw C++”, which is the closest equivalent we can expect to doing so in FPC. Here’s the sample:

namespace abi_vm = ABI::Windows::UI::ViewManagement;
namespace wrl = Microsoft::WRL;
namespace wf = Windows::Foundation;

void GetAccentColor()
{
    wrl::ComPtr<abi_vm::IUISettings> settings;
    wf::ActivateInstance(wrl::Wrappers::HStringReference(
     RuntimeClass_Windows_UI_ViewManagement_UISettings).Get(), &settings);
    ABI::Windows::UI::Color color;
    settings->GetColorValue(abi_vm::UIColorType::Accent, &color);
}

OK; it looks manageable, except in FPC, we don’t have access to any of those namespace compiler definitions. Which are leveraged for everything. So this isn’t going to be straightforward. Someone else must have solved this problem though, right? If not for FPC, then for Delphi? After an hour of Googling… no, I don’t think the source code exists for this in Pascal anywhere on the internet.

Breaking it down

Let’s look at what this code actually does, then we can hopefully rewrite it in FPC, step-by-step:

1. Define a COM interface to UISettings
2. Figure out what that HStringReference wrapper does
3. Call a function called ActivateInstance()
4. Call UISettings.GetColorValue() to obtain colour
5. Tidying up

Allright. I’ve used COM before. So let’s get started! I’ll go into a lot of detail, because there’s a good chance there’s someone out there that wants to take this code and port it to yet another language that has no code sample! For those that just want the results, download the source code at the end.

1. Define a COM interface to UISettings

First problem with this: I don’t know what the UISettings interface looks like, and I’m going to need to write a complete definition of the interface (as well as the GUID) in order to use it correctly. There’s no real way to ‘discover’ this, either. You just have to search for an existing definition in any language, and translate it. Fortunately, there’s a handy definition available on Github. From there, it was relatively straightforward to translate it into the Pascal dialect. But first! IUISettings derives from IInspectable, which seems to be common to all of the WinRT APIs. So we have to translate that first:

type
   IInspectable = interface (IUnknown)
   ['{AF86E2E0-B12D-4c6a-9C5A-D7AA65101E90}']
      function GetIIDs (out iidCount: Cardinal; out IIDs: PGUID): HRESULT; stdcall;
      function GetRuntimeClassName (out ClassName: HSTRING): HRESULT; stdcall;
      function GetTrustLevel (out Trust: TrustLevel): HRESULT; stdcall;
   end;

And you can see from there, we also need definitions for HSTRING, and for an enum called TrustLevel (while we’re here, I’ll add other types we need later too):

type
   HSTRING    = type THandle;
   TrustLevel = (BaseTrust, PartialTrust, FullTrust);
   PCNZWCH    = PWideChar;
   RO_INIT_TYPE = (RO_INIT_SINGLETHREADED, RO_INIT_MULTITHREADED);	
   TUIColorType = (Background=0,Foreground=1,AccentDark3=2,AccentDark2=3,AccentDark1=4,Accent=5,AccentLight1=6,AccentLight2=7,AccentLight3=8,Complement=9,Force_Dword=$7fffffff);

Here, for the first time, I actually got lucky. The IUISettings interface contains a whole bunch of functions and new types (you can see them here on Github, starting at line 699), and normally to define the interface you need to translate all of them. However, Microsoft added extra functionality in newer versions of the interface, IUISettings2, IUISettings3 and IUISettings4, and it so happens that the only function we need GetColorValue, is in IUISettings3 – and it’s the only function in that interface! This makes translation trivial, and we now have all the definitions we need.

type
   IUISettings3 = interface (IInspectable)
      ['{03021BE4-5254-4781-8194-5168F7D06D7B}']
      function GetColorValue (desiredColor: TUIColorType; out Value: UINT32): HRESULT; stdcall;
   end;

2. Figure out what that HStringReference wrapper does

Well, obviously it’s a wrapper for an HSTRING. What’s an HSTRING? It’s how the Windows Runtime manages strings (because there weren’t enough string types already). For FPC’s purposes, they’re equivalent to Handles. The function we need to call in step 3, ActivateInstance(), takes an HSTRING as it’s first parameter.

It turns out we can manipulate HSTRINGs using the WindowsCreateString() and WindowsDeleteString() functions in the Windows Runtime. Of course, FPC has no idea about HSTRINGs or about the Windows Runtime in general. Additionally, we don’t want to make our program dependent on the Windows Runtime (Windows 8+) unnecessarily – not being able to acquire the user’s accent color is a really poor reason to prevent an application from executing on earlier Windows versions. So we need to use dynamic linking. The key code you need to dynamically link against the Windows Runtime (for our purposes) is as follows:

const
   WINRTSTRING_DLL = 'api-ms-win-core-winrt-string-l1-1-0.dll';
type
   TWindowsCreateString = function (sourceString: PCNZWCH; Length: UINT32; out Str: HSTRING): HRESULT; stdcall;
   TWindowsDeleteString = function (Str: HSTRING): HRESULT; stdcall;

For space, I’ll leave out the usual calls to LoadLibrary and GetProcAddress; they’re included in the full downloadable source code at the end of this article. Now we have some functions we can use to obtain HSTRINGs from PWideChar strings (which are FPC-native), what do we actually populate the HSTRING with? What’s this – RuntimeClass_Windows_UI_ViewManagement_UISettings ?

OK, that one’s easy. It’s just a constant string:

const
RunTimeClass_UISettings = WideString('Windows.UI.ViewManagement.UISettings')

3. Call a function called ActivateInstance()

Getting closer to the action… now we’ve got the HSTRING, and we’ve got the interfaces we want to populate. But what is this wf::ActivateInstance() call?

This function is defined in the Windows Runtime too, and it’s how we actually instantiate the UISettings interface. But before we do so, and similarly to how normal COM works, we need to initialize (and eventually uninitialize) the runtime itself before we can instantiate interfaces from it. As before, here are the types you need for dynamic linking:

const
   WINRTCORE_DLL   = 'api-ms-win-core-winrt-l1-1-0.dll';
type
   TRoInitialize        = function (InitType: RO_INIT_TYPE): HRESULT; stdcall;
   TRoUninitialize      = procedure; stdcall;
   TRoActivateInstance  = function (activatableClassId: HSTRING; out Instance: IInspectable): HRESULT; stdcall;

And finally, here is how we put it all together to finally obtain a usable IUISettings3 interface instance:

// ALL ERROR checking omitted - refer to source code at end of article!
var
   Hstr : HSTRING;
   Inspectable : IInspectable;
   UISettings : IUISettings3;
begin
   RoInitialize(RO_INIT_MULTITHREADED);
   WindowsCreateString(RunTimeClass_UISettings
      ,Length(RunTimeClass_UISettings),hstr);
   RoActivateInstance(hstr,Inspectable);
   UISettings := Inspectable as IUISettings3;
   // ..use our UISettings object!
   UISettings := nil;
   Inspectable := nil;
   WindowsDeleteString(hstr);
   RoUninitialize; // more on this below
end;

4. Call UISettings.GetColorValue() to obtain colour

After all the setup work to get to this point, this part is trivially easy:

var
   color : dword;
begin
   UISettings.GetColorValue(Accent,color);
end;

Accent is the TUIColorType enum we defined earlier; if you’re lazy, you can replace this with the magic integer 5. Color is the same type as Windows’ GDI Color: a dword, in BRGA format.

5. Tidying up

If you’ve been following along, you should be able to build a working sample from the above code, but if you run it, it won’t be quite perfect. It’ll work, and you’ll get an actual color value, BUT your program will exception out with an Access Violation when your IUISettings interface variable leaves scope.

This is an unfortunate consequence of FPC not having a native understanding of the types we’re working with; even though we explicitly set UISettings and Inspectable to nil, the compiler still believes we’re holding a reference, and finalizes it when the variables leave scope. Unfortunately, if that’s *after* we’ve called RoUninitialize, we’ll take an access violation. I’ve tried various methods to try and figure out where FPC thinks the extra reference is, or alternatively to try and tell it *not* to be smart about finalization, but I’ve only found three methods that work reliably:

1. Just don’t call RoUninitialize
2. Make sure the variable’s scope ends before calling RoUninitialize
3. Move RoInitialize and RoUninitialize to unit initialization/finalization seconds

Of the three, the second is my preferred option – and the way you’ll find it laid out in the attached source code. FPC doesn’t quite have the fine-grained scope control of C++, but you can simply wrap a nested procedure or function to do the same job. In pseudocode:

begin
   RoInitialize(RO_INIT_MULTITHREADED);
   DoActualWork;
   RoUninitialize;
end.

procedure DoActualWork;
var
   UISettings: IUISettings3;
begin
    // ... etc
end;

Option 3 (using an FPC Unit’s initialization/finalization sections) works just fine too – and I’d probably use that if I was going to statically link to the WinRT DLLs; but with Dynamic Linking, I chose to keep everything self-contained within a function instead.

Side note: If you have a smarter way of trying to prevent FPC from generating the spurious finalization call, I’d love to hear it!

Source Code and demo

Because I couldn’t find an FPC version of this code anywhere else on the internet, I’ve made the smallest possible working code sample available too (tested with FPC 3.0.4). Here’s the source code and a compiled demo download. (18.6KB).

It’s finally ready! There was some scope changes involved in this version, which is why it’s taken much longer than expected, but here it is!

Key new features in this version:

• Achievements! Over 20 specific in-game achievements to unlock
• Assisted check for new versions/update process
• Support for fullscreen (and windowed fullscreen) display modes
• Three different AI play styles to choose between
• Bugfixes, new cardsets, new backdrops

Download here, or at the Downloads page.

Paradice 500 is totally free; and comes with no advertising, spyware, shareware or anything like that. It was created with the single goal of wanting to create the best computer version of Five Hundred, ever.

Please remember to leave a comment if you enjoy!

Well it’s been a year between major updates (I seem to get the most time to work on this over Christmas/new years), but a new version of the Five Hundred is almost ready and will be released in the next few days.

I have been busy and have added quite a few new features, though! Such as:

• Achievements!
• Can easily check and download new versions
• Windowed, fullscreen, and borderless window modes
• Controls for volumes and game speeds
• Smoother animations
• Tweaked artificial intelligence
• New cardsets, tables and cardbacks included

In the background, there is a lot of work towards making an online multiplayer mode however I’m suffering from lack of people to test this with. It’s not far away, though!

Consider the following code, which might be part of a custom Font class to draw fancy text.

procedure DrawText(Text: String; Position: TRect; Color: dword);

Looks good, right? Parameters are clear, order makes sense, and it’s easy to understand what the code does when you find it invoked:

// some random stuff
Font.DrawText('Hello!',Window.Position,COL_WHITE);
// more random stuff

No need to go searching for the function implementation, or hovering over using the IDE to figure out what the parameters mean. It’s very clear. But now, say you want to add the ability to draw a “drop shadow” behind the text. No worries, let’s add a boolean parameter:

// Method declaration
procedure DrawText(
   Text: String; Position: TRect; Color: dword; Shadow: boolean);

// Invocation
Font.DrawText('Hello!',Window.Position,COL_WHITE,true);

Hmm. It’s not terrible, and if you use DrawText a lot you will soon pick up the meaning, but a little bit of clarity has been lost. You might get smarter and make Shadow an optional parameter which defaults to false, to prevent breaking any existing code. But now… you want to add the ability for text to be horizontally and/or vertically centered within the position rect. Let’s see:

// Method declaration
procedure DrawText(
   Text: String; Position: TRect; Color: dword; Shadow,CentreX,CentreY: boolean);

// Invocation
Font.DrawText('Hello!',Window.Position,COL_WHITE,true,true,false);

OK, at this point the function’s invocation is no longer readable by itself. Worse, no matter how many times you use it, you’re bound to forget the order of those parameters occasionally. I should know, the above function was ripped directly out of my old custom bitmap-font based class. But when I needed to add wordwrapping and other alignment options, it needed to go.

In general, if the meaning of a boolean parameter isn’t made totally obvious by the function name, it might not be the most readable solution. One of the golden rules of programming: it’s harder to read code than to write, so any extra effort to make it easier to read later is time well spent.

Use Sets as parameters!

It’s a little bit more setup, but you (and anyone else reading your code) will thank you if you take the time to implement a set. (if your language doesn’t support sets, constant values achieve the same result, but are very slightly less readable, and also don’t protect you against invalid values being passed).

// Type declaration
TTextStyles      = (
   TS_DropShadow ,
   TS_CentreX    ,
   TS_CentreY    ,
   TS_WordWrap   );

TTextStyle       = set of TTextStyles;

// Method declaration
procedure DrawText(
   Text: String; Position: TRect; Color: dword; Style: TTextStyle);

// Invocation
Font.DrawText('Hello!',Window.Position,COL_WHITE,[TS_DropShadow,TS_CentreX]);

It’s instantly obvious what the invocation does; no need to look up parameters. A bonus feature is the set of available styles can easily be extended without breaking any existing code.

The main downside is that it’s harder to generate set values inline compared to boolean functions, so if the parameters to your particular method tend to change depending on conditional evaluation, it can be a bit of a pain. But in this example, the readability benefit is worth the extra effort during declaration.

This post is kind of an open question. I’m hoping that I can get some comments, any comments, on it 🙂

Let’s set up a situation with a problem, and look at different solutions for addressing the problem. Which one do you think is best, and more importantly, why?

The Setup

There is a multithreaded application, which offloads work items to a worker thread, and uses TEventObject.SetEvent call to signal to the main thread “hey, all done”. Note: the worker thread doesn’t just complete this one task and then exit; it instead sleeps until another work item is generated.

The Problem

We want the main thread to wait for either a Windows message to be received, OR for the worker thread’s event to be signalled. Win32 provides a handy function for doing exactly this: MsgWaitForMultipleObjects with the event object’s handle and with QS_ALLINPUT as the wakemask.

However, FPC’s implementation of TEventObject doesn’t expose the OS handle, so we can’t call Win32 functions on it. (TEventObject inherits from THandleObject, whose reason for existance is encapsulating an operating system handle, however it’s actual “Handle” property is a pointer and the documentation explicitly states TEventHandle is an opaque type and should not be used in user code).

From looking at the actual implementation of TEventObject, you can determine that the Windows Handle needed is the very first member of the structure pointed to by the “Handle” property, however.

TEventObject.WaitFor() is clearly the intended usage, however that would block on that event only, and doesn’t wake up if window messages are received, therefore doesn’t address the situation.

(Note: it makes perfect sense why TEventObject is abstracting the Windows handle; otherwise it would be too easy to break cross-platform source compatibility, which is something FPC tries really hard to maintain. However, in this scenario the project is locked to Win32 for a number of reasons, so we should take advantage of it’s capability to wait for both events and messages without polling if we can.)

The Options

Here are the options, as I see it (I may have missed some!)

1. Reinvent: Reimplement the whole TEventObject functionality, which will mostly be line-for-line identical except that the windows Handle will be an accessible property instead of hidden behind an opaque pointer type.
2. Typecast: Apply the typecast of HANDLE(TEventObject.Handle^) to grab the windows handle out of the opaque type, disable the warning, and just hope the implementation behind the opaque type doesn’t change in a future version of FPC.
3. Monitor: – Create a third thread, whose only purpose in life is to call TEventObject.WaitFor. Then back in the main thread, call MsgWaitForMultipleObjects on the third thread’s TThread.Handle (since it’s implementation is different: the TThread.Handle property IS a directly usable Windows handle without a typecast.
4. Poll: Call TEventObject.WaitFor with a small timeout of say 10 millseconds, and pump window messages between waits.

Discussion Please!

In my view,:

1. Reinvent is the safest, but also doesn’t feel great; turning our backs on FPC’s otherwise simple and elegant synchronization objects.
2. Typecast is the easiest and results in exactly the behaviour that we want, but “it’s not guaranteed safe forever”.
3. Monitor is safe, but burning an entire extra thread seems like overkill, and maybe worse than polling in #4.
4. Poll works, but eats a lot of unnecessary context switches if the application is just idling and there’s no work going on. (A Sleep(10) in an idle loop consumes about 1% of an entire logical processor just in context switches)

Would love to hear your thoughts about how you would approach this. Remember the problem isn’t that the problem can’t be resolved (there are at least 4 solutions above, and maybe more I’ve missed), the problem is picking the ‘best’ solution, so your thoughts about why you would recommend a particular approach are the most valuable.

So, using thread Suspend and Resume functionality is deprecated in Delphi, Freepascal, and even Windows MSDN itself warns against using it for synchronization.

There are good reasons for trying to kill this paradigm: suspending and resuming other threads from the one you’re currently on is a deadlock waiting to happen, and it’s typically not supported at all in OS’es other that Windows. The only circumstance where it’s needed is to start execution of a thread that was initially created suspended (to allow additional initialization to take place). This is still supported and a new command has been added to FPC/Delphi called “TThread.Start” which implements this.

However, a number of people are confused about how to correctly re-implement their “worker thread” without using suspend/resume; and some of the advice given out hasn’t been that great, either.

Let’s say you have a worker thread which normally remains suspended. When the main thread wants it to do something, it pushes some parameters somewhere and then resumes the thread. When the thread is complete, it suspends itself. (note: critical sections or other access protection on the “work to do” data needs to be here too, but is removed for clarity):

{the worker thread's execution}
procedure TMyThread.Execute;
begin
   repeat
      if (work_to_do) then
         //...do_some_work...
      else
         Suspend;
   until Terminated;
end;

{called from the main thread:}
procedure TMyThread.QueueWork(details);
begin
   //...add_work_details...
   if Suspended then
      Resume;
end;

Although the particular example above still works, now’s a good time to go ahead and clean this up so that you’re not depending on deprecated functions.

Here’s where we get to the inspiration for today’s post. The suggested ‘clean up’ is often implemented using polling. Let’s take something I saw suggested on stackoverflow as a replacement for the above:

procedure TMyThread.Execute;
begin
   repeat
      if (work_to_do) then
         //...do_some_work...
      else
         Sleep(10);
   until Terminated;
end;

procedure TMyThread.QueueWork(details);
begin
   //...add_work_details...
end;

Yuck! What’s the problem with this design? It’s not particularly “busy”, since it sleeps all the time, but there are issues. Firstly: if the thread is idle, it can be 10-milliseconds before it gets around to realizing there’s any work to do. Depending on your application that may or may not be a big deal, but it’s not exactly elegant.

Secondly (and this is the bigger one for me), this thread is going to eat 200 context switches per second (2 per 10ms), whether busy or not. A far worse design than the original! Context switches aren’t free! If we assume 50,000 nanoseconds per context switch (0.05ms), which seems a reasonable finding, 200 of them per second just ate 1% of the total capacity of a processor core, to achieve nothing except wait. There’s a better solution, right?

Use Event Objects

Fortunately, there are better ways than Sleeping and Polling. The best replacement for the above scenario is just to deploy an event. Events can be “signalled” or “nonsignalled”, and you can let the operating system know “hey, I’m waiting for this event”. It will then go away and not waste any more cycles on you until the event is signalled. Brilliant! How do you do this? Well, it depends on your language:

• Win32 itself exposes event handles (see CreateEvent) which can be waited on with the WaitFor family of calls
• Freepascal provides a TEventObject, which encapsulates the Win32 (or other OS equivalent) functionality
• Delphi uses TEvent, which does the same thing
• C# uses System.Threading.ManualResetEvent (and related)

Here’s how to rewrite the above handler using a waitevent, so it consumes no CPU cycles until an event arrives. (I’ll use the FPC mechanism, but they’re functionally identical in all the other languages).

constructor TMyThread.Create;
begin
   //...normal initialization stuff...
   mEvent := TEventObject.Create(nil,true,false,'');
end;

{the worker thread's execution}
procedure TMyThread.Execute;
begin
   repeat
      mEvent.WaitFor(INFINITE);
      mEvent.ResetEvent;
      if (work_to_do) then
         //...do_some_work...
 until Terminated;
end;

{called from the main thread:}
procedure TMyThread.QueueWork(details);
begin
 //...add_work_details...
 mEvent.SetEvent;
end;

Presto! Thread will happily wait until a new piece of work comes in, without consuming any CPU cycles at all, and it will respond immediately once there’s something to do. The only caveat on this design? The only way out of the .WaitFor() call is for the event to be signalled, so you also need to account for this when you want to terminate the thread for good. (note that FPC’s TThread.Terminate isn’t virtual, so we have to cast to TThread to get the correct call):

procedure TMyThread.Terminate;
begin
   // Base Terminate method (to set Terminated=true)
   TThread(self).Terminate;

   // Signal event to wake up the thread
   mEvent.SetEvent;
end;

Sorted!

In Windows Vista and earlier, the operating system managed a list of audio (playback) devices, and one of them was always specified as the ‘default’. This is how audio devices may have looked on such a system:

1. Speakers (Default)
2. USB Headset
3. Realtek rear audio jack

Applications using Windows’ built-in sound functions such as PlaySound() always played to the default device, while games and other more sophisticated software could enumerate the available audio devices and allow the user to choose, while still typically selecting whichever device is marked as ‘default’ if the user doesn’t express a preference.

Windows 7 changed the game a little bit, by introducing a new, virtual device called the “Default Audio Device”. If a user running Windows 7 on the same hardware as above opens up Control Panel and goes into Sound, they will still see the same three devices, so nothing appears to have changed. However, applications that enumerate the available devices now see something different:

1. Default Audio Device (Default)
2. Speakers
3. USB Headset
4. Realtek rear audio jack

In the above scenario, the speakers are still the default *physical* device (and the device that the user sees as Default in control panel), however the new, virtual device is the default device to applications. I fan application selects either device 1 or 2 in the list above, they will both play to the speakers. So, why implement this feature and change the relationship between what the application sees and the user sees?

The primary benefit is that the Default Audio Device automatically remaps to the default physical device whenever it changes, *instantly*. Whereas on previous versions of Windows if you did something like start playing a song in WinAmp with the Speakers as the default audio, then changed the default to the USB Headset, your music would continue to play through the speakers until the start of the next song (or whenever the application closed and reopened it’s audio channel).

Implementing Support in Applications

I strongly, strongly encourage you to ensure you support playback to the Default Audio Device in your application. Having a program or game that *doesn’t* change automatically these days is enough to make me stop using it (looking at Diablo III here!). If you’re using the awesome BASS Audio Library (which I continue to endorse wholeheartedly), here’s how you do it:

BASS_SetConfig(BASS_CONFIG_DEF_DEFAULT,true); // Use Default device
BASS_Init(-1,Frequency,0,0,nil); // Initialize audio

Now, if WinAmp is playing to the (virtual) Default Audio Device, and the physical default changes, the music changes to the new device *instantly*. WinAmp doesn’t have to poll or register a callback event or do anything. For users who switch between devices several times a day, support for this feature is a godsend!

Changing Default Device Programatically

The only problem? Microsoft haven’t provided any way to programmatically change the default audio device. They really really want you to do it manually, through the control panel each time. That’s really painful; the best solution I have found so far is using scripting to simulate opening the control panel and changing the defaults, similar to what’s described here. Not that elegant, but it gets the job done.

This topic seems to come up quite a lot, and yet the majority of the time, there’s no clear answer. Take the scenario: you have a game or an application, and there’s some downtime. You’ve noticed in task manager that your apps remains at a high CPU Usage% even while it’s not doing anything, and you want to reduce it somehow. Which way is best?

This is where questions like “is Sleep(0) better than Sleep(1)? How about Sleep(50)? Or WaitForSingleObject, or WaitForMultipleObjects, or MsgWaitForMultipleObjects? Should I use the (deprecated) Multimedia Timers? Where does WaitFor() come in?

More often than not, answers to these questions describe how these functions *shouldn’t* be used, but a lot of the time they skip or gloss over an actual proposed alternative. The correct answer, of course, is that ‘it depends’: on the type of application you’re writing, the situation you’re in, and what you’re waiting *for*. With that in mind, however, let’s look at some concrete answers for common situations!

Games

For games, the answer is actually pretty simple. Your main thread almost never wants to sleep or wait for anything! There are two common scenarios: If you have a fullscreen, 3D or action game: never wait, just continually run the game loop and you get improved FPS. If you have a puzzle, card or strategy-type game, you may want to lock the framerate to the screen’s refresh rate. In that case, the best and only place for your application to wait is inside Direct3D’s Present() method, after calling Device.Reset() with PresentationInterval = D3DPRESENT_INTERVAL_DEFAULT. There it will happily render the scene while it waits for the appropriate time to elapse, and not waste any CPU cycles.

If you have a windowed game and it gets minimized, you again have two choices: either just keep the game running, or pause the game and wait for it to be restored. To keep running, just ignore the minimize event! If you want to wait efficiently until the player restores the window, the best way is something like this:

while (GameWindow.Minimized) do begin
   WaitMessage;         // Wait until new message arrives
   PumpWindowMessages;  // Process all pending WM_ messages 
end;

Assuming your WindowProc handles WM_ACTIVATE correctly to restore the game window’s state, this is all you need! Your application will receive exactly zero CPU time until a message arrives for it; it will immediately handle any messages that do come in (thus remaining responsive), and the instant the application is restored, normal play will resume.

Waiting for a worker Thread to finish

No contest here. This is exactly what the WaitFor() function was designed for. Use it! Note that “WaitFor” isn’t a Win32 API, but a version of this function is implemented by a wide variety of languages with threading support. FPC’s Windows implementation of TThread.WaitFor essentially does the following; if your chosen language doesn’t implement WaitFor, design something like this:

repeat
   Outcome := MsgWaitForMultipleObjects([Threadhandle,SynchronizeEvent],INFINITE,QS_SENDMESSAGE);

   case Outcome of
      WAIT_OBJECT_0  {ThreadHandle}    : ExitFlag := true; 
      WAIT_OBJECT_0+1{SynchronizeEvent}: CheckSynchronize; // Execute Synchronize() calls
      WAIT_OBJECT_0+2{a WindowMessage} : PeekMessage(PM_NOREMOVE);
   end;
until (ExitFlag);

In other words, it calls MsgWaitForMultipleObjects specifying a handle to the thread to wait for, a global handle that is signalled if a thread calls Synchronize() on a method, and specifies to exit if a message is received from another thread or process. If the thread ending was the outcome, the function exits. Otherwise, it either executes the synchronized method, or peeks at the window messages, and starts waiting again. (If there’s a GUI, the application may wish to alter this behavior by waiting on QS_ALLINPUT and actually dispatching window messages instead of just peeking). Beware that if you’re waiting for a worker thread *from* the main thread, and the main thread also controls the GUI, make sure your language implementation includes a way to pump window messages during WaitFor(), or your GUI will stop responding up until the thread eventually completes.

The importance of the “SynchroniseEvent” wait allows other threads (including, potentially, the thread you’re waiting for) to execute Synchronized() procedure calls on the main thread while you wait. If this wasn’t included, attempting a synchronized procedure call (also know as an Asynchronous Procedure Call or APC) could cause a deadlock.

GUI application waiting for user input

WaitMessage. Very simple!

Non-GUI thread in an application that needs to poll something

This is where it gets tricky. Applications should *try* to avoid polling whenever they possibly can, because by definition it wastes CPU cycles: waking up a thread just to check one value and then going back to sleep is wasting two context switches worth of processor every time. So, if you’re in control of the information you’re polling for, rewrite it as an alert or an event mechanism (using a callback function, a custom window message, or a waithandle; whatever works for you!) so that you can just wait until it’s done. However, if you’re not in control of the source, sometimes you have to poll.

while not (<check some event>)
   Sleep(50);

Works best in this situation. 50ms is short enough to remain responsive when the event happens, but generous enough that the OS will be able to give several timeslices to other processes before it comes back to you. Note that internally, Windows implements Sleep() using a timeout waithandle and WaitForSingleObject(), so doing that does the same thing with more calls.

GUI thread in an application that needs to poll something

Similar to above, except that you need to be more responsive. You don’t want to wait 50 milliseconds to respond to window messages; that’s long enough to potentially cause irritation. So what we want is something like WaitMessage, but with a timeout. Here’s how:

while not (<check some event>) do begin
   MsgWaitForMultipleObjects(0,nil,false,50,QS_ALLINPUT);
   PumpWindowMessages; 
end;

Here, we call MsgWaitForMultipleObjects, using a timeout of 50 millisec and telling it we’re interested in all window messages, but don’t pass it any objects. This means that the function will wait until either the 50 milliseconds have elapsed, OR any window message is received (which we then want to pump immediately, being a GUI thread). Then as long as we’re awake, we check the polling condition before going back to sleep.

That’s it! A bunch of common situations, and the appropriate and graceful way to wait, sleep or yield your application. Hopefully this helps someone! Oh wait, I forgot something:

Sleep(0) and Sleep(1)

So, it turned out that in all of our situations, we never needed these. But they’re talked about quite a lot, so they must do something. What do they do?

Well, Sleep(0) yields the remainder of the current timeslice, but the thread remains ready to execute. This means that if the OS has no other threads or processes waiting to do something, it will return immediately. If there are other threads waiting, our thread will sleep and it’ll come back as soon as the scheduler finds time for it. The net effect? If it’s the only thing running on that processor, CPU Usage % on task manager will remain high. If other stuff is running, it will compete with that to run whenever possible.

Outcome? Not much is accomplished. If your application is actually busy doing something, you don’t want to randomly give up your timeslice. The scheduler will pre-empt you when it needs to: trust it! As long as it’s given you the processor, you should be using it. “ending early” like this is just generating needless context switches, with the result that your computer is slightly less efficient than it was before. If your application is *not* busy doing something, then you’re waiting! And you should use either the “wait for input” or the “wait and poll” methods described above. Don’t just sleep for tiny amounts of time.

Sleep(1) is slightly different. The 1 millisecond tells the scheduler “do not come back to me for at least 1 millisecond. (and it might be more like 5 or 10). Net result? This will reduce the CPU Usage % on task manager, even if it’s the only thing running, because you’re forcing the OS to ignore you temporarily. So it’s slightly ‘better’ in that sense. However, the question remains: why are you doing this? If your application is actually busy, you shouldn’t be sleeping. And if your application is actually waiting, you should use one of the waiting paradigms described above.

If your application is “just a little bit busy but you know, nothing important”, what you should be doing is using a worker thread, and setting it to a lower priority. That lets the OS scheduler control exactly when to allocate processor time. After all, even if you’re not doing anything important, it’s better than doing nothing at all. If the scheduler is able to give you that time, you may as well use it.

The final scenario where this might be tried is “my application needs to do something every 1 millisecond; otherwise it’s idle”. Sorry, but your approach is doomed: Sleep(1) guarantees at least a 1ms wait – it could be (and will probably be!) much more. If you really need this precise behavior, you need something better. That’s out of scope for this article though, it’s long enough already!

A short and simple post for today. Playing a video file in Freepascal, without using Lazarus.

I honestly couldn’t find any examples on the internet of how to do this, so I made one.

The DirectX9SDK has examples of how to use DirectShow/ActiveMovie to play back video files in C++, however, the common version of the DirectX headers for Delphi/FPC (Clootie’s graphics pages) don’t include the DirectShow headers, seemingly due to ActiveX dependencies.

For a lot of people, they might use video playback maybe once or twice in their whole application: playing a logo, or an end-of-game cutscene, and that’s it. Having to familiarise yourself with how to use COM, ActiveX and DirectShow in FPC seems like a lot of overhead just to achieve something so simple!

So, I created a handy class that takes care of all of that work and presents an extremely simple interface to anyone wanting to play video. Here’s how it works:

var
   VideoPlayer: TVideoPlayer;

begin
   VideoPlayer := TVideoPlayer.Create;
   VideoPlayer.PlayVideo('somevideofile.avi');
   VideoPlayer.Free;
end;

Download source code (including precompiled exe and sample video file) from the guide page.

The source code also shows you where to insert other code, if you want to do something useful while the video is playing (like loading other assets) or respond to user input.