Fri, 19 Jul, 2024 11:39:59

Author: tuorqai

LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 tuorqai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

secamiz0r.c

@@ -1,8 +1,115 @@
+/**
+ * Copyright (c) 2023 tuorqai
+ * 
+ * This software is provided 'as-is', without any express or implied
+ * warranty. In no event will the authors be held liable for any damages
+ * arising from the use of this software.
+ * 
+ * Permission is granted to anyone to use this software for any purpose,
+ * including commercial applications, and to alter it and redistribute it
+ * freely, subject to the following restrictions:
+ * 
+ * 1. The origin of this software must not be misrepresented; you must not
+ *    claim that you wrote the original software. If you use this software
+ *    in a product, an acknowledgment in the product documentation would be
+ *    appreciated but is not required.
+ * 2. Altered source versions must be plainly marked as such, and must not be
+ *    misrepresented as being the original software.
+ * 3. This notice may not be removed or altered from any source distribution.
+ */
+
+/**
+ * secamiz0r.c: SECAM fire frei0r plugin.
+ */
 
 #include <math.h>
 #include <stdlib.h>
 #include "frei0r.h"
 
+/**
+ * Limit integer value to the range.
+ */
+static int clamp_int(int value, int a, int b)
+{
+    return (value < a) ? a : ((value > b) ? b : value);
+}
+
+/**
+ * Limit value to the 8-bit range.
+ */
+static uint8_t clamp_byte(int value)
+{
+    return (uint8_t) clamp_int(value, 0, 255);
+}
+
+/**
+ * Convert 24-bit RGB value to array of floating-point values.
+ */
+static void unpack_rgb(float *rgb, uint8_t const *src)
+{
+    rgb[0] = ((float) src[0]) / 255.f;
+    rgb[1] = ((float) src[1]) / 255.f;
+    rgb[2] = ((float) src[2]) / 255.f;
+}
+
+/**
+ * Calculate 8-bit luminance value from floating-point RGB value.
+ */
+static uint8_t y_from_rgb(float const *rgb)
+{
+    return (uint8_t) (16.0 + (65.7380 * rgb[0]) + (129.057 * rgb[1]) + (25.0640 * rgb[2]));
+}
+
+/**
+ * Calculate 8-bit B-Y value from floating-point RGB value.
+ */
+static uint8_t u_from_rgb(float const *rgb)
+{
+    return (uint8_t) (128.0 - (37.9450 * rgb[0]) - (74.4940 * rgb[1]) + (112.439 * rgb[2]));
+}
+
+/**
+ * Calculate 8-bit R-Y value from floating-point RGB value.
+ */
+static uint8_t v_from_rgb(float const *rgb)
+{
+    return (uint8_t) (128.0 + (112.439 * rgb[0]) - (94.1540 * rgb[1]) - (18.2850 * rgb[2]));
+}
+
+/**
+ * Convert floating-point YUV value to 24-bit RGB.
+ */
+static void rgb_from_yuv(uint8_t *dst, float y, float u, float v)
+{
+    dst[0] = clamp_byte((int) ((298.082 * y) + (408.583 * v) - 222.921));
+    dst[1] = clamp_byte((int) ((298.082 * y) - (100.291 * u) - (208.120 * v) + 135.576));
+    dst[2] = clamp_byte((int) ((298.082 * y) + (516.412 * u) - 276.836));
+}
+
+/**
+ * Unsigned modulo.
+ */
+static unsigned int umod(int a, int b)
+{
+    return ((a % b) + b) % b;
+}
+
+/**
+ * Do I have any idea what this does?
+ * Make random integer out of random integer.
+ */
+static int juice(int j)
+{
+    j ^= j << 13;
+    j ^= j >> 17;
+    j ^= j << 5;
+
+    return j;
+}
+
+/**
+ * secamiz0r instance struct.
+ */
 struct secamiz0r
 {
     unsigned int width;
@@ -19,28 +126,64 @@ struct secamiz0r
     int echo_offset;
 };
 
+/**
+ * Some values are dependent on "fire intensity" parameter.
+ */
+static void set_fire_intensity(struct secamiz0r *self, double fire_intensity)
+{
+    double const x = self->fire_intensity = fire_intensity;
+
+    self->fire_threshold = 1024 - (int) (x * x * 256.0);
+    self->fire_seed = (int) (x * 1024.0);
+}
+
+/**
+* Some values are dependent on "noise intensity" parameter.
+*/
+static void set_noise_intensity(struct secamiz0r *self, double noise_intensity)
+{
+    double const x = self->noise_intensity = noise_intensity;
+
+    self->luma_noise = clamp_int((int) (x * x * 256.0), 16, 224);
+    self->chroma_noise = clamp_int((int) (x * 256.0), 32, 256);
+    self->echo_offset = clamp_int((int) (x * 8.0), 2, 16);
+}
+
+/**
+ * frei0r plugin entry point: seems to be deprecated.
+ */
 int f0r_init()
 {
-	return 1;
+    return 1;
 }
 
+/**
+ * Same as f0r_init(), no signs of usage.
+ */
 void f0r_deinit()
 {
 }
 
+/**
+ * Expose some metadata.
+ */
 void f0r_get_plugin_info(f0r_plugin_info_t *info)
 {
     info->name = "secamiz0r";
     info->author = "tuorqai";
     info->plugin_type = F0R_PLUGIN_TYPE_FILTER;
     info->color_model = F0R_COLOR_MODEL_RGBA8888;
     info->frei0r_version = FREI0R_MAJOR_VERSION;
-    info->major_version = 1;
+    info->major_version = 2;
     info->minor_version = 0;
     info->num_params = 2;
     info->explanation = "SECAM Fire effect";
 }
 
+/**
+ * Expose parameter metadata.
+ * Note: kdenlive uses .name field to refer to these.
+ */
 void f0r_get_param_info(f0r_param_info_t *info, int index)
 {
     switch (index) {
@@ -59,28 +202,9 @@ void f0r_get_param_info(f0r_param_info_t *info, int index)
     }
 }
 
-static int clamp_int(int value, int a, int b)
-{
-    return (value < a) ? a : ((value > b) ? b : value);
-}
-
-static void set_fire_intensity(struct secamiz0r *self, double fire_intensity)
-{
-    double const x = self->fire_intensity = fire_intensity;
-
-    self->fire_threshold = 1024 - (int) (x * x * 256.0);
-    self->fire_seed = (int) (x * 1024.0);
-}
-
-static void set_noise_intensity(struct secamiz0r *self, double noise_intensity)
-{
-    double const x = self->noise_intensity = noise_intensity;
-
-    self->luma_noise = clamp_int((int) (x * x * 256.0), 16, 224);
-    self->chroma_noise = clamp_int((int) (x * 256.0), 32, 256);
-    self->echo_offset = clamp_int((int) (x * 8.0), 2, 16);
-}
-
+/**
+ * The actual entry point of a frei0r plugin.
+ */
 f0r_instance_t f0r_construct(unsigned int width, unsigned int height)
 {
     struct secamiz0r *self = malloc(sizeof(*self));
@@ -99,11 +223,17 @@ f0r_instance_t f0r_construct(unsigned int width, unsigned int height)
     return self;
 }
 
+/**
+ * Don't forget to turn off your TV.
+ */
 void f0r_destruct(f0r_instance_t instance)
 {
     free(instance);
 }
 
+/**
+ * Parameter value setter.
+ */
 void f0r_set_param_value(f0r_instance_t instance, f0r_param_t param, int index)
 {
     struct secamiz0r *self = instance;
@@ -120,6 +250,9 @@ void f0r_set_param_value(f0r_instance_t instance, f0r_param_t param, int index)
     }
 }
 
+/**
+ * Parameter value getter.
+ */
 void f0r_get_param_value(f0r_instance_t instance, f0r_param_t param, int index)
 {
     struct secamiz0r *self = instance;
@@ -136,40 +269,13 @@ void f0r_get_param_value(f0r_instance_t instance, f0r_param_t param, int index)
     }
 }
 
-static void unpack_rgb(float *rgb, uint8_t const *src)
-{
-    rgb[0] = ((float) src[0]) / 255.f;
-    rgb[1] = ((float) src[1]) / 255.f;
-    rgb[2] = ((float) src[2]) / 255.f;
-}
-
-static uint8_t y_from_rgb(float const *rgb)
-{
-    return (uint8_t) (16.0 + (65.7380 * rgb[0]) + (129.057 * rgb[1]) + (25.0640 * rgb[2]));
-}
-
-static uint8_t u_from_rgb(float const *rgb)
-{
-    return (uint8_t) (128.0 - (37.9450 * rgb[0]) - (74.4940 * rgb[1]) + (112.439 * rgb[2]));
-}
-
-static uint8_t v_from_rgb(float const *rgb)
-{
-    return (uint8_t) (128.0 + (112.439 * rgb[0]) - (94.1540 * rgb[1]) - (18.2850 * rgb[2]));
-}
-
-static uint8_t clamp_byte(int value)
-{
-    return (uint8_t) clamp_int(value, 0, 255);
-}
-
-static void rgb_from_yuv(uint8_t *dst, float y, float u, float v)
-{
-    dst[0] = clamp_byte((int) ((298.082 * y) + (408.583 * v) - 222.921));
-    dst[1] = clamp_byte((int) ((298.082 * y) - (100.291 * u) - (208.120 * v) + 135.576));
-    dst[2] = clamp_byte((int) ((298.082 * y) + (516.412 * u) - 276.836));
-}
-
+/**
+ * Filtering Stage 1. Copy two consecutive pixel rows from source buffer to the destination
+ * buffer, converting it to YUV on the fly.
+ * We need to do this, because this plugin aims not to allocate memory at all (with the
+ * exception of secamiz0r struct in f0r_construct()). So the only available storage for us
+ * is the destination buffer provided by frei0r itself.
+ */
 static void copy_pair_as_yuv(struct secamiz0r *self, uint8_t *dst_even, uint8_t *dst_odd, uint8_t const *src_even, uint8_t const *src_odd)
 {
     for (size_t i = 0; i < self->width; i += 2) {
@@ -224,20 +330,14 @@ static void copy_pair_as_yuv(struct secamiz0r *self, uint8_t *dst_even, uint8_t
     }
 }
 
-static int juice(int j)
-{
-    j ^= j << 13;
-    j ^= j >> 17;
-    j ^= j << 5;
-
-    return j;
-}
-
-static unsigned int umod(int a, int b)
-{
-    return ((a % b) + b) % b;
-}
-
+/**
+ * Filtering Stage 2.1. The loop inside this function works on two consecutive
+ * lines copied in Stage 1. It aims to detect areas where luminance level is
+ * changed rapidly, and then marks those areas. To achieve this, we keep summing
+ * up difference between two pixels, halving the sum every step (it kinda fades
+ * away). To make this more chaotic, we also add a random value. Then, if at
+ * some point the sum is larger than a threshold value, we mark this pixel.
+ */
 static void prefilter_pair(struct secamiz0r *self, uint8_t *even, uint8_t *odd)
 {
     int r_even = rand();
@@ -266,6 +366,10 @@ static void prefilter_pair(struct secamiz0r *self, uint8_t *even, uint8_t *odd)
     }
 }
 
+/**
+ * Filtering Stage 2.2. This actually modifies the image, adding random noise
+ * and fires at marked areas.
+ */
 static void filter_pair(struct secamiz0r *self, uint8_t *even, uint8_t *odd)
 {
     int r_even = rand();
@@ -339,6 +443,11 @@ static void filter_pair(struct secamiz0r *self, uint8_t *even, uint8_t *odd)
     }
 }
 
+/**
+ * Filtering Stage 3. Two consecutive YUV pixel rows, filtered in previous stages,
+ * now converted to RGB in place. But conversion isn't straightforward: to make
+ * the image look more analog, a sophisticated method is used.
+ */
 static void convert_pair_to_rgb(struct secamiz0r *self, uint8_t *even, uint8_t *odd)
 {
     int const luma_loss = 4;
@@ -372,6 +481,10 @@ static void convert_pair_to_rgb(struct secamiz0r *self, uint8_t *even, uint8_t *
     }
 }
 
+/**
+ * The whole process of filtering is done here.
+ * This function is called every frame.
+ */
 void f0r_update(f0r_instance_t instance, double time, uint32_t const* src, uint32_t *dst)
 {
     struct secamiz0r *self = instance;