Getting Started

Getting started with the C++ AMP Algorithms Library is very easy. If you are already using C++ AMP then there are no additional system requirements and the library is entirely implemented as C++ templates with no binary dependencies to link to your project.

System Requirements

There are no additional requirements for the C++ AMP Algorithms Library beyond those required by C++ AMP. However to run the unit tests you will need to download and compile the Google Testing Framework. You will need the following hardware and software to build and use the C++ AMP Algorithms Library:

  • Either Microsoft Windows 7 with Service Pack 1 or Windows 8 (x86 or x64). The library should also build and run on Windows Server 2008 R2 (x64) and  Windows Server 2012 (x64), but they have not been tested on these OSs.
  • Visual Studio 2013, any edition. Visual Studio 2012 is no longer supported after release 0.9.4.
  • A DirectX 11 capable video card running at 1024 x 768 or higher-resolution display (for Visual Studio 2012). If you do not have a DX11 capable card you can still use the Library using the WARP or REF accelerators but with greatly reduced performance.

Debugging and WARP accelerator support is now available on Windows 7 and Windows Server 2008 RC2 with the Platform Update for Windows 7. The following blog posts outline how to use these:

NVidia has also added support for hardware debugging. You can read about how to enable this on the C++ AMP team’s blog too:

If you’re using Window 7 then installing these updates will improve your experience.

Installing the Library

Download the latest release and unzip it into a folder in your source tree. The download page is the best place to get the most up to date formal release. You can also download the source directly from the Source Code tab.

While the C++ AMP Algorithms Library is entirely header files and doesn’t require building it is a good idea to build and run the associated unit tests to ensure that everything is working correctly.

  1. Download the 1.7 version of the Google Testing Framework, googletest, and unzip the source.
  2. Create a GTEST_ROOT environment variable which contains the path to the root of the googletest source tree, e.g. C:\Src\gtest-1.7.0.
  3. Build googletest Win32, Release and Debug configurations:
    1. Modify the gtest-1.7.0\msvc\gtest.sln file have read/write permission. 
    2. Open the gtest-1.7.0\msvc\gtest.sln solution in Visual Studio 2013.
    3. Select OK at the upgrade dialog and save the upgraded solution as gtest.sln.
    4. Open the Batch Build dialog from the Build | Batch Build… menu. Use Select All and then Rebuild to build binaries for all configurations and platforms. Any warnings can be ignored.
  4. Open the amp_algorithms.sln solution in the root of the source tree.
  5. Build the project using the Release | Win32 configuration.
  6. Run the application without the debugger (Ctrl-F5). This will display test output.

You can also use the pre_checkin_build.ps1 PowerShell script to execute a full build of all supported build configurations and execute a unit test run from a PowerShell window.

Dealing with Failing Tests

What to do if one or more of the tests fails? The first thing to do is to verify that the issue is not driver related. Make sure that you have the latest drivers for your GPU installed and rerun the tests. If tests still fail then try running the tests on C++ AMP’s REF accelerator.

Rerun the amp_algorithms.exe with –verbose –device ref flags.

If all the tests pass then the bug is driver related and not an issue with the C++ AMP Algorithms Library. If the tests fail when run using the REF accelerator then please file a bug.

Building 64-bit

Unfortunately googletest does not come configured with a 64-bit build as part of the solution. Building the amp_algorithms solution for x64 will result in a “LINK : fatal error LNK1104: cannot open file 'gtest.lib'” error. The following describes how to modify the gtest.sln to generate a 64-bit library.

Load the supplied Visual Studio solution file, msvc\gtest.sln. Go through the migration wizard to migrate the solution and project files to Visual Studio 2013. Select Configuration Manager... from the Build menu. Select <New...> from the Active solution platform dropdown. Select x64 from the new platform dropdown, leave Copy settings from set to Win32 and Create new project platforms checked, then click OK. You now have Win32 and x64 platform configurations, selectable from the Standard toolbar, which allow you to toggle between building 32-bit or 64-bit binaries (or both at once using Batch Build).

In order to prevent build output files from overwriting one another, you'll need to change the Intermediate Directory settings for the newly created platform configuration across all the projects. To do this, multi-select (e.g. using shift-click) all projects (but not the solution) in the Solution Explorer. Right-click one of them and select Properties. In the left pane, select Configuration Properties, and from the Configuration dropdown, select All Configurations. Make sure the selected platform is x64. For the Intermediate Directory setting, change the value from $(PlatformName)\$(ConfigurationName) to $(OutDir)\$(ProjectName). Click OK and then build the solution. When the build is complete, the 64-bit binaries will be in the msvc\x64\Debug directory.

- Taken from the googletest FAQ (with minor corrections).

Repeat step 3.4 above to build both Win32 and x64 Release and Debug builds.

Other Command Line Options

In addition to the command line options supported by googletest the amp_algorithms.exe also supports the following options:

-d [d]
--device [d]
Run tests on a selected device. Where d is:
gpu – The default hardware accelerator or exit if none is available
ref – The direct3d\ref reference accelerator
warp – The direct3d\warp Direct3D software WARP accelerator
1-N – The device
-q
--quiet
Minimal output showing only the build configuration and test output.
-v
--verbose
Verbose output showing properties for all C++ AMP devices. The device being used for running tests is denoted with a `*`.

Using the Library

The C++ AMP Algorithms Library is entirely template based, so using it is very straightforward. Add the inc folder to your project’s include directories (in the Configuration Properties | VC++ Directories | Include Directories tab of the Project Properties Dialog). Now include the library headers and use the namespaces:

#include <amp_algorithms.h>
#include <amp_stl_algorithms.h>

using namespace amp_algorithms;
using namespace amp_stl_algorithms;

The following example shows code that creates an array on the GPU, fills it with ascending values, removes all the odd values and calculates the total of the remaining values.

array<float> data(1024 * 1024);
array_view<float, 1> data_av(data);

amp_stl_algorithms::iota(begin(data_av), end(data_av), 1.0f);
auto last = amp_stl_algorithms::remove_if(begin(data_av), end(data_av),
    [=](const float& v) restrict(amp) { return int(v) % 2 == 1; });
float total = amp_stl_algorithms::accumulate(begin(data_av), last, 0.0f);

Compare this to the equivalent code written using STL and running on the CPU:

std::vector<float> data(1024 * 1024);

std::iota(std::begin(data), std::end(data), 1.0f);
auto last = std::remove_if(std::begin(data), std::end(data),
    [=](const float& v) { return int(v) % 2 == 1; });
float total = std::accumulate(begin(data), last, 0.0f);

This is the simplest “Hello World” example of using the Algorithms Library. Future documentation will cover more features of the Library. You can also look at the unit tests to see examples of using individual library features.

Last edited Dec 25, 2014 at 3:43 PM by AdeMiller, version 24

Comments

No comments yet.