Added Apoorv Upreti's GSoC2013 work: visual test suite.

See visualtest/README.txt for details.

visualtest/include/SDL_visualtest_variator_common.h

@@ -0,0 +1,120 @@
+/* See COPYING.txt for the full license governing this code. */
+/**
+ * \file SDL_visualtest_variator_common.h
+ *
+ * Header for common functionality used by variators.
+ */
+
+#include <SDL_types.h>
+#include "SDL_visualtest_sut_configparser.h"
+
+#ifndef _SDL_visualtest_variator_common_h
+#define _SDL_visualtest_variator_common_h
+
+/** The number of variations one integer option would generate */
+#define SDL_SUT_INTEGER_OPTION_TEST_STEPS 3
+
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** enum for indicating the type of variator being used */
+typedef enum SDLVisualTest_VariatorType
+{
+    SDL_VARIATOR_NONE = 0,
+    SDL_VARIATOR_EXHAUSTIVE,
+    SDL_VARIATOR_RANDOM
+} SDLVisualTest_VariatorType;
+
+/**
+ * One possible value for a command line option to the SUT.
+ */
+typedef union SDLVisualTest_SUTOptionValue
+{
+    /*! Value if the option is of type boolean */
+    SDL_bool bool_value;
+    /*! Value if the option is of type integer. If on is true then the option
+        will be passed to the SUT, otherwise it will be ignored. */
+    struct {
+        int value;
+        SDL_bool on;
+    } integer;
+    /*! Index of the string in the enum_values field of the corresponding
+        SDLVisualTest_SUTOption object. If on is true the option will passed
+        to the SUT, otherwise it will be ignored. */
+    struct {
+        int index;
+        SDL_bool on;
+    } enumerated;
+    /*! Value if the option is of type string. If on is true the option will 
+        be passed to the SUT, otherwise it will be ignored. */
+    struct {
+        char* value;
+        SDL_bool on;
+    } string;
+} SDLVisualTest_SUTOptionValue;
+
+/**
+ * Represents a valid combination of parameters that can be passed to the SUT.
+ * The ordering of the values here is the same as the ordering of the options in
+ * the SDLVisualTest_SUTConfig object for this variation.
+ */
+typedef struct SDLVisualTest_Variation
+{
+    /*! Pointer to array of option values */
+    SDLVisualTest_SUTOptionValue* vars;
+    /*! Number of option values in \c vars */
+    int num_vars;
+} SDLVisualTest_Variation;
+
+/**
+ * "Increments" the value of the option by one and returns the carry. We wrap
+ * around to the initial value on overflow which makes the carry one.
+ * For example: "incrementing" an SDL_FALSE option makes it SDL_TRUE with no
+ * carry, and "incrementing" an SDL_TRUE option makes it SDL_FALSE with carry
+ * one. For integers, a random value in the valid range for the option is used.
+ *
+ * \param var Value of the option
+ * \param opt Object with metadata about the option
+ *
+ * \return 1 if there is a carry for enum and bool type options, 0 otherwise.
+ *         1 is always returned for integer and string type options. -1 is
+ *         returned on error.
+ */
+int SDLVisualTest_NextValue(SDLVisualTest_SUTOptionValue* var,
+                            SDLVisualTest_SUTOption* opt);
+
+/**
+ * Converts a variation object into a string of command line arguments.
+ *
+ * \param variation Variation object to be converted.
+ * \param config Config object for the SUT.
+ * \param buffer Pointer to the buffer the arguments string will be copied into.
+ * \param size Size of the buffer.
+ *
+ * \return 1 on success, 0 on failure
+ */
+int SDLVisualTest_MakeStrFromVariation(SDLVisualTest_Variation* variation,
+                                       SDLVisualTest_SUTConfig* config,
+                                       char* buffer, int size);
+
+/**
+ * Initializes the variation using the following rules:
+ * - Boolean options are initialized to SDL_FALSE.
+ * - Integer options are initialized to the minimum valid value they can hold.
+ * - Enum options are initialized to the first element in the list of values they
+ *   can take.
+ * - String options are initialized to the name of the option.
+ *
+ * \return 1 on success, 0 on failure.
+ */
+int SDLVisualTest_InitVariation(SDLVisualTest_Variation* variation,
+                                SDLVisualTest_SUTConfig* config);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _SDL_visualtest_variator_common_h */