| [opengtl-commits] [499] update shivaspec with a metadata section |
[ Thread Index |
Date Index
| More lists.tuxfamily.org/opengtl-commits Archives
]
Revision: 499
Author: cyrille
Date: 2008-11-27 00:08:25 +0100 (Thu, 27 Nov 2008)
Log Message:
-----------
update shivaspec with a metadata section
Modified Paths:
--------------
trunk/OpenGTL/OpenShiva/doc/specification/ShivaSpec.tex
Modified: trunk/OpenGTL/OpenShiva/doc/specification/ShivaSpec.tex
===================================================================
--- trunk/OpenGTL/OpenShiva/doc/specification/ShivaSpec.tex 2008-11-26 23:07:55 UTC (rev 498)
+++ trunk/OpenGTL/OpenShiva/doc/specification/ShivaSpec.tex 2008-11-26 23:08:25 UTC (rev 499)
@@ -1,11 +1,18 @@
\documentclass[a4paper,10pt]{report}
\usepackage{array}
\usepackage{graphicx}
+\usepackage{listings}
+\usepackage{color}
% Title Page
\title{Shiva Language Specification}
\author{Cyrille Berger}
+\definecolor{ColorCodeBackground}{rgb}{0.9,0.9,0.9}
+\lstset{frame=lines,backgroundcolor=\color{ColorCodeBackground},
+basicstyle=\small,numbers=left}
+
+
\begin{document}
\maketitle
@@ -38,23 +45,31 @@
\section{Structure}
-\begin{verbatim}
+\begin{lstlisting}
+<
+...
+>
kernel MyKernel
{
parameter float firstParameter;
parameter int secondParameter;
...
- void evaluatePixel(input image source1, input image source2, ..., output pixel result)
+ void evaluatePixel(input image source1, input image source2,
+ ..., output pixel result)
{
...
}
- region needed(region output_region, int input_index, region input_DOD[])
+ region needed(region output_region, int input_index,
+ region input_DOD[])
{
...
}
}
-\end{verbatim}
+\end{lstlisting}
+The \verb|< ... >| is the metadata associated with a \verb|kernel| and is
+optional.
+
While the order of functions in the kernel is not important, if you want to use
a function or a constant it needs to be define before its use. For instance the
\verb|needed| and \verb|changed| functions can use the name of source of image
@@ -65,23 +80,24 @@
\subsection{evaluatePixel}
-\begin{verbatim}
- void evaluatePixel(input image source1, input image source2, ..., output pixel
-result)
- {
- ...
- }
-\end{verbatim}
+\begin{lstlisting}
+void evaluatePixel(input image source1, input image source2,
+ ..., output pixel result)
+{
+ ...
+}
+\end{lstlisting}
\subsection{needed}
-\begin{verbatim}
- region needed(region output_region, int input_index, region input_DOD[])
- {
- ...
- }
-\end{verbatim}
+\begin{lstlisting}
+region needed(region output_region, int input_index,
+ region input_DOD[])
+{
+ ...
+}
+\end{lstlisting}
The \verb|needed| function indicates the Shiva interpreter which pixel in the
input images are needed. For instance, if you program is a gaussian blur, it
@@ -92,20 +108,20 @@
\verb|region output_region| & the region that will be operated
by the kernel \\
\hline
-\verb|int input_index| & the index of the image for which we want to know the
-region that will be needed \\
+\verb|int input_index| & the index of the image for which we want to
+know the region that will be needed \\
\hline
\verb|region input_DOD[]| & the list of input \\
\hline
\end{tabular}
Exemple for a gaussian blur:
-\begin{verbatim}
+\begin{lstlisting}
region needed(region output_region, int input_index, region input_DOD[])
{
output_region.outset(1,1)
}
-\end{verbatim}
+\end{lstlisting}
\subsection{changed}
@@ -114,13 +130,13 @@
changed. As a special note, the changed function is usually called at the first
run to compute the region of the output image.
-\begin{verbatim}
+\begin{lstlisting}
region changed( region changed_input_region, int input_index, region
input_DOD[])
{
...
}
-\end{verbatim}
+\end{lstlisting}
\subsection{generated}
@@ -129,12 +145,12 @@
expected to be of infinite size, some generators can have a more limited area
of effect.
-\begin{verbatim}
+\begin{lstlisting}
region generated()
{
...
}
-\end{verbatim}
+\end{lstlisting}
@@ -144,15 +160,77 @@
parameter and return the number of failed tests.
Exemple:
-\begin{verbatim}
+\begin{lstlisting}
int runTest()
{
int count = 0;
if( (1+1) != 2) ++count;
return count;
}
-\end{verbatim}
+\end{lstlisting}
+\section{Metadata}
+A \verb|kernel| can contains metadata before the its declaration. Metadata is
+divided in optional sections.
+
+\begin{itemize}
+ \item \verb|version| indicates the version of the Shiva spec used for this
+\verb|kernel|, the current version is \textit{0}
+ \item \verb|info| this section contains various information about the
+\verb|kernel|, author, vendor, license... and it is basically a list of key /
+value.
+ \item \verb|parameters| this section allow to define parameters that can be
+adjusted by the user and will be given to the kernel as constant parameters
+before compilation.
+\end{itemize}
+
+Example of metadata:
+\begin{lstlisting}
+ <
+ version: 0;
+ info: <
+ author: "Joe Doe; Joe Doe Jr";
+ vendor: <
+ name: DoeGraphics;
+ address: 1242 Main Street;
+ >
+ license: "LGPLv2+";
+ >;
+ parameters: <
+ param1: <
+ type: int;
+ minValue: 0;
+ maxValue: 100;
+ defaultValue: 50;
+ description: This is the first parameter;
+ >;
+ categorie2: <
+ description: This is a categorie of parameters
+ param2: <
+ type: curve;
+ defaultValue: {{0,0},{1,1}};
+ >;
+ >;
+ >;
+ >
+\end{lstlisting}
+
+
+\subsection{info}
+
+\subsection{parameters}
+
+Supported types of parameters:
+\begin{itemize}
+ \item \verb|int| integer value, if no range is specified it is defaulted to
+$[ 0, 100 ] $
+ \item \verb|float| float value (32bits), if no range is specified it is
+defaulted to $[ 0.0, 1.0 ] $
+ \item \verb|curve| (mapped to \verb|float[][2]|) this allow to pass a curve to
+a \verb|kernel|, values are expected to between $ (0,0) $ and $ (1,1) $.
+\end{itemize}
+
+
\chapter{library}
Libraries are used to write reusable code for Shiva Kernel, if you have
@@ -161,7 +239,7 @@
Libraries are started with the \verb|library| keyword and can contain
constants, and functions:
-\begin{verbatim}
+\begin{lstlisting}
library MyLibrary {
const int value = 2;
int addValue(int v )
@@ -169,16 +247,16 @@
return v + value;
}
}
-\end{verbatim}
+\end{lstlisting}
The keyword \verb|import| allows to use a library in a kernel:
-\begin{verbatim}
+\begin{lstlisting}
import mylibrary;
...
int v = 3;
v = MyLibrary::addValue( v );
-\end{verbatim}
+\end{lstlisting}
\chapter{Types}
@@ -201,29 +279,29 @@
\subsection{Vectors initialisation}
Vectors are initialized using a list of elements
\verb|{ first element, second element, ...}|. For instance:
-\begin{verbatim}
+\begin{lstlisting}
float3 v = { 1.0, 2.0, 3.0 };
-\end{verbatim}
+\end{lstlisting}
Alternatively vectors can be initilized using their constructor:
-\begin{verbatim}
+\begin{lstlisting}
typeN::typeN(el0, el1, ..., elN)
-\end{verbatim}
+\end{lstlisting}
For instance:
-\begin{verbatim}
+\begin{lstlisting}
float3 v( 1.0, 2.0, 3.0 );
float3 v;
v = float3(1.0, 2.0, 3.0);
-\end{verbatim}
+\end{lstlisting}
\subsection{Access vectors elements}
Vector elements can be access using the classical subscript operator \verb|[]|.
For instance:
-\begin{verbatim}
+\begin{lstlisting}
float3 v( 1.0, 2.0, 3.0 );
float v0 = v[0];
-\end{verbatim}
+\end{lstlisting}
The elements of the vector can be access as named elements using the following
sequences :
@@ -236,29 +314,27 @@
\subsection{Specific members for floating points vector}
-\paragraph{length}
-\begin{verbatim}
+\paragraph{length} This function return the length of the vector:
+\begin{lstlisting}
floatN floatN::length( )
-\end{verbatim}
-This function return the length of the vector.
+\end{lstlisting}
For instance:
-\begin{verbatim}
+\begin{lstlisting}
float2 float2::length( )
{
return sqrt( this[0] * this[0] + this[1] * this[1]);
}
-\end{verbatim}
+\end{lstlisting}
-\paragraph{normalize}
-\begin{verbatim}
+\paragraph{normalize} This function return the normalized version of the vector:
+\begin{lstlisting}
floatN floatN::normalize( )
{
return this / this.length();
}
-\end{verbatim}
-This function return the normalized version of the vector.
+\end{lstlisting}
\section{Complex types}
@@ -277,11 +353,12 @@
at compile time.
\subsubsection{Members}
-\paragraph{sampleNearest and sampleLinear}
-\begin{verbatim}
+\paragraph{sampleNearest and sampleLinear} Those two functions are used to
+access the pixel value in the image:
+\begin{lstlisting}
void imageN::sampleNearest(float2 coord)
void imageN::sampleLinear(float2 coord)
-\end{verbatim}
+\end{lstlisting}
\verb|sampleNearest| return the value of the pixel whose coordinates
are the closest to the coordinates given as argument. This function does no
@@ -289,7 +366,7 @@
interpolation.
For instance the following function will copy the source image into the output:
-\begin{verbatim}
+\begin{lstlisting}
kernel Copy
{
void evaluatePixel(input image source, output pixel result)
@@ -297,11 +374,11 @@
result = source.sampleNearest( result.coord() );
}
}
-\end{verbatim}
+\end{lstlisting}
For instance the following function will translate the source image by
$(-4,-2)$:
-\begin{verbatim}
+\begin{lstlisting}
kernel Translate
{
void evaluatePixel(input image source, output pixel result)
@@ -309,7 +386,7 @@
result = source.sampleNearest( result.coord() + float2(4,2) );
}
}
-\end{verbatim}
+\end{lstlisting}
\subsection{Pixeles types}
@@ -339,14 +416,14 @@
\subsection{Region types}
-\begin{verbatim}
+\begin{lstlisting}
struct Region {
float x;
float y;
float width;
float height;
}
-\end{verbatim}
+\end{lstlisting}
\begin{figure*}[htp]
\centering
@@ -362,7 +439,7 @@
respectively, the horrizontal coordinate of the left pixels and of the right
pixels, and the vertical coordinate of the top pixels and bottom pixels.
-\begin{verbatim}
+\begin{lstlisting}
region reg = { 1, 2, 10, 20 };
reg.left() == 1;
reg.left() == reg.x
@@ -372,47 +449,47 @@
reg.right() == reg.x + reg.width - 1
reg.bottom() == 11;
reg.bottom() == reg.y + reg.height - 1
-\end{verbatim}
+\end{lstlisting}
\paragraph{Intersect}
The \verb|intersect| function will intersect the current region with an other
region.
-\begin{verbatim}
+\begin{lstlisting}
region reg1 = { 0, 0, 2, 2 };
region reg2 = { 1, -1, 3, 2 };
reg1.intersect( reg2 );
// Now reg1 == { 1, 0, 1, 1 };
-\end{verbatim}
+\end{lstlisting}
\paragraph{Union}
The \verb|union| function will unify the current region with an other region.
-\begin{verbatim}
+\begin{lstlisting}
region reg1 = { 0, 0, 2, 2 };
region reg2 = { 1, -1, 3, 2 };
reg1.union( reg2 );
// Now reg1 == { 0, -1, 4, 3 };
-\end{verbatim}
+\end{lstlisting}
\paragraph{Outset}
The \verb|outset| function expand each edge of a given amount.
-\begin{verbatim}
+\begin{lstlisting}
region reg = { 0, 1, 2, 3 };
reg.outset(1);
// Now reg == { -1, 0, 4, 5 };
-\end{verbatim}
+\end{lstlisting}
\paragraph{Inset}
The \verb|inset| function contract each edge of a given amount.
-\begin{verbatim}
+\begin{lstlisting}
region reg = { 0, 1, 2, 3 };
reg.inset(1);
// Now reg == { 1, 2, 0, 1 };
-\end{verbatim}
+\end{lstlisting}
\section{Special types}
@@ -420,12 +497,12 @@
\subsection{Void}
Functions that do not return a value are declared with the type \verb|void|.
For instance:
-\begin{verbatim}
+\begin{lstlisting}
void addition(input int a, input int b, output int c)
{
c = a + b;
}
-\end{verbatim}
+\end{lstlisting}
\chapter{Function declaration}
@@ -473,11 +550,14 @@
\subsection{Pixel arithmetic}
-Pixel arithmetic is defined depending on the type of the channel, for floating point channels
-the arithmetic is the same as for numbers. But for integer channels, the arithmetic is defined
+Pixel arithmetic is defined depending on the type of the channel, for floating
+point channels
+the arithmetic is the same as for numbers. But for integer channels, the
+arithmetic is defined
by the following formulas:
-$ MAX $ is the maximum value of an integer channel, $ MAX = 255 $ for 8bits, $ MAX = 65535 $ for 16bits
+$ MAX $ is the maximum value of an integer channel, $ MAX = 255 $ for 8bits, $
+MAX = 65535 $ for 16bits
and $ MAX = 4294967295 $ for 32bits.
\begin{itemize}
@@ -487,14 +567,20 @@
\item \verb|/| : $ ( a * MAX ) / b $
\end{itemize}
-To avoid overflow, operations are computed at a higher level of bit depth, 8bits operations are done in 16bits,
+To avoid overflow, operations are computed at a higher level of bit depth, 8bits
+operations are done in 16bits,
16bits operations in 32bits, and 32bits operation in 64bits.
\subsection{Type conversion}
-Type conversion between primary types is implicit. They follow the following priority, from low to highest : bool, unsigned int, int, float, when a low priority is added to a high priority type, then the result is in the high priority
+Type conversion between primary types is implicit. They follow the following
+priority, from low to highest : bool, unsigned int, int, float, when a low
+priority is added to a high priority type, then the result is in the high
+priority
type.
-Pixels types can be converted as a vector of float in the range $ [ 0, 1 ] $ for integer pixels, or directly
-for float pixels. The opposite conversion is also possible from float vectors to pixels.
+Pixels types can be converted as a vector of float in the range $ [ 0, 1 ] $ for
+integer pixels, or directly
+for float pixels. The opposite conversion is also possible from float vectors to
+pixels.
\chapter{Grammar}
@@ -561,9 +647,12 @@
\section{Compatibility function with Hydra}
+
+This is a library intented to ease compatibility with Hydra.
+
\subsection{Image}
\paragraph{sampleNearest and sampleLinear}
-\begin{verbatim}
+\begin{lstlisting}
pixelN sampleNearest(imageN, float2 coord)
{
return imageN.sampleNearest(coord);
@@ -572,7 +661,7 @@
{
return imageN.sampleLinear(coord);
}
-\end{verbatim}
+\end{lstlisting}
\chapter{Interfacing with CTL}