Skip to content

Commit 0c1aa9e

Browse files
kblaschkekblaschke
committed
Add expression variable watch public API functions and data types
1 parent f67dac9 commit 0c1aa9e

1 file changed

Lines changed: 114 additions & 2 deletions

File tree

‎src/api/include/projectM-4/debug.h‎

Lines changed: 114 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ extern "C" {
3636
* @brief Writes a .bmp main texture dump after rendering the next main texture, before shaders are applied.
3737
*
3838
* If no file name is given, the image is written to the current working directory
39-
* and will be named named "frame_texture_contents-YYYY-mm-dd-HH:MM:SS-frame.bmp".
39+
* and will be named "frame_texture_contents-YYYY-mm-dd-HH:MM:SS-frame.bmp".
4040
*
4141
* Note this is the main texture contents, not the final rendering result. If the active preset
4242
* uses a composite shader, the dumped image will not have it applied. The main texture is what is
@@ -50,7 +50,119 @@ extern "C" {
5050
* @param output_file The filename to write the dump to or NULL.
5151
* @since 4.0.0
5252
*/
53-
PROJECTM_EXPORT void projectm_write_debug_image_on_next_frame(projectm_handle instance, const char* output_file);
53+
PROJECTM_EXPORT void projectm_write_debug_image_on_next_frame(projectm_handle instance,
54+
const char* output_file);
55+
56+
/**
57+
* @brief Structure containing the values of a single expression variable.
58+
*
59+
* This struct is used to return the values of a single, monitored expression variable. Depending
60+
* on how often a certain code block is being executed, this struct will contain one or more values.
61+
* For example, per_frame variables will only have one entry, while variables in custom waveform
62+
* per_point expressions will have as many entries as there were points rendered in the last frame.
63+
*
64+
* For user sprites, @a index is the sprite slot returned by @a projectm_sprite_create().
65+
*
66+
* If a code block wasn't executed at all, e.g. if a preset doesn't use a certain effect, the count
67+
* will be zero and the values array a NULL pointer.
68+
*
69+
* The application must not change the contents of the returned structure, as it is considered
70+
* read-only.
71+
*
72+
* @note There is no last NULL element in the values array. Use value_count to iterate over the
73+
* correct number of values!
74+
* @since 4.2.0
75+
*/
76+
struct projectm_expression_variable_values {
77+
uint32_t value_count; //!< The number of entries in @a values.
78+
uint32_t index; //!< The custom shape/waveform or user sprite index. 0 for any other block.
79+
double** values; //!< An array of double pointers, containing the values of the expression values as they were set to at the end of the last rendered frame.
80+
};
81+
82+
/**
83+
* @brief Available expression blocks for watches.
84+
*
85+
* Currently, the five code blocks executed per frame are available for watching, plus the Milkdrop
86+
* user sprite per_frame code.
87+
*
88+
* Init blocks cannot be watched, as they are only executed once whenever a preset is loaded, and use
89+
* the same variables as their respective per_frame counterparts.
90+
*
91+
* @since 4.2.0
92+
*/
93+
typedef enum
94+
{
95+
PROJECTM_EXPR_PER_FRAME, //!< Variables in the "per_frame_" code block
96+
PROJECTM_EXPR_PER_POINT, //!< Variables in the "per_point_" (AKA per vertex) code block
97+
PROJECTM_EXPR_SHAPE_PER_FRAME, //!< Variables in
98+
PROJECTM_EXPR_WAVE_PER_FRAME,
99+
PROJECTM_EXPR_WAVE_PER_POINT,
100+
PROJECTM_EXPR_MILKDROP_SPRITE
101+
} projectm_expression_blocks;
102+
103+
/**
104+
* @brief Adds a new variable watch and returns a pointer to the data holder structure.
105+
*
106+
* This function will add a new watch for a single variable in the specified code block. If the code
107+
* block was valid, a pointer to a @a projectm_expression_variable_values will be returned. This
108+
* pointer will stay valid until this specific or all watches are removed, or the watched projectM
109+
* instance is being destroyed.
110+
*
111+
* Only the "active" preset is being watched. During a transition, the newly loaded preset is not
112+
* the active one - it will become active once the transition is finished and the previous preset
113+
* was unloaded. Hard cuts will change the active preset immediately.
114+
*
115+
* Variables which are not used/defined by a preset will always return 0.0. The value count will
116+
* still match the number of block invocations.
117+
*
118+
* User sprites will be watched based on their slot index, as returned by @a projectm_sprite_create().
119+
*
120+
* Adding watches only have a very small performance impact, with most of the work being done on
121+
* preset load. During runtime, the overhead basically consists of copying the watched double values
122+
* from the expression context into the watch structure.
123+
*
124+
* @note The returned structure is owned by projectM. Do not free the structure externally!
125+
* @param instance The projectM instance handle.
126+
* @param block The code block to add the watch for.
127+
* @param index The custom shape/waveform or user sprite index. Ignored for other block types.
128+
* @param variable_name The name of the variable to watch.
129+
* @return A pointer to a @a projectm_expression_variable_values structure which will contain the
130+
* variable data, or NULL if the watch could not be added.
131+
* @since 4.2.0
132+
*/
133+
PROJECTM_EXPORT const projectm_expression_variable_values* projectm_expression_watch_add(projectm_handle instance,
134+
projectm_expression_blocks block,
135+
uint32_t index,
136+
const char* variable_name);
137+
138+
/**
139+
* @brief Removes a previously added variable watch.
140+
*
141+
* @note The returned structure pointer will be invalid after calling this function, and is only
142+
* supplied to match it to a stored value within the application for easier removal.
143+
* @param instance The projectM instance handle.
144+
* @param block The code block to remove the watch from.
145+
* @param index The custom shape/waveform or user sprite index. Ignored for other block types.
146+
* @param variable_name The name of the variable to remove the watch for.
147+
* @return The pointer to the previously registered @a projectm_expression_variable_values structure,
148+
* if the watch was found, or NULL if the watch could not be found and wasn't removed.
149+
* @since 4.2.0
150+
*/
151+
PROJECTM_EXPORT const projectm_expression_variable_values* projectm_expression_watch_remove(projectm_handle instance,
152+
projectm_expression_blocks block,
153+
uint32_t index,
154+
const char* variable_name);
155+
156+
/**
157+
* @brief Removes all active variable watches from this projectM instance.
158+
*
159+
* All previously returned pointers to @a projectm_expression_variable_values will no longer be valid
160+
* and thus must not be used/dereferenced after calling this function.
161+
*
162+
* @param instance The projectM instance handle.
163+
* @since 4.2.0
164+
*/
165+
PROJECTM_EXPORT void projectm_expression_watch_remove_all(projectm_handle instance);
54166

55167
#ifdef __cplusplus
56168
} // extern "C"

0 commit comments

Comments
 (0)