fragment_downloaded_cb({"url":"tutorial.html#example-1","fragment":"Example 1\nThis example demonstrates combining two stereo audio streams by adding. Uncompressed audio streams (i.e., PCM format) can be in a variety of formats, but one of the most common is interleaved signed 16-bit integers, and we will choose that for the purposes of this example. Extending to other formats is left as an exercise for the reader. Interleaved means that left and right channel samples are consecutive: in memory, the data look like LRLRLR... The sampling rate is unimportant, as long as both streams are the same.\nOne important feature/limitation of signed 16-bit audio samples is that adding two together could cause an overflow. For example, adding the value 25000 to 10000 gives 35000, but this overflows 16 bits, so a standard addition would instead give the value -30536 (35000-65536). Overflows handled this way sound like crackling or worse, so we would like a better solution. One solution is to use saturating addition: in this case, the addition of 25000 and 10000 would be limited by the upper end of signed 16-bit values to give 32767. Although this still causes distortion in the output signal, it is much less audible and annoying.\nIn normal C code, 16-bit saturating addition is difficult to express without using 32-bit intermediates. In Orc, saturating addition is a basic operation with opcodes for each size, both signed and unsigned. In this case, we want \"addssw\", for \"add signed saturated word\".\nAlso, we're going to make a one simplification: Adding two interleaved stereo streams is the same as adding two mono streams with twice as many samples. So we'll use 2*n_samples in the calling code.\nTo the code:\nLine by line:\nThis starts a function. A function (represented internally by the object OrcProgram) is equivalent to a C function. When you generate C code from this Orc exmaple using the orcc tool, it generates a C stub function called \"audio_add_s16()\", which at runtime will generate an OrcProgram object corresponding to the above code, compile it, and then run it.\nThis specifies that you want a destination (output) array named \"d1\", with the element size being 2. Orc does not differentiate between signed and unsigned arrays (or even floating point), however, you may optionally specify a type afterwards that will be used in any autogenerated C code.\nThis specifies that you want two source (input) arrays, \"s1\" and \"s2\", similar to the destination array.\nThis specifies the (only) opcode that we want for this program: signed saturated addition of each member of the two source arrays, and store the result in the destination array.\nA few notes about the above program: The loop over the array members is implied. Everything that Orc does is based on looping over each array element and executing the opcodes in a program.\nWhen you generate C code from the above Orc code using 'orcc --implementation example1.orc', you get a bunch of boilerplate code, plus three C functions:\nThis function is used if DISABLE_ORC is defined. As one might guess, if you define DISABLE_ORC, no runtime Orc features are used, and all calls to audio_add_s16() use this function. The interior of the function is a for() loop that implements the Orc function. The generated code may not necessarily be easy to read, but it is straightforward: all the verbosity and use of unions is to avoid compiler warnings without making the compiler too complex. But this is the place to go if you are trying to understand what Orc is doing.\nThis function is used when runtime Orc is enabled, but Orc was unable to generate code for the function at runtime. There are various reasons why that might happen -- unimplemented rules for a target, or more temporary variables used than available registers.\nThe third generated function is the important part: It is used when Orc is enabled at runtime, and creates the OrcProgram corresponding to the function you defined. Then it compiles the function and calls it.\nAfter generating the C code, you should generate the header file, using: 'orcc --header example1orc.orc -o example1orc.h'. After similar boilerplate code, there is the expected declaration of audio_add_s16():\nSome C code to generate sample data, call the generated code, and print out the results:\nThe output of the program:\n"});