Merge pull request #6 from BinaryNoggin/feature/documentation

Document types in Turbojpeg

Author: adkron

dialyzer.ignore-warnings.exs

@@ -0,0 +1,3 @@
+[
+  {"lib/turbojpeg/native.ex"}
+]

lib/turbojpeg.ex

@@ -1,3 +1,86 @@
 defmodule Turbojpeg do
   @moduledoc File.read!("README.md")
+  alias Turbojpeg.Native
+
+  @type width :: dimension
+  @type height :: dimension
+  @type dimension :: pos_integer()
+  @type quality :: 0..100
+  @type format ::
+          :I420
+          | :I422
+          | :I444
+          | :GRAY
+  @type error ::
+          {:error, atom()}
+          | {:error, struct}
+  @type jpeg_header :: %{
+          format: format(),
+          width: width(),
+          height: height()
+        }
+
+  @doc """
+  Converts yuv to jpeg images
+
+
+        iex> {:ok, jpeg} = Turbojpeg.yuv_to_jpeg(Shmex.new(frame), 1920, 1080, 90, :I420)
+          {:ok,
+            %Shmex{
+            capacity: 203783,
+            guard: #Reference<0.938325095.2990669827.232440>,
+            name: "/shmex-00000005607042890133#000",
+            size: 203783
+          }}
+  """
+  @spec yuv_to_jpeg(Shmex.t(), width, height, quality, format) ::
+          {:ok, Shmex.t()} | error()
+  def yuv_to_jpeg(yuv, width, height, quality, format) do
+    Native.yuv_to_jpeg(yuv, width, height, quality, format)
+  rescue
+    error ->
+      {:error, error}
+  end
+
+  @doc """
+  Converts jpeg to yuv
+
+
+        iex> {:ok, yuv} = Turbojpeg.jpeg_to_yuv(Shmex.new(jpeg))
+          {:ok,
+            %Shmex{
+            capacity: 203783,
+            guard: #Reference<0.938325095.2990669827.232440>,
+            name: "/shmex-00000005607042890133#000",
+            size: 203783
+          }}
+  """
+  @spec jpeg_to_yuv(Shmex.t()) ::
+          {:ok, Shmex.t()} | error()
+  def jpeg_to_yuv(jpeg) do
+    Native.jpeg_to_yuv(jpeg)
+  rescue
+    error ->
+      {:error, error}
+  end
+
+  @doc """
+  Gets the header from a jpegv
+
+       iex> {:ok, header} = Turbojpeg.get_jpeg_header(Shmex.new(jpeg))
+         {:ok,
+           %{
+              format: :I422,
+              width: 192,
+              height: 192
+            }
+         }
+  """
+  @spec get_jpeg_header(Shmex.t()) :: {:ok, jpeg_header} | error()
+  def get_jpeg_header(jpeg) do
+    Native.get_jpeg_header(jpeg)
+  rescue
+    error ->
+      {:error, error}
+  end
 end

lib/turbojpeg/sink.ex

@@ -1,5 +1,4 @@
 defmodule Turbojpeg.Sink do
-  alias Turbojpeg.Native
   use Membrane.Sink
   alias Membrane.{Buffer, Time}
   alias Membrane.Caps.Video.Raw
@@ -48,12 +47,12 @@ defmodule Turbojpeg.Sink do
   @impl true
   def handle_write(:input, %Buffer{payload: payload}, _ctx, state) do
     with {:ok, data} <-
-           Native.yuv_to_jpeg(payload, state.width, state.height, state.quality, state.format),
+           Turbojpeg.yuv_to_jpeg(payload, state.width, state.height, state.quality, state.format),
          :ok <- File.write(state.filename, Shmex.to_binary(data)) do
       {:ok, state}
     else
-      {:error, reason} ->
-        {{:error, reason}, state}
+      {:error, _} = error ->
+        {error, state}
     end
   end
 

mix.exs

@@ -16,7 +16,10 @@ defmodule Turbojpeg.MixProject do
       homepage_url: @github_link,
       package: package(),
       docs: docs(),
-      deps: deps()
+      deps: deps(),
+      dialyzer: [
+        ignore_warnings: "dialyzer.ignore-warnings.exs"
+      ]
     ]
   end
 
@@ -36,7 +39,8 @@ defmodule Turbojpeg.MixProject do
       {:membrane_core, "~> 0.5.0"},
       {:ex_doc, "~> 0.21.3", only: [:dev], runtime: false},
       {:propcheck, "~> 1.2.0", only: [:test]},
-      {:mogrify, github: "ConnorRigby/mogrify", branch: "master", only: [:test, :dev]}
+      {:mogrify, github: "ConnorRigby/mogrify", branch: "master", only: [:test, :dev]},
+      {:dialyxir, "~> 1.0.0-rc.7", only: [:dev], runtime: false}
     ]
   end
 

mix.lock

@@ -3,7 +3,9 @@
   "bunch_native": {:hex, :bunch_native, "0.2.1", "0227d2a751a32f8c0b77dfec57c8dc7216351720c9c755c467e6d9387467fd1f", [:mix], [{:bundlex, "~> 0.2.7", [hex: :bundlex, repo: "hexpm", optional: false]}], "hexpm", "f0819b2f9f78086447ac7459a8e7b6e25ad535b9d3a4f9469253c552137de6b4"},
   "bundlex": {:hex, :bundlex, "0.2.7", "8f46199bf4cf84a60cdfc142edeafbab37040167acc35dda8aa70433f2ff8162", [:mix], [{:bunch, "~> 1.0", [hex: :bunch, repo: "hexpm", optional: false]}, {:qex, "~> 0.5", [hex: :qex, repo: "hexpm", optional: false]}, {:secure_random, "~> 0.5", [hex: :secure_random, repo: "hexpm", optional: false]}], "hexpm", "5751b4bb5dd0576ca70519239e2ee7b495b17e4bbfbe3ef1f60ae0c12c0e4fe9"},
   "coerce": {:hex, :coerce, "1.0.1", "211c27386315dc2894ac11bc1f413a0e38505d808153367bd5c6e75a4003d096", [:mix], [], "hexpm", "b44a691700f7a1a15b4b7e2ff1fa30bebd669929ac8aa43cffe9e2f8bf051cf1"},
+  "dialyxir": {:hex, :dialyxir, "1.0.0-rc.7", "6287f8f2cb45df8584317a4be1075b8c9b8a69de8eeb82b4d9e6c761cf2664cd", [:mix], [{:erlex, ">= 0.2.5", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "506294d6c543e4e5282d4852aead19ace8a35bedeb043f9256a06a6336827122"},
   "earmark": {:hex, :earmark, "1.4.3", "364ca2e9710f6bff494117dbbd53880d84bebb692dafc3a78eb50aa3183f2bfd", [:mix], [], "hexpm", "8cf8a291ebf1c7b9539e3cddb19e9cef066c2441b1640f13c34c1d3cfc825fec"},
+  "erlex": {:hex, :erlex, "0.2.5", "e51132f2f472e13d606d808f0574508eeea2030d487fc002b46ad97e738b0510", [:mix], [], "hexpm", "756d3e19b056339af674b715fdd752c5dac468cf9d0e2d1a03abf4574e99fbf8"},
   "ex_doc": {:hex, :ex_doc, "0.21.3", "857ec876b35a587c5d9148a2512e952e24c24345552259464b98bfbb883c7b42", [:mix], [{:earmark, "~> 1.4", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "0db1ee8d1547ab4877c5b5dffc6604ef9454e189928d5ba8967d4a58a801f161"},
   "makeup": {:hex, :makeup, "1.0.0", "671df94cf5a594b739ce03b0d0316aa64312cee2574b6a44becb83cd90fb05dc", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "a10c6eb62cca416019663129699769f0c2ccf39428b3bb3c0cb38c718a0c186d"},
   "makeup_elixir": {:hex, :makeup_elixir, "0.14.0", "cf8b7c66ad1cff4c14679698d532f0b5d45a3968ffbcbfd590339cb57742f1ae", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "d4b316c7222a85bbaa2fd7c6e90e37e953257ad196dc229505137c5e505e9eff"},

test/turbojpeg_test.exs

@@ -1,6 +1,6 @@
 defmodule TurbojpegTest do
   use ExUnit.Case
-  use PropCheck, default_opts: [numtests: 10]
+  use PropCheck, numtests: 10
   use Mogrify.Options
 
   @jpeg_header <<255, 216, 255>>
@@ -10,52 +10,52 @@ defmodule TurbojpegTest do
   test "Converts an i420 frame into a jpeg" do
     frame = File.read!(@i420_fixture)
     shmex = Shmex.new(frame)
-    {:ok, jpeg} = Turbojpeg.Native.yuv_to_jpeg(shmex, 1920, 1080, 100, :I420)
+    {:ok, jpeg} = Turbojpeg.yuv_to_jpeg(shmex, 1920, 1080, 100, :I420)
     assert match?(@jpeg_header <> _, Shmex.to_binary(jpeg))
   end
 
   test "extracts i444 frame from jpeg" do
     jpeg = Shmex.new(File.read!(@ff0000_fixture))
-    {:ok, yuv} = Turbojpeg.Native.jpeg_to_yuv(jpeg)
-    {:ok, new_jpeg} = Turbojpeg.Native.yuv_to_jpeg(yuv, 64, 64, 100, :I444)
+    {:ok, yuv} = Turbojpeg.jpeg_to_yuv(jpeg)
+    {:ok, new_jpeg} = Turbojpeg.yuv_to_jpeg(yuv, 64, 64, 100, :I444)
     assert Shmex.to_binary(jpeg) == Shmex.to_binary(new_jpeg)
   end
 
   test "get jpeg header" do
     jpeg = Shmex.new(File.read!(@ff0000_fixture))
-    {:ok, result} = Turbojpeg.Native.get_jpeg_header(jpeg)
+    {:ok, result} = Turbojpeg.get_jpeg_header(jpeg)
     assert result.width == 64
     assert result.height == 64
     assert result.format == :I444
   end
 
-  @tag [timeout: :infinity]
-  property "encoding an image is fast", numtests: 8 do
+  @tag [timeout: :timer.minutes(2)]
+  property "encoding an image is fast", numtests: 5 do
     forall [width, height] <- [
              width(100),
              height(100)
            ] do
-      {jpeg_creation_micros, jpeg} =
-        :timer.tc(fn ->
-          jpeg =
-            %Mogrify.Image{}
-            |> Mogrify.custom("size", "#{width}x#{height}")
-            |> Mogrify.custom("seed", 43)
-            |> Mogrify.custom("plasma", "fractal")
-            |> Mogrify.custom("sampling-factor", "4:4:4")
-            |> Mogrify.custom("stdout", "jpg:-")
-            |> Mogrify.create(buffer: true)
-
-          Shmex.new(jpeg.buffer)
-        end)
-
-      {native_micros, ret} =
-        :timer.tc(fn ->
-          Turbojpeg.Native.jpeg_to_yuv(jpeg)
-        end)
+      jpeg =
+        %Mogrify.Image{}
+        |> Mogrify.custom("size", "#{width}x#{height}")
+        |> Mogrify.custom("seed", 43)
+        |> Mogrify.custom("plasma", "fractal")
+        |> Mogrify.custom("sampling-factor", "4:4:4")
+        |> Mogrify.custom("stdout", "jpg:-")
+        |> Mogrify.create(buffer: true)
 
+      Shmex.new(jpeg.buffer)
+
+      ret = Turbojpeg.jpeg_to_yuv(jpeg)
+
+      # Only for local runs
+      # {time_micros, ret} =
+      #   :timer.tc(fn ->
+      #     Turbojpeg.jpeg_to_yuv(jpeg)
+      #   end)
+
+      # assert time_micros / 1000 <= 5000
       assert match?({:ok, _}, ret)
-      aggregate(true, result: {to_range(10, jpeg_creation_micros), to_range(1024, jpeg.size)})
     end
   end
 
@@ -79,31 +79,25 @@ defmodule TurbojpegTest do
         |> Mogrify.create(buffer: true)
 
       jpeg = Shmex.new(jpeg.buffer)
-      {:ok, yuv} = Turbojpeg.Native.jpeg_to_yuv(jpeg)
+      {:ok, yuv} = Turbojpeg.jpeg_to_yuv(jpeg)
 
-      {:ok, original_header} = Turbojpeg.Native.get_jpeg_header(jpeg)
+      {:ok, original_header} = Turbojpeg.get_jpeg_header(jpeg)
 
-      {:ok, new_jpeg} =
-        Turbojpeg.Native.yuv_to_jpeg(yuv, width, height, 100, original_header.format)
+      {:ok, new_jpeg} = Turbojpeg.yuv_to_jpeg(yuv, width, height, 100, original_header.format)
 
-      {:ok, new_header} = Turbojpeg.Native.get_jpeg_header(new_jpeg)
+      {:ok, new_header} = Turbojpeg.get_jpeg_header(new_jpeg)
 
       assert original_header == new_header
-
-      aggregate(true,
-        r: to_range(51, r),
-        g: to_range(51, g),
-        b: to_range(51, b)
-      )
     end
   end
 
   property "jpeg and yuv conversion are complementary after running through the tool once" do
-    forall [width, height, seed, {sampling_factor, format}] <- [
+    forall [width, height, seed, {sampling_factor, format}, quality] <- [
              width(),
              height(),
              seed(),
-             format()
+             format(),
+             integer(0, 100)
            ] do
       jpeg =
         %Mogrify.Image{}
@@ -115,16 +109,11 @@ defmodule TurbojpegTest do
         |> Mogrify.create(buffer: true)
 
       jpeg = Shmex.new(jpeg.buffer)
-      {:ok, yuv} = Turbojpeg.Native.jpeg_to_yuv(jpeg)
-      {:ok, new_jpeg} = Turbojpeg.Native.yuv_to_jpeg(yuv, width, height, 100, format)
-      {:ok, original_header} = Turbojpeg.Native.get_jpeg_header(jpeg)
-      {:ok, new_header} = Turbojpeg.Native.get_jpeg_header(new_jpeg)
+      {:ok, yuv} = Turbojpeg.jpeg_to_yuv(jpeg)
+      {:ok, new_jpeg} = Turbojpeg.yuv_to_jpeg(yuv, width, height, quality, format)
+      {:ok, original_header} = Turbojpeg.get_jpeg_header(jpeg)
+      {:ok, new_header} = Turbojpeg.get_jpeg_header(new_jpeg)
       assert original_header == new_header
-
-      aggregate(true,
-        size: to_range(10_000, width * height) |> as_bytes(1024),
-        width: to_range(10, width)
-      )
     end
   end
 
@@ -137,11 +126,11 @@ defmodule TurbojpegTest do
     {div(min, size), div(max, size)}
   end
 
-  def width(multiplier \\ 50) do
+  def width(multiplier \\ 10) do
     dimension(multiplier)
   end
 
-  def height(multiplier \\ 50) do
+  def height(multiplier \\ 10) do
     dimension(multiplier)
   end