doc/html/orc-tutorial.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Orc Tutorial</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
   7 <link rel="home" href="index.html" title="Orc Reference Manual">
   8 <link rel="up" href="ch01.html" title="Overview">
   9 <link rel="prev" href="orc-concepts.html" title="Orc Concepts">
  10 <link rel="next" href="ch02.html" title="Application API">
  11 <meta name="generator" content="GTK-Doc V1.14 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
  16 <td><a accesskey="p" href="orc-concepts.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  17 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  18 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  19 <th width="100%" align="center">Orc Reference Manual</th>
  20 <td><a accesskey="n" href="ch02.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  21 </tr></table>
  22 <div class="refentry" title="Orc Tutorial">
  23 <a name="orc-tutorial"></a><div class="titlepage"></div>
  24 <div class="refnamediv"><table width="100%"><tr>
  25 <td valign="top">
  26 <h2><span class="refentrytitle">Orc Tutorial</span></h2>
  27 <p>Orc Tutorial —
  28 Getting started writing Orc code.
  29 </p>
  30 </td>
  31 <td valign="top" align="right"></td>
  32 </tr></table></div>
  33 <div class="refsect1" title="Orc Tutorial">
  34 <a name="id2900000"></a><h2>Orc Tutorial</h2>
  35 <p>
  36     This section walks you through several examples of increasing
  37     complexity to get you started working with Orc.  Each of these
  38     examples are available in the Orc source code, in the examples
  39     directory.  The first three examples use static Orc code that
  40     is in a source file, and is compiled into intermediate C code
  41     by the orcc tool.
  42   </p>
  43 <p>
  44     The first example demonstrates how to add two arrays of 16-bit
  45     signed integers together.  A possible use case for this is
  46     combining two stereo audio streams together.
  47   </p>
  48 <p>
  49     The second example builds from the first, replacing one of the
  50     stereo input streams with a mono stream, converting it to stereo
  51     in the process, and also adjusting the volume of the stream.
  52   </p>
  53 <p>
  54     The third example shows how to convert a planar 4:2:0 video
  55     image into a packed 4:4:4 video image with an alpha channel.
  56   </p>
  57 </div>
  58 <div class="refsect1" title="Example 1">
  59 <a name="id2932491"></a><h2>Example 1</h2>
  60 <p>
  61   This example demonstrates combining two stereo audio streams
  62   by adding.  Uncompressed audio streams (i.e., PCM format) can
  63   be in a variety of formats, but one of the most common is
  64   interleaved signed 16-bit integers, and we will choose that
  65   for the purposes of this example.  Extending to other formats
  66   is left as an exercise for the reader.  Interleaved means that
  67   left and right channel samples are consecutive: in memory, the
  68   data look like LRLRLR...  The sampling rate is unimportant, as
  69   long as both streams are the same.
  70 </p>
  71 <p>
  72   One important feature/limitation of signed 16-bit audio samples
  73   is that adding two together could cause an overflow.  For example,
  74   adding the value 25000 to 10000 gives 35000, but this overflows
  75   16 bits, so a standard addition would instead give the value
  76   -30536 (35000-65536).  Overflows handled this way sound like
  77   crackling or worse, so we would like a better solution.  One
  78   solution is to use saturating addition: in this case, the addition
  79   of 25000 and 10000 would be limited by the upper end of signed
  80   16-bit values to give 32767.  Although this still causes
  81   distortion in the output signal, it is much less audible and
  82   annoying.
  83 </p>
  84 <p>
  85   In normal C code, 16-bit saturating addition is difficult to express
  86   without using 32-bit intermediates.  In Orc, saturating addition
  87   is a basic operation with opcodes for each size, both signed and
  88   unsigned.  In this case, we want "addssw", for "add signed saturated
  89   word".
  90 </p>
  91 <p>
  92   Also, we're going to make a one simplification: Adding two
  93   interleaved stereo streams is the same as adding two mono streams
  94   with twice as many samples.  So we'll use 2*n_samples in the calling
  95   code.
  96 </p>
  97 <p>
  98   To the code:
  99
 100 </p>
 101 <pre class="programlisting">
 102 .function audio_add_s16
 103 .dest 2 d1
 104 .source 2 s1
 105 .source 2 s2
 106
 107 addssw d1, s1, s2
 108 </pre>
 109 <p>
 110 </p>
 111 <p>
 112   Line by line:
 113
 114 </p>
 115 <pre class="programlisting">
 116 .function audio_add_s16
 117 </pre>
 118 <p>
 119
 120   This starts a function.  A function (represented internally by the
 121   object OrcProgram) is equivalent to a C function.  When you generate
 122   C code from this Orc exmaple using the orcc tool, it generates a C
 123   stub function called "audio_add_s16()", which at runtime will
 124   generate an OrcProgram object corresponding to the above code,
 125   compile it, and then run it.
 126
 127 </p>
 128 <pre class="programlisting">
 129 .dest 2 d1 short
 130 </pre>
 131 <p>
 132
 133   This specifies that you want a destination (output) array named "d1",
 134   with the element size being 2.  Orc does not differentiate between
 135   signed and unsigned arrays (or even floating point), however, you
 136   may optionally specify a type afterwards that will be used in any
 137   autogenerated C code.
 138
 139 </p>
 140 <pre class="programlisting">
 141 .source 2 s1 short
 142 .source 2 s2 short
 143 </pre>
 144 <p>
 145
 146   This specifies that you want two source (input) arrays, "s1" and "s2",
 147   similar to the destination array.
 148
 149 </p>
 150 <pre class="programlisting">
 151 addssw d1, s1, s2
 152 </pre>
 153 <p>
 154
 155   This specifies the (only) opcode that we want for this program: signed
 156   saturated addition of each member of the two source arrays, and store
 157   the result in the destination array.
 158 </p>
 159 <p>
 160   A few notes about the above program: The loop over the array members
 161   is implied.  Everything that Orc does is based on looping over each
 162   array element and executing the opcodes in a program.
 163 </p>
 164 <p>
 165   When you generate C code from the above Orc code using
 166   'orcc --implementation example1.orc',
 167   you get a bunch of boilerplate code, plus three C functions:
 168
 169 </p>
 170 <pre class="programlisting">
 171 /* audio_add_s16 */
 172 #ifdef DISABLE_ORC
 173 void
 174 audio_add_s16 (int16 * d1, const int16 * s1, const int16 * s2, int n)
 175 {
 176   ...
 177 }
 178 </pre>
 179 <p>
 180
 181   This function is used if DISABLE_ORC is defined.  As one might guess,
 182   if you define DISABLE_ORC, no runtime Orc features are used, and all
 183   calls to audio_add_s16() use this function.  The interior of the function
 184   is a for() loop that implements the Orc function.  The generated code
 185   may not necessarily be easy to read, but it is straightforward: all
 186   the verbosity and use of unions is to avoid compiler warnings without
 187   making the compiler too complex.  But this is the place to go if you
 188   are trying to understand what Orc is doing.
 189
 190 </p>
 191 <pre class="programlisting">
 192 #else
 193 static void
 194 _backup_audio_add_s16 (OrcExecutor * ORC_RESTRICT ex)
 195 {
 196   ...
 197 }
 198 </pre>
 199 <p>
 200
 201   This function is used when runtime Orc is enabled, but Orc was unable
 202   to generate code for the function at runtime.  There are various
 203   reasons why that might happen -- unimplemented rules for a target, or
 204   more temporary variables used than available registers.
 205
 206 </p>
 207 <pre class="programlisting">
 208 void
 209 audio_add_s16 (short * d1, const short * s1, const short * s2, int n)
 210 {
 211   ...
 212 }
 213 </pre>
 214 <p>
 215
 216   The third generated function is the important part: It is used when
 217   Orc is enabled at runtime, and creates the OrcProgram corresponding
 218   to the function you defined.  Then it compiles the function and
 219   calls it.
 220 </p>
 221 <p>
 222   After generating the C code, you should generate the header file,
 223   using: 'orcc --header example1orc.orc -o example1orc.h'.
 224   After similar boilerplate code, there is the expected declaration
 225   of audio_add_s16():
 226
 227 </p>
 228 <pre class="programlisting">
 229 void audio_add_s16 (short * d1, const short * s1, const short * s2, int n);
 230 </pre>
 231 <p>
 232
 233
 234 </p>
 235 <p>
 236   Some C code to generate sample data, call the generated code, and
 237   print out the results:
 238
 239 </p>
 240 <pre class="programlisting">
 241 #include &lt;stdio.h&gt;
 242 #include "example1orc.h"
 243
 244 #define N 10
 245
 246 short a[N];
 247 short b[N];
 248 short c[N];
 249
 250 int
 251 main (int argc, char *argv[])
 252 {
 253   int i;
 254
 255   /* Create some data in the source arrays */
 256   for(i=0;i &lt; N;i++){
 257     a[i] = 100*i;
 258     b[i] = 32000;
 259   }
 260
 261   /* Call a function that uses Orc */
 262   audio_add_s16 (c, a, b, N);
 263
 264   /* Print the results */
 265   for(i=0;i &lt; N;i++){
 266     printf("%d: %d %d -&gt; %d\n", i, a[i], b[i], c[i]);
 267   }
 268
 269   return 0;
 270 }
 271 </pre>
 272 <p>
 273 </p>
 274 <p>
 275   The output of the program:
 276
 277 </p>
 278 <pre class="programlisting">
 279 0: 0 32000 -&gt; 32000
 280 1: 100 32000 -&gt; 32100
 281 2: 200 32000 -&gt; 32200
 282 3: 300 32000 -&gt; 32300
 283 4: 400 32000 -&gt; 32400
 284 5: 500 32000 -&gt; 32500
 285 6: 600 32000 -&gt; 32600
 286 7: 700 32000 -&gt; 32700
 287 8: 800 32000 -&gt; 32767
 288 9: 900 32000 -&gt; 32767
 289 </pre>
 290 <p>
 291 </p>
 292 <p>
 293
 294 </p>
 295 </div>
 296 <div class="refsect1" title="Example 2">
 297 <a name="id2935554"></a><h2>Example 2</h2>
 298 <p>
 299   In this example, we will expand on the previous example by making
 300   one of the input arrays a mono stream, and also scale the mono
 301   input stream by a volume.  Rather than iterating over each
 302   signed 16-bit value, in this example we will iterate over samples,
 303   meaning the member size for the stereo arrays is 4, since each
 304   array member contains a left and right 16 bit value.
 305 </p>
 306 <p>
 307 </p>
 308 <pre class="programlisting">
 309 .function audio_add_mono_to_stereo_scaled_s16
 310 .dest 4 d1 short
 311 .source 4 s1 short
 312 .source 2 s2 short
 313 .param 2 volume
 314 .temp 4 s2_scaled
 315 .temp 2 t
 316 .temp 4 s2_stereo
 317
 318 mulswl s2_scaled, s2, volume
 319 shrsl s2_scaled, s2_scaled, 12
 320 convssslw t, s2_scaled
 321 mergewl s2_stereo, t, t
 322 x2 addssw d1, s1, s2_stereo
 323 </pre>
 324 <p>
 325
 326   Piece by piece:
 327
 328 </p>
 329 <pre class="programlisting">
 330 .function audio_add_mono_to_stereo_scaled_s16
 331 .dest 4 d1 short
 332 .source 4 s1 short
 333 .source 2 s2 short
 334 </pre>
 335 <p>
 336
 337   This is the same as the previous example, except that the stereo
 338   arrays are increased in size to 4.  However, we'll use the short
 339   type, since Orc does not care what type we use, and short is
 340   the type of the array we want to use in the C code.
 341
 342 </p>
 343 <pre class="programlisting">
 344 .param 2 volume
 345 </pre>
 346 <p>
 347
 348   This specifies a parameter, which is an integer that is passed to
 349   an Orc function.  In the generated C code, parameters are always of
 350   type int.  There are also float parameters for the floating point
 351   equivalent.
 352
 353 </p>
 354 <pre class="programlisting">
 355 .temp 4 s2_scaled
 356 .temp 2 t
 357 .temp 4 s2_stereo
 358 </pre>
 359 <p>
 360
 361   This specifies a few temporary variables that are used later in the
 362   code.  These definitions are similar to defining local variables in
 363   C code.  Note that the size is important:  each opcode has
 364   specific sizes for source and destination operands, and it is
 365   important to match these correctly with temporary variables.
 366
 367 </p>
 368 <pre class="programlisting">
 369 mulswl s2_scaled, s2, volume
 370 shrsl s2_scaled, s2_scaled, 12
 371 </pre>
 372 <p>
 373
 374   This scales the mono input: signed multiply of s2 and volume, giving
 375   a 32-bit value, and then a signed right shift by 12.  Since the
 376   second operand of mulswl is 16-bit, only the lower 16 bits of
 377   volume will be used in the multiply.  The right shift is
 378   effectively the same as dividing by 4096.  Thus, a neutral scaling
 379   that does not increase or decrease the mono input would correspond
 380   to calling the function with a parameter value of 4096.
 381
 382 </p>
 383 <pre class="programlisting">
 384 convssslw t, s2_scaled
 385 mergewl s2_stereo, t, t
 386 </pre>
 387 <p>
 388
 389   The first instruction is "convert saturated signed 32-bit to signed
 390   16-bit", and the second merges the two values of (16 bit) t into the
 391   high and low halves of s2_stereo.  This duplicates the mono signal
 392   into the right and left channels.  It is important to use the
 393   saturated conversion, since the effective scaling value may have
 394   been greater than 1.0, thus the larger values may need to be clipped.
 395
 396 </p>
 397 <pre class="programlisting">
 398 x2 addssw d1, s1, s2_stereo
 399 </pre>
 400 <p>
 401
 402   The "x2" prefix indicates that we want the operation specified to be
 403   done twice, first to the upper half of all operands, and again
 404   separately to the lower half of all operands.  Since addssw is
 405   normally a 16-bit operation, the x2 prefix causes it to be a 32-bit
 406   operation.  And so, it adds the newly created right and left values
 407   of the scaled mono signal into the s1 signal.
 408 </p>
 409 <p>
 410   There are several variations of the above program that might be
 411   more suitable for a particular application.  This function only
 412   handles a limited dynamic range of volume scaling factors, however,
 413   by changing the shift constant, or turning the shift into a
 414   parameter, the dynamic range can be increased significantly.
 415 </p>
 416 </div>
 417 <div class="refsect1" title="Example 3">
 418 <a name="id2935677"></a><h2>Example 3</h2>
 419 <p>
 420   The third example shows how to convert a planar 4:2:0 video
 421   image into a packed 4:4:4 video image with an alpha channel.  The
 422   first format is often referred to as I420 and the second as AYUV.
 423 </p>
 424 <p>
 425   For simplicity in the following discussion, we'll assume that the
 426   image dimensions are 640x480.  The 4:2:0 subsampling means the
 427   input chroma planes are 320x240 (subsampled by 2 in each direction).
 428   These need to be upsampled to 640x480, then repacked with the input
 429   Y plane, with an added dummy alpha value.  There are many ways to
 430   perform upsampling; the simplest is to duplicate each value
 431   horizontally and vertically.  The result is low quality, but
 432   adequate for demonstration purposes.
 433 </p>
 434 <p>
 435   There are several choices for the Orc array size and dimensionality.
 436   Iterating vertically can be done in the C code or in the Orc code.  If
 437   done in the Orc code, we would need to use an array size of 240 and
 438   have two separate arrays for the even and odd Y rows.  If done in the
 439   C code, there is no such limitation.  Horizontally, the story is
 440   different: we can use the loadupsdb opcode to duplicate each byte in
 441   the U and V arrays, so we can iterate over 640 array elements.  It
 442   is also possible to iterate over 320 elements and duplicate the U
 443   and V elements using mergebw.  There is a very slight speed
 444   advantage to iterating vertically in Orc, and for demonstration
 445   purposes, we will choose to use the loadupsdb opcode, thus we will
 446   be iterating over 320x240 elements.
 447 </p>
 448 <p>
 449   The code:
 450
 451 </p>
 452 <pre class="programlisting">
 453 .function convert_I420_AYUV
 454 .flags 2d
 455 .dest 4 d1
 456 .dest 4 d2
 457 .source 1 y1
 458 .source 1 y2
 459 .source 1 u
 460 .source 1 v
 461 .const 1 c255 255
 462 .temp 2 uv
 463 .temp 2 ay
 464 .temp 1 tu
 465 .temp 1 tv
 466
 467 loadupdb tu, u
 468 loadupdb tv, v
 469 mergebw uv, tu, tv
 470 mergebw ay, c255, y1
 471 mergewl d1, ay, uv
 472 mergebw ay, c255, y2
 473 mergewl d2, ay, uv
 474 </pre>
 475 <p>
 476
 477   A few things of note: The ".flags 2d" line is used to indicate that
 478   Orc should iterate over two dimensions, and generate a prototype that
 479   includes row strides for each array and a size parameter for the
 480   second dimension.
 481 </p>
 482 <p>
 483   Since we are working on two input Y lines and two output AYUV lines
 484   at a time, we need two source and destination arrays corresponding
 485   to the even and odd lines.  The row strides for these are doubled
 486   compared to the normal 2-D array.
 487 </p>
 488 <p>
 489   The mergebw and mergewl opcodes join two 8-bit values into one 16-bit
 490   value (or 16-bit values into a 32-bit value) by concatinating them
 491   in memory order.  Thus, to get AYUV in memory order, we merge AY and
 492   UV, and to get UV, we merge U and V.  Since we're duplicating each
 493   U and V line, we use the same UV value for the even and odd output
 494   lines.
 495 </p>
 496 <p>
 497   The prototype that is generated is:
 498
 499 </p>
 500 <pre class="programlisting">
 501 void convert_I420_AYUV (orc_uint32 * d1, int d1_stride, orc_uint32 * d2,
 502   int d2_stride, const orc_uint8 * s1, int s1_stride, const orc_uint8 * s2,
 503   int s2_stride, const orc_uint8 * s3, int s3_stride, const orc_uint8 * s4,
 504   int s4_stride, int n, int m);
 505 </pre>
 506 <p>
 507
 508   The orcc tool unhelpfully changed the names of the parameters,
 509   however, the order is standard: first destinations, then sources, then
 510   parameters, then array sizes.  Think of it like memcpy() or memset().
 511 </p>
 512 <p>
 513   Calling the function:
 514
 515 </p>
 516 <pre class="programlisting">
 517 convert_I420_AYUV (output, 1280*4, output + 640, 1280 * 4,
 518     input_y, 1280, input_y + 640, 1280,
 519     input_u, 320, input_v, 320,
 520     320, 240);
 521 </pre>
 522 <p>
 523
 524 </p>
 525 </div>
 526 </div>
 527 <div class="footer">
 528 <hr>
 529           Generated by GTK-Doc V1.14</div>
 530 </body>
 531 </html>