Doc cleanup

Documentation/sources/Reference/ofxParameter.rst

@@ -55,6 +55,21 @@ outside of a describe action will be a working instance of a parameter,
 you can still set (some) properties of the parameter, and all the
 get/set value functions are now usable.
 
+Getting and Setting Parameter Values
+------------------------------------
+
+During rendering and interactions, a plugin gets its param values via
+:cpp:func:`OfxParameterSuiteV1::paramGetValue` or
+:cpp:func:`OfxParameterSuiteV1::paramGetValueAtTime`.
+
+To set param values, a plugin can use
+:cpp:func:`OfxParameterSuiteV1::paramSetValue` or
+:cpp:func:`OfxParameterSuiteV1::paramSetValueAtTime`.
+
+In addition, :cpp:struct:`OfxParameterSuiteV1` has functions for
+manipulating keyframes, copying and editing params, getting their
+properties, and getting derivatives and integrals of param values.
+
 .. _parameterTypes:
 
 Parameter Types

include/ofxCore.h

@@ -47,9 +47,9 @@ typedef struct OfxHost {
 
   /** @brief The function which the plug-in uses to fetch suites from the host.
 
-      \arg \e host          - the host the suite is being fetched from this \em must be the \e host member of the OfxHost struct containing fetchSuite.
-      \arg \e suiteName     - ASCII string labelling the host supplied API
-      \arg \e suiteVersion  - version of that suite to fetch
+      \arg \c host          the host the suite is being fetched from this \em must be the \e host member of the OfxHost struct containing fetchSuite.
+      \arg \c suiteName     ASCII string labelling the host supplied API
+      \arg \c suiteVersion  version of that suite to fetch
 
       Any API fetched will be valid while the binary containing the plug-in is loaded.
 
@@ -65,10 +65,10 @@ typedef struct OfxHost {
 
 /** @brief Entry point for plug-ins
 
-  \arg \e action   - ASCII c string indicating which action to take
-  \arg \e instance - object to which action should be applied, this will need to be cast to the appropriate blind data type depending on the \e action
-  \arg \e inData   - handle that contains action specific properties
-  \arg \e outData  - handle where the plug-in should set various action specific properties
+  \arg \c action   ASCII c string indicating which action to take
+  \arg \c instance object to which action should be applied, this will need to be cast to the appropriate blind data type depending on the \e action
+  \arg \c inData   handle that contains action specific properties
+  \arg \c outData  handle where the plug-in should set various action specific properties
 
   This is how the host generally communicates with a plug-in. Entry points are used to pass messages
   to various objects used within OFX. The main use is within the OfxPlugin struct.
@@ -115,7 +115,7 @@ typedef struct OfxPlugin {
 
   /** @brief Function the host uses to connect the plug-in to the host's api fetcher
 
-      \arg \e fetchApi - pointer to host's API fetcher
+      \arg \c fetchApi pointer to host's API fetcher
 
       Mandatory function.
 

include/ofxDialog.h

@@ -32,7 +32,7 @@ actions needed. (Like lowering its priority etc..)
 
 /** @brief Action called after a dialog has requested a 'Dialog'
          The arguments to the action are:
-          \arg user_data - Pointer which was provided when the plugin requested the Dialog
+          \arg \c user_data Pointer which was provided when the plugin requested the Dialog
 
 	   When the plugin receives this action it is safe to popup a dialog.
 	   It runs in the host's UI thread, which may differ from the main OFX processing thread.

include/ofxDrawSuite.h

@@ -84,9 +84,9 @@ typedef enum OfxDrawTextAlignment
 typedef struct OfxDrawSuiteV1 {
 	/** @brief Retrieves the host's desired draw colour for
 
-	 \arg context  - the draw context
-	 \arg std_colour - the desired colour type
-	 \arg colour      - the returned RGBA colour
+	 \arg \c context  draw context
+	 \arg \c std_colour desired colour type
+	 \arg \c colour      returned RGBA colour
 
 	 @returns
 	 - ::kOfxStatOK - the colour was returned
@@ -97,8 +97,8 @@ typedef struct OfxDrawSuiteV1 {
 
 	/** @brief Sets the colour for future drawing operations (lines, filled shapes and text)
 
-	 \arg context  - the draw context
-	 \arg colour      - the RGBA colour
+	 \arg \c context  draw context
+	 \arg \c colour      RGBA colour
 
 	 The host should use "over" compositing when using a non-opaque colour.
 
@@ -110,8 +110,8 @@ typedef struct OfxDrawSuiteV1 {
 
 	/** @brief Sets the line width for future line drawing operations
 
-	 \arg context  - the draw context
-	 \arg width     - the line width
+	 \arg \c context  draw context
+	 \arg \c width     line width
 
 	 Use width 0 for a single pixel line or non-zero for a smooth line of the desired width
 
@@ -125,8 +125,8 @@ typedef struct OfxDrawSuiteV1 {
 
 	/** @brief Sets the stipple pattern for future line drawing operations
 
-	 \arg context  - the draw context
-	 \arg pattern  - the desired stipple pattern
+	 \arg \c context  draw context
+	 \arg \c pattern  desired stipple pattern
 
 	 @returns
 	 - ::kOfxStatOK - the pattern was changed
@@ -137,10 +137,10 @@ typedef struct OfxDrawSuiteV1 {
 
 	/** @brief Draws a primitive of the desired type
 
-	 \arg context  - the draw context
-	 \arg primitive  - the desired primitive
-	 \arg points  - the array of points in the primitive
-	 \arg point_count  - the number of points in the array
+	 \arg \c context  draw context
+	 \arg \c primitive  desired primitive
+	 \arg \c points  array of points in the primitive
+	 \arg \c point_count  number of points in the array
 
 	 kOfxDrawPrimitiveLines - like GL_LINES, n points draws n/2 separated lines
 	 kOfxDrawPrimitiveLineStrip - like GL_LINE_STRIP, n points draws n-1 connected lines
@@ -159,10 +159,10 @@ typedef struct OfxDrawSuiteV1 {
 
 	/** @brief Draws text at the specified position
 
-	 \arg context  - the draw context
-	 \arg text  - the text to draw (UTF-8 encoded)
-	 \arg pos  - the position at which to align the text
-	 \arg alignment  - the text alignment flags (see kOfxDrawTextAlignment*)
+	 \arg \c context  draw context
+	 \arg \c text  text to draw (UTF-8 encoded)
+	 \arg \c pos  position at which to align the text
+	 \arg \c alignment  text alignment flags (see kOfxDrawTextAlignment*)
 
 	 The text font face and size are determined by the host.
 

include/ofxGPURender.h

@@ -206,16 +206,16 @@ typedef struct OfxImageEffectOpenGLRenderSuiteV1
 {
   /** @brief loads an image from an OFX clip as a texture into OpenGL
 
-      \arg clip   - the clip to load the image from
-      \arg time   - effect time to load the image from
-      \arg format - the requested texture format (As in
+      \arg \c clip   clip to load the image from
+      \arg \c time   effect time to load the image from
+      \arg \c format requested texture format (As in
             none,byte,word,half,float, etc..)
             When set to NULL, the host decides the format based on the
 	    plug-in's ::kOfxOpenGLPropPixelDepth setting.
-      \arg region - region of the image to load (optional, set to NULL to
+      \arg \c region region of the image to load (optional, set to NULL to
             get a 'default' region)
 	    this is in the \ref CanonicalCoordinates.
-      \arg textureHandle - a property set containing information about the
+      \arg \c textureHandle property set containing information about the
             texture
 
   An image is fetched from a clip at the indicated time for the given region
@@ -352,10 +352,10 @@ plugin swap OpenGL contexts by issuing a attach/detach for the first context
 then another attach for the next context.
 
 The arguments to the action are...
-  \arg handle - handle to the plug-in instance, cast to an
+  \arg \c handle handle to the plug-in instance, cast to an
   \ref OfxImageEffectHandle
-  \arg inArgs - is redundant and set to null
-  \arg outArgs - is redundant and set to null
+  \arg \c inArgs is redundant and set to NULL
+  \arg \c outArgs is redundant and set to NULL
 
 A plugin can return...
   - ::kOfxStatOK, the action was trapped and all was well
@@ -378,10 +378,10 @@ The host must call this with the same OpenGL context active as it
 called with the corresponding ::kOfxActionOpenGLContextAttached.
 
 The arguments to the action are...
-  \arg handle - handle to the plug-in instance, cast to an
+  \arg \c handle handle to the plug-in instance, cast to an
   \ref OfxImageEffectHandle
-  \arg inArgs - is redundant and set to null
-  \arg outArgs - is redundant and set to null
+  \arg \c inArgs is redundant and set to NULL
+  \arg \c outArgs is redundant and set to NULL
 
 A plugin can return...
   - ::kOfxStatOK, the action was trapped and all was well

include/ofxImageEffect.h

@@ -1436,8 +1436,8 @@ This suite provides the functions needed by a plugin to defined and use an image
 typedef struct OfxImageEffectSuiteV1 {  
   /** @brief Retrieves the property set for the given image effect
 
-  \arg imageEffect   image effect to get the property set for
-  \arg propHandle    pointer to a the property set pointer, value is returned here
+  \arg \c imageEffect   image effect to get the property set for
+  \arg \c propHandle    pointer to a the property set pointer, value is returned here
 
   The property handle is for the duration of the image effect handle.
 
@@ -1451,8 +1451,8 @@ typedef struct OfxImageEffectSuiteV1 {
 
   /** @brief Retrieves the parameter set for the given image effect
 
-  \arg imageEffect   image effect to get the property set for
-  \arg paramSet     pointer to a the parameter set, value is returned here
+  \arg \c imageEffect   image effect to get the property set for
+  \arg \c paramSet     pointer to a the parameter set, value is returned here
 
   The param set handle is valid for the lifetime of the image effect handle.
 
@@ -1467,9 +1467,9 @@ typedef struct OfxImageEffectSuiteV1 {
 
   /** @brief Define a clip to the effect. 
 
-   \arg pluginHandle - the handle passed into 'describeInContext' action
-   \arg name - unique name of the clip to define
-   \arg propertySet - a property handle for the clip descriptor will be returned here
+   \arg \c pluginHandle handle passed into 'describeInContext' action
+   \arg \c name unique name of the clip to define
+   \arg \c propertySet property handle for the clip descriptor will be returned here
 
    This function defines a clip to a host, the returned property set is used to describe
    various aspects of the clip to the host. Note that this does not create a clip instance.
@@ -1485,10 +1485,10 @@ typedef struct OfxImageEffectSuiteV1 {
 
   /** @brief Get the propery handle of the named input clip in the given instance 
 
-   \arg imageEffect - an instance handle to the plugin
-   \arg name        - name of the clip, previously used in a clip define call
-   \arg clip        - where to return the clip
-  \arg propertySet  if not null, the descriptor handle for a parameter's property set will be placed here.
+   \arg \c imageEffect an instance handle to the plugin
+   \arg \c name        name of the clip, previously used in a clip define call
+   \arg \c clip        where to return the clip
+  \arg \c propertySet  if not NULL, the descriptor handle for a parameter's property set will be placed here.
 
   The propertySet will have the same value as would be returned by OfxImageEffectSuiteV1::clipGetPropertySet
 
@@ -1514,8 +1514,8 @@ typedef struct OfxImageEffectSuiteV1 {
 
   /** @brief Retrieves the property set for a given clip
 
-  \arg clip          clip effect to get the property set for
-  \arg propHandle    pointer to a the property set handle, value is returedn her
+  \arg \c clip         clip effect to get the property set for
+  \arg \c propHandle   pointer to a the property set handle, value is returedn her
 
   The property handle is valid for the lifetime of the clip, which is generally the lifetime of the instance.
 
@@ -1529,11 +1529,11 @@ typedef struct OfxImageEffectSuiteV1 {
 
   /** @brief Get a handle for an image in a clip at the indicated time and indicated region
 
-      \arg clip  - the clip to extract the image from
-      \arg time        - time to fetch the image at
-      \arg region      - region to fetch the image from (optional, set to NULL to get a 'default' region)
+      \arg \c clip  clip to extract the image from
+      \arg \c time        time to fetch the image at
+      \arg \c region      region to fetch the image from (optional, set to NULL to get a 'default' region)
                             this is in the \ref CanonicalCoordinates. 
-      \arg imageHandle - property set containing the image's data
+      \arg \c imageHandle property set containing the image's data
 
   An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.
 
@@ -1579,11 +1579,11 @@ If clipGetImage is called twice with the same parameters, then two separate imag
 
   /** @brief Returns the spatial region of definition of the clip at the given time
 
-      \arg clipHandle  - the clip to extract the image from
-      \arg time        - time to fetch the image at
-      \arg region      - region to fetch the image from (optional, set to NULL to get a 'default' region)
+      \arg \c clipHandle  clip to extract the image from
+      \arg \c time        time to fetch the image at
+      \arg \c region      region to fetch the image from (optional, set to NULL to get a 'default' region)
                             this is in the \ref CanonicalCoordinates. 
-      \arg imageHandle - handle where the image is returned
+      \arg \c imageHandle handle where the image is returned
 
   An image is fetched from a clip at the indicated time for the given region and returned in the imageHandle.
 
@@ -1610,7 +1610,7 @@ If clipGetImage is called twice with the same parameters, then two separate imag
 
   /** @brief Returns whether to abort processing or not.
 
-      \arg imageEffect  - instance of the image effect
+      \arg \c imageEffect  instance of the image effect
 
   A host may want to signal to a plugin that it should stop whatever rendering it is doing and start again. 
   Generally this is done in interactive threads in response to users tweaking some parameter.
@@ -1625,9 +1625,9 @@ If clipGetImage is called twice with the same parameters, then two separate imag
 
   /** @brief Allocate memory from the host's image memory pool
 
-  \arg instanceHandle  - effect instance to associate with this memory allocation, may be NULL.
-  \arg nBytes          - the number of bytes to allocate
-  \arg memoryHandle    - pointer to the memory handle where a return value is placed
+  \arg \c instanceHandle  effect instance to associate with this memory allocation, may be NULL.
+  \arg \c nBytes          number of bytes to allocate
+  \arg \c memoryHandle    pointer to the memory handle where a return value is placed
 
   Memory handles allocated by this should be freed by OfxImageEffectSuiteV1::imageMemoryFree. 
   To access the memory behind the handle you need to call  OfxImageEffectSuiteV1::imageMemoryLock.
@@ -1645,7 +1645,7 @@ If clipGetImage is called twice with the same parameters, then two separate imag
 
   /** @brief Frees a memory handle and associated memory.
 
-  \arg memoryHandle - memory handle returned by imageMemoryAlloc
+  \arg \c memoryHandle memory handle returned by imageMemoryAlloc
 
   This function frees a memory handle and associated memory that was previously allocated via OfxImageEffectSuiteV1::imageMemoryAlloc
 
@@ -1661,8 +1661,8 @@ If clipGetImage is called twice with the same parameters, then two separate imag
 
   /** @brief Lock the memory associated with a memory handle and make it available for use.
 
-  \arg memoryHandle - memory handle returned by imageMemoryAlloc
-  \arg returnedPtr - where to the pointer to the locked memory
+  \arg \c memoryHandle memory handle returned by imageMemoryAlloc
+  \arg \c returnedPtr where to the pointer to the locked memory
 
   This function locks them memory associated with a memory handle and returns a pointer to it. The memory will be 16 byte aligned, to allow use of vector operations.
 
@@ -1684,7 +1684,7 @@ If clipGetImage is called twice with the same parameters, then two separate imag
 
   /** @brief Unlock allocated image data
 
-  \arg allocatedData - pointer to memory previously returned by OfxImageEffectSuiteV1::imageAlloc
+  \arg \c allocatedData pointer to memory previously returned by OfxImageEffectSuiteV1::imageAlloc
 
   This function unlocks a previously locked memory handle. Once completely unlocked, memory associated with a memoryHandle is no longer available for use. Attempting to use it results in undefined behaviour.
 

include/ofxMemory.h

@@ -22,9 +22,9 @@ For images, you should use the memory allocation functions in the image effect s
 typedef struct OfxMemorySuiteV1 {
   /** @brief Allocate memory.
 
-  \arg handle	- effect instance to assosciate with this memory allocation, or NULL.
-  \arg nBytes        - the number of bytes to allocate
-  \arg allocatedData - a pointer to the return value. Allocated memory will be alligned for any use.
+  \arg \c handle	- effect instance to assosciate with this memory allocation, or NULL.
+  \arg \c nBytes        number of bytes to allocate
+  \arg \c allocatedData pointer to the return value. Allocated memory will be alligned for any use.
 
   This function has the host allocate memory using its own memory resources
   and returns that to the plugin.
@@ -40,7 +40,7 @@ typedef struct OfxMemorySuiteV1 {
 
   /** @brief Frees memory.
 
-  \arg allocatedData - pointer to memory previously returned by OfxMemorySuiteV1::memoryAlloc
+  \arg \c allocatedData pointer to memory previously returned by OfxMemorySuiteV1::memoryAlloc
 
   This function frees any memory that was previously allocated via OfxMemorySuiteV1::memoryAlloc.