Graphics Equalizer Display Library Helpww1.microchip.com/downloads/en//softwarelibrary/pic32 audio...

Graphics Equalizer DisplayLibrary Help

Copyright (c) 2013 Microchip Technology Inc. All rights reserved.

1 Graphic Equalizer Display Library Files Referenced

Name Descriptionaudio_equalizer_fixedpoint.h Audio Equalizer (DSP) fixed point typedefs.

graphic_equalizer.h Supports graphic equalizer display.

graphic_equalizer_config.h Supports graphic equalizer display by defining various display colors

Description

1 Graphics Equalizer Display Library Help

1-1

1

C14575

Line

1.1 Introduction Graphic Equalizer Display Library

for

Microchip Microcontrollers

The Graphic Equalizer Display Library is a graphics library. It works on any Microchip device that drives an LCD display,providing Graphic Equalizer displays (see below) for the host application. Graphic Equalizers are used to adjust the spectralcontent of music by providing gain or attenuation to parts of the music based on frequency. This library works hand-in-hand withthe Audio Equalizer Filtering Library, which does the actual signal processing (filtering).

Description

The Graphic Equalizer Display Library is an adjunct of the Audio Equalizer Filtering Library in that it supports displayinginformation produced by routines in the filtering library, namely signal strength as measured by the filtering library. It alsosupports displaying band filter gains so that the user can adjust filter gains as part of a Graphic Equalizer display.

Audio equalization filtering and the supporting Graphic Equalizer Display are just two parts of an overall system that deliversmusic to the user:

The blocks in orange are part of the Audio Equalization Filtering library. The blocks in green are part of the Graphic EqualizerDisplay library.

As shown above a smart phone can provide music through a Bluetooth or USB interface that is then decoded using the AudioDecoder. Raw left/right samples are then filtered and passed on to an audio amplifier and DAC to convert digital samples intoanalog sound. The Digital Filter block also measure frequency band signal strength (energy) and passes this information ontothe Graphics Formatting block for display on the application LCD.

As a black box, a graphic equalizer has left/right inputs and left/right outputs:

1.1 Introduction Graphics Equalizer Display Library Help

1-2

1

In this example, frequency bands are centered at 50 Hz, 150 Hz, 300 Hz, ... , 10 KHz, and 12.5 KHz. Signal strength is plottedfor each frequency band by a stack of green bars, more bars meaning a stronger signal. Below each stack of green bars is aslider that is used to adjust the filter gain for each band, which is centered at the frequency shown. Moving the red tab upincreases filter gain, increasing signal strength. Moving the red tab down decreases filter gain, decreasing signal strength.

A typical band filter passes signals centered at a frequency (f0) and attenuates signals outside of a pass band (fL to fH). Thepass band gain, shown below as 0 dB, or unity gain, can be adjusted up or down to increase or decrease signal strength in theband (fL to fH).

Graphic equalizer filters adjust the spectral content of music by filtering left and right stereo signals through a bank of parallelfilters, summing the results to create the output left and right signals. Each filter passes part of the signal's spectrum. Addedtogether again after filtering the left/right signals are reconstructed with modified spectral content. Increasing the gain of a filterwill emphasize the signal in that filter's frequency band. Decreasing the gain of a filter will de-emphasize the signal in that filter'sfrequency band.

A typical graphic equalizer filter bank can be represented by:


1-3

1

The Audio Decoder takes raw binary music and decodes it into a stream of 16 or 24 bit integers, with a pair of such integersrepresenting a single left/right sample of music. Typically these samples are played at 44,100 or 48,000 sample per second.Signals from the left or right channel are fed into a bank of parallel band filters. The output of each filter is multiplied by auser-adjustable gain and then summed together to create a left or right output signal, which is then sent via a DAC to speakers.Each filter output is used to update the signal strength of each filter's output. It is this data that is displayed on the GraphicEqualizer screen.

Filters for each band are designed to overlap across the signal's spectrum. The signal's spectrum can be divided into equallysized band or into bands that increase by a factor of two with each higher frequency band.

% Linear spacing: 6 bands from Dc to FS/2, with FS = 44,100 Hz FcFilters = [ 0 4410 8820 13230 17640 22050 ]; % Octave spacing of band centers: FcFilters = [ 125/2 125 250 500 1000 2000 4000 8000 16000 ];

Whether the bands are equally spaced or logarithmically spaced, the screen is the same, it all depends on how the filters aredesigned and the display library is ignorant of such details.

The Graphic Equalizer Display library supports the user interface to this signal processing:


1-4

1

Left and right band signal strengths are displayed side-by-side. Each frequency band's signal strength is represented by theheight of a column of colored rectangles. On top of each signal strength column is an icon representing the current gain settingfor each band's filter. The library supports user modification of a band's filter gain by moving a gain icon up and down. A special"focus" icon a the bottom of a band's signal strength column shows which band gain can be adjusted.

Note, however, that a complete user interface requires more than just this display. For example, button drivers are needed tosupport user inputs to the application. In the example below, buttons are used to play/pause music and select applicationscreens.

For completeness, let us review a prototype user interface with a Graphic Equalizer to highlight the display features that are notpart of the Graphic Equalizer Display Library. This example uses a demo board with five buttons for user input.


1-5

1

The Graphic Equalizer Display shows each band's signal strength as music is played. Below the equalizer display the currentAlbum Title, Track Title, and elapsed time are displayed. The bottom buttons are used to control how the music is played. Theright hand buttons either move the screen back to some master main menu or advance the screen to one used to begin theadjustment of band filter gains.

Note that only the graphic display is provided by this library. Software for button drivers and displaying the Album title, TrackTitle, and elapsed time are outside the scope of the display library.

A single call to the GRAPHIC_EQUALIZER_Create primitive draws the screen:


1-6

1

The location, size, and number of bands and signal strength bars is user selectable at the time GRAPHIC_EQUALIZER_Createis called.

Here are two additional screens on the same display, created with different numbers of bands and bars:

Pushing Button 2 on our "application" brings the user to a new screen:


1-7

1

This screen allows the user to select a left or right frequency band for gain adjustments to the band's filter. The bottom buttons(<-Band and Band-> allow the user to move the "focus" icon left or right to select the desired frequency band. Then pressing themiddle button (Select Band) moves the user to the next screen, where the gain of the band's filter can be adjusted to increase ordecrease signal strength. Pressing Button 1 or Button 2 returns the user either to the main menu or the previous menu.

The Graphic Equalizer Display primitive

void GRAPHIC_EQUALIZER_ChannelFocus(bool enable, GFX_EQUAL_CHANNEL channel, uint8_t iBand)

Controls the focus icon, turning it on or off, as well as choosing which band is in "focus".

Once a band has been chosen, the user can select the "Select Band" button to move to the final screen:


1-8

1

Here the right hand side buttons are used to move the gain icon up or down, increasing or decreasing the filter's gain. The usercan see from the corresponding behavior of the band's signal strength column how changing the filter's gain affects the band'ssignal strength. When the user is satisfied with the gain adjustments for this band the "Set Gain" button can be pressed to setinto place the filter gains. Then the previous screen is redrawn to allow choosing a different frequency band.


1-9

1

1.2 Resource Requirements The memory and processing requirements for a Graphic Equalizer display are very small. Less than 1 Kwords are needed fromprogram memory and less than 100 words of data memory are needed. Since the refresh rate of any Graphic Equalizer displayon an LCD is 10 to 25 Hz, the processing requirements are inconsequential.

1.2 Resource Requirements Graphics Equalizer Display Library Help

1-10

1

1.3 Release Notes Graphic Equalizer Display Library Version:

0.1 Beta Release Date: 18 November 2013

1.3 Release Notes Graphics Equalizer Display Library Help

1-11

1

1.4 SW License Agreement ---------------------------------------

(c) 2013 Microchip Technology Inc.

---------------------------------------

Microchip licenses this software to you solely for use with Microchip products. The software is owned by Microchip and itslicensors, and is protected under applicable copyright laws. All rights reserved.

SOFTWARE IS PROVIDED "AS IS" MICROCHIP EXPRESSLY DISCLAIMS ANY WARRANTY OF ANY KIND, WHETHEREXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL MICROCHIP BE LIABLE FORANY INCIDENTAL, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, HARM TOYOUR EQUIPMENT, COST OF PROCUREMENT OF SUBSTITUTE GOODS, TECHNOLOGY OR SERVICES, ANY CLAIMSBY THIRD PARTIES (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), ANY CLAIMS FOR INDEMNITY ORCONTRIBUTION, OR OTHER SIMILAR COSTS.

To the fullest extent allowed by law, Microchip and its licensors liability shall not exceed the amount of fees, if any, that you havepaid directly to Microchip to use this software.

MICROCHIP PROVIDES THIS SOFTWARE CONDITIONALLY UPON YOUR ACCEPTANCE OF THESE TERMS.

1.4 SW License Agreement Graphics Equalizer Display Library Help

1-12

1

1.5 Using the Library This library is an adjunct to the Audio Equalizer Filltering Library. It supports a graphic equalizer display based on filtering andsignal strength estimation done by the filtering library. Consult the help file for the library for more information.

1.5.1 Display Overview There are six primitives in the library:

• GRAPHIC_EQUALIZER_DisplayScaleSet - sets the display scaling for signal strength and for filter gain

• GRAPHIC_EQUALIZER_LabelsSet - sets the "Left" and "Right" label text strings and the display font. It can also disable the display of labels.

• GRAPHIC_EQUALIZER_Create - Creates (draws) a graphic equalizer display

• GRAPHIC_EQUALIZER_BandValueUpdate - Updates the signal strength or filter gain for a channel and frequency band

• GRAPHIC_EQUALIZER_BandDisplayRefresh - Refreshes a channel and frequency band column to reflect new values

• GRAPHIC_EQUALIZER_ChannelFocus - Disables or enables the channel focus icon and sets the icon on a channel/band

The number of frequency bands and the number of signal strength bars is determined by arguments to the routineGRAPHIC_EQUALIZER_Create .

The space between adjacent bars on the display is 1/2 bar height in the vertical and 1/2 bar width in the horizontal. So if(Left,Top) is defined by the first two arguments of the call to GRAPHIC_EQUALIZER_Create, the opposite corner's (X,Y)coordinates can be calculated by:

(Right,Bottom) = (Left + 2*W + BarWidth/2, Top + FontPixelHeight + H)

1.5 Using the Library Graphics Equalizer Display Library Help Display Overview

1-13

1

where,

W = NumFreqBands*(3/2)*BarWidth + BarWidth/2

and

H = (Nbars+1)*(3/2)*BarHeight + 1

For the display shown above, FontPixelHeight = 20 pixels. (This information is found in the font bitmap dot C file.

This library can also show band filter gains as an additional icon for each left/right frequency band. The signal strength value andfilter gain value displayed for each frequency band is set by calls to GRAPHIC_EQUALIZER_BandValueUpdate. Displayupdates are initiated by calls to GRAPHIC_EQUALIZER_BandDisplayRefresh.

Typically the user can adjust the filter gain for only single left/right frequency band at a time. To show which band is being gainadjusted there is a "Channel Focus Icon", as seen below for the left-most frequency and of the left stereo channel. Calls to theroutine GRAPHIC_EQUALIZER_ChannelFocus sets which left/right frequency band is in "focus". Note however that the gain forany filter can be adjusted at any time, not just the filter that is in "focus". When there is no frequency band in "focus" the channelfocus icon is not displayed:

The labels for the left and right channels, "Left" and "Right" in the display above, as well as the font used is specified byGRAPHIC_EQUALIZER_LabelsSet. Labels can also be disabled by calling GRAPHIC_EQUALIZER_LabelsSet with nullpointers instead of character strings for the labels.

The Y axis scaling of the display is set by GRAPHIC_EQUALIZER_DisplayScaleSet:

1.5 Using the Library Graphics Equalizer Display Library Help Display Overview

1-14

1

X axis scaling is implied in the frequency band number, from 0,1,..., NumFreqBands-1. Whether frequency bands are equallyspaced on a linear frequency axis or spaced by octaves on a logarithmic frequency axis is hidden from the user. All that isdisplayed is NumFreqBands columns for the left stereo channel and NumFreqBands columns for the right stereo channel.

1.5.2 Configuring The Library GFX_EQUAL_MAX_BANDS

The file graphic_equalizer_config.h configures the maximum number of equalization frequency bands supported(GFX_EQUAL_MAX_BANDS). For the display there is no real limit on the number of frequency bands or the number of signalstrength bars, as long as there are sufficient pixels on the display. However, there is a real limit on the number of frequencybands that comes from the fact that each channel/band is an output of a audio equalizer filter. Sufficient processing power onhost device must be available for the number of filters required.

1.5.3 Fixed Point Data and Mathematics C Language Native Data Types

The C programming language supports integer and floating point data types. It does not support fractional data types. Thus youcan only represent 1/2 as a floating point constant (0.5) but that requires using floating point mathematics. For many embeddedapplications floating point mathematics is too slow and needs too much memory to be of practical use.

1.5 Using the Library Graphics Equalizer Display Library Help Fixed Point Data and Mathematics

1-15

1

Fixed Point Addition and Subtraction

Fixed point (Qm.n or Qn) data types and associated mathematics support fractional data without using floating point. It allows theuse of integer data types instead of floating point. The key idea is to think of fractional data as a pair of numbers, the numeratorand denominator. A signed 16 bit integer ranges from -32768 to +32767. So using 16 bits you can represent 1/2 as16384/32768. Thus 1/2 is represented by M/N, where M = 16384 and N = 32768.

Now the trick comes that we just do integer math using M and keep N hidden (in our heads). Each fixed point data type has animplied numerator (N). For example the Q0.15 16 bit fixed point data type has N = 32768.

Adding fixed point fractions simply means adding the numerators:

1/2 + 1/4 = 16384/32768 + 8192/32768 = ( 16384 + 8192 )/32768 = 24576/32768 = 3/4

So in C you simply add the numerators and keep the denominator (32768) in your head:

1/2 + 1/4 = 16384 + 8192 = 16384 + 8192 = 24576

Fixed Point Data Types

Fixed point data types are defined as typedefs in the Audio Equalizer Filtering library file audio_equalizer_fixedpoint.h.

Each data type is of the form Qm.n, where m is the number of integer bits and n is the number of fractional bits. Thuslibq_q15d16_t is a 32 bit format with 1 one sign bit, 15 integer bits, and 16 fractional bits:

-3---------2---------1---------- 10987654321098765432109876543210 ----____----____----____----____ Siiiiiiiiiiiiiiiffffffffffffffff

With 16 fractional bits the implied denominator N = 65536:

float Xfloat; libq_q15d16_t Xq15d31; Xfloat = Xq15d31/65536.0;

The most common data types are the 16-bit libq_q0d15_t (or libq_q15_t):

-----1---------- 5432109876543210 ----____----____ Sfffffffffffffff

As mentioned above, Q0.15 (or Q15) has an implied N = 32768:

float Xfloat; libq_q15_t Xq15; Xfloat = Xq15/32768.0;

And the 32-bit libq_q0d31_t (or libq_q31_t):

-3---------2---------1---------- 10987654321098765432109876543210 ----____----____----____----____ Sfffffffffffffffffffffffffffffff

Q0.31 (or Q31) has an implied N = 2^31:

float Xfloat; libq_q31_t Xq31; Xfloat = Xq31/((float)2<<31);

1.5 Using the Library Graphics Equalizer Display Library Help Fixed Point Data and Mathematics

1-16

1

Fixed Point Multiplication and Division

Fixed point addition and subtraction is very easy since we just add or subtract numerators. But multiplication and division needsome tweaks to convert integer multiplication and division into fixed point multiplication and division. (PIC32 assembly hasinstructions that do fixed point multiplication/division correctly.) Let's look at multiplying 1/2 * 1/4 = 1/8:

1/2 * 1/4 = 16384/32768 * 8192/32768 = (16384 * 8192)/(32768*32768) = 134,217,728/1,073,7431,824 = 1/8

Ignoring the denominators, and just multiplying the numerators we have:

1/2 * 1/4 = 16384 * 8192 = 16384 * 8192 = 134,217,728

So the first thing you notice is multiplying two 16-bit integers produces a 32-bit integer (16+16 = 32).

So to convert it back into a 16 bit integer, just shift by 16 bits:

1/2 * 1/4 = 16384 * 8192 = 16384 * 8192 = 134,217,728>>16 = 2048

But

1/8 = 4096/32768

So we are off by a factor of two. Thus you have the rule that you must left shift integer multiplication by one bit to producefractional multiplication. Similarly integer division must be right shifted one bit to produce fractional division.

Here's a code snippet that multiplies two Q0d15 numbers:

libq_q15_t A16, B16, C16; libq_q31_t Temp32; Temp32 = A16 * B16; C16 = Temp32>>(16-1);

This example can be simplified since 32 bit integers are assigned to 16 bit by copying the lower 16 bits:

C16 = (A16 * B16)>>(16-1);

Note that this works because C promotes all 16-bit multiplication into 32 bit. But for 32 bit multiplication you have to explicitly castone of the multiplicands into a 64 bit integer:

libq_q31_t A32, B32, C32; libq_q63_t Temp64; Temp64 = A32 * (libq_q63_t)B32; C32 = Temp64>>(32-1);

Or simply:

C32 = (A32 * (lib1_q63_t)B32)>>(32-1);

1.5.4 Application Examples Creating a Graphic Equalizer Display

// Define labels GRAPHIC_EQUALIZER_LabelsSet("Left","Right",(void*)LARGE_FONT); // Signal strength will be measured in RMS Volts, from 0 to 1 // +1 as Q16.16 is 1<<16 GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_SIGNAL_STRENGTH,0,1<<16); // Filter gains will range from -10 dB to +10 dB // +/-10 as Q15.16 is +/-10<<16

1.5 Using the Library Graphics Equalizer Display Library Help Application Examples

1-17

1

GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_FILTER_GAIN,-10<<16,10<<16); // Draw graphic equalizer display GRAPHIC_EQUALIZER_Create( 8, 6, //Xleft,Ytop 8, 4, //BarWidth, BarHeight 8,16);//nBands, nBars

Updating The Display #include "audio_equalizer.h" #include "audio_equalizer_fixedpoint.h" #include "myStereoFilters6x2_Q15.h" #define NBANDS 6 #define NFILTERS 2 uint16_t iBand; libq_q0d15_t XinLeft,XinRight,YoutBand, YoutLeft, YoutRight; libq_q0d15_t bandEnergyDBFS; // Define labels GRAPHIC_EQUALIZER_LabelsSet("Left","Right",(void*)LARGE_FONT); // Signal strength will be measured in RMS Volts in dB re Full scale, -30 dBFS to 0 dBFS GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_SIGNAL_STRENGTH,-30<<16,0<<16); // Filter gains will range from -10 dB to +10 dB GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_FILTER_GAIN,-10<<16,10<<16); // Draw graphic equalizer display GRAPHIC_EQUALIZER_Create( 8, 6, //Xleft,Ytop 8, 4, //BarWidth, BarHeight 8,16);//nBands, nBars // Setup to measure signal energy in dB re Full Scale (dBFS) AUDIO_EQUALIZER_BandEnergySumsInit(2*NBANDS,BAND_ENERGY_RMS_DBFS); while ( 1 ) { if ( bGotInput() ) { // Get XinLeft,XinRight // Execute equalizer filtering and signal strength updates. // See Audio Equalizer Filtering Library for example code to implement this. FilterInputPlusEnergy(XinLeft,XinRight,&YoutLeft,&YoutRight); // Send YoutRight,YoutRight }//end if ( bGotInput ) if ( bUpdateDisplay() ) { // Memory update for each frequency band, left and right channels for ( iBand = 0; iBand < NBANDS; iBand++ ) { // Left channel: Update signal strength bandEnergyDBFS = AUDIO_EQUALIZER_BandEnergyGetQ15(iBand,true); GRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_SIGNAL_STRENGTH,GFX_EQUAL_CHANNEL_LEFT,iBand,bandEnergyDBFS); // Right Channel: Update signal strength bandEnergyDBFS = AUDIO_EQUALIZER_BandEnergyGetQ15(iBand+NBANDS,true); GRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_SIGNAL_STRENGTH,GFX_EQUAL_CHANNEL_RIGHT,iBand,bandEnergyDBFS); }//end for ( iBand = 0; iBand < NBANDS; iBand++ )


1-18

1

// Refresh entire display at same time GRAPHIC_EQUALIZER_BandDisplayRefresh(GFX_EQUAL_CHANNEL_LEFT, -1); // Refresh all bands for Left GRAPHIC_EQUALIZER_BandDisplayRefresh(GFX_EQUAL_CHANNEL_RIGHT,-1); // Refresh all bands for Right }//end if ( bUpdateDisplay ) }//end while ( 1 )

Adjusting Band Filter Gains #include "audio_equalizer.h" #include "audio_equalizer_fixedpoint.h" #include "myStereoFilters6x2_Q15.h" #define NBANDS 6 #define NFILTERS 2 EQUALIZER_FILTER *pMyFilters; GFX_EQUAL_CHANNEL myChannel; uint8_t myBand; int16_t iGainAdj; libq_q0d15_t displayGainAdjQ15; while ( !GainAdjDone ) { switch ( gainAdjStateGet() ); { case GET_CHANNEL: myChannel = GetUserChannel(); if ( GFX_EQUAL_CHANNEL_LEFT == myChannel ) { pMyFilters = myFiltersLeft; } else { pMyFilters = myFiltersRight; } break; case GET_BAND: myBand = GetUserBand(); GRAPHIC_EQUALIZER_ChannelFocus(true,myChannel,myBand); bandGain = // Base all gain adjustments on this old value AUDIO_EQUALIZER_FilterGainGetQ15(pMyFilters, NBANDS, NFILTERS, myBand, NFILTERS ); break; case APPLY_GAIN_ADJ: iGainAdj = GetUserGainAdj(); // -50 dB <= iGainAdj <= +50 dB displayGainAdjQ15 = 327*iGainAdj + 16384; GRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_FILTER_GAIN,channel,myBand,displayGainAdjQ15); adjBandGain = AUDIO_EQUALIZER_FilterGainAdjustQ15(bandGain,iGainAdj); AUDIO_EQUALIZER_FilterGainSetQ15(pMyFilters, NBANDS, NFILTERS, myBand, NFILTERS, adjBandGain ); GRAPHIC_EQUALIZER_BandDisplayRefresh(myChannel,myBand); break;


1-19

1

case GAIN_ADJUST_DONE: GRAPHIC_EQUALIZER_ChannelFocus(false,myChannel,myBand); GainAdjDone = true; break; }//end switch ( gainAdjStateGet() ) }//end while ( !GainAdjustDone )


1-20

1

1.6 Library Interface C Routines

Name DescriptionGRAPHIC_EQUALIZER_LabelsSet Sets left/right channel label strings and the font to be used in writing

the labels.

GRAPHIC_EQUALIZER_DisplayScaleSet Sets the display scaling for signal strength or filter gain, allowing the conversion of data value into pixels on the display.

GRAPHIC_EQUALIZER_Create Creates a Graphic Equalizer display on the application's LCD screen.

GRAPHIC_EQUALIZER_BandValueUpdate Update left/right channel and frequency band with new signal energy or filter gain

GRAPHIC_EQUALIZER_BandDisplayRefresh Refreshes the display for given channel and band

GRAPHIC_EQUALIZER_ChannelFocus "Focus" graphic equalizer on specified channel/iBand.

Data Types

Name DescriptionGFX_EQUAL_CHANNEL Supports audio channels for stereo music.

GFX_EQUAL_MAX_BANDS Defines the maximum number of bands supported.

GFX_EQUAL_VALUE_TYPE Each graphic equalizer band can show signal strength (energy) and filter gain values. This enumeration distinquishes between the two in APIs.

Fixed Point Data Types

Name Descriptionlibq_q0d15_t Typedef for the Q0.15 fixed point data type.

libq_q15_t Typedef for the Q0.15 fixed point data type.

libq_q0d16_t Typedef for the Q0.16 fixed point data type.



libq_q15d16_t Typedef for the Q15.16 fixed point data type

libq_q16d15_t Typedef for the Q16d15 fixed point data type


libq_q63_t Typedef for the Q0.63 fixed point data type

Description

1.6.1 C Routines

1.6 Library Interface Graphics Equalizer Display Library Help C Routines

1-21

1

1.6.1.1 GRAPHIC_EQUALIZER_LabelsSet Function C

void GRAPHIC_EQUALIZER_LabelsSet( char * pLeftLabel, char * pRightLabel, void * pLabelFont);

Description

Sets left/right channel label strings and the font to be used in writing the labels. To disable labels pass null pointers as argumentsfor the text labels.

Preconditions

None.

Parameters

Parameters DescriptionpLeftLabel Character string defining left channel label.

pRightLabel Character string defining right channel label.

pLabelFont Pointer to label font.

Returns

None.

Remarks

None.

Example #include "../../Graphics/Fonts/prototype/Prototype16pt.h" GRAPHIC_EQUALIZER_LabelsSet("Left","Right",(void*)&Prototype_16); GRAPHIC_EQUALIZER_Create(10, 10, //Left,Top 8, 4, //BarWidth,BarHeight 8, 16);//NumFreqBands,NumBars . . . // Disable labels, rest of display stays the same. #include "../../Graphics/Fonts/prototype/Prototype16pt.h" GRAPHIC_EQUALIZER_LabelsSet(NULL,NULL,(void*)&Prototype_16); GRAPHIC_EQUALIZER_Create(10, 10+GetTextHeight((void*)&Prototype_16), //Left,Top 8, 4, //BarWidth,BarHeight 8, 16);//NumFreqBands,NumBars

1.6.1.2 GRAPHIC_EQUALIZER_DisplayScaleSet Function C

void GRAPHIC_EQUALIZER_DisplayScaleSet( GFX_EQUAL_VALUE_TYPE type, libq_q15d16_t minValue, libq_q15d16_t maxValue);

Description

Sets the display scaling for signal strength or filter gain, allowing the conversion of data value into pixels on the display. The data


1-22

1

range of [minValue,maxValue] is translated to a pixel range, where minValue corresponds to the bottom of the display maxValuecorresponds to the top.

Preconditions

None.

Parameters

Parameters Descriptiontype GFX_EQUAL_SIGNAL_STRENGTH (for signal energy/amplitude) or

GFX_EQUAL_FILTER_GAIN (for filter gain)

minValue minimum value, corresponding to the bottom of the display

maxValue maximum value, corresponding to the top of the display

Returns

None.

Remarks

The default scaling for signal strength is -30 dBFs to 0 dBFS. The default scaling for filter gain is -20 dB to 20 dB. These scalingswill be used unless new scaling values are set by calling this function.

Example // Signal strength will be measured in RMS Volts, from 0 to 1 // +1 as Q16.16 is 1<<16 GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_SIGNAL_STRENGTH,0,1<<16); // Filter gains will range from -10 dB to +10 dB // +/-10 as Q15.16 is +/-10<<16 GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_FILTER_GAIN,-10<<16,10<<16);

1.6.1.3 GRAPHIC_EQUALIZER_Create Function C

void GRAPHIC_EQUALIZER_Create( int16_t left, int16_t top, int16_t bWidth, int16_t bHeight, uint8_t nBands, uint8_t nBars);

Description

Creates a Graphic Equalizer display on the application's LCD screen.

Preconditions

InitGraph has been called to initialize the graphics library. GRAPHIC_EQUALIZER_LabelsSet has been called to define labels.

Parameters

Parameters Descriptionleft left-most (X) pixel coordinate of the equalizer object

top top-most (Y) pixel coordinate of the equalizer object

bWidth equalizer channel bar width, in pixels

bHeight equalizer bar height, in pixels

nBands number of bands (columns)


1-23

1

nBars number of bars (rows) in "LED" display of band signal energy

Returns

None.

Remarks

Default colors are defined in the file graphic_equalizer_config.h:

Example #include "../../Graphics/Fonts/prototype/Prototype16pt.h" GRAPHIC_EQUALIZER_LabelsSet("Left","Right",(void*)&Prototype_16); GRAPHIC_EQUALIZER_Create(10, 10, //Left,Top 8, 4, //BarWidth,BarHeight 8, 16);//NumFreqBands,NumBars

1.6.1.4 GRAPHIC_EQUALIZER_BandValueUpdate Function C

void GRAPHIC_EQUALIZER_BandValueUpdate( GFX_EQUAL_VALUE_TYPE type, GFX_EQUAL_CHANNEL channel, uint8_t iBand, libq_q15d16_t bandValue);

Description

Update left/right channel and frequency band with new signal energy or filter gain

Preconditions

GRAPHIC_EQUALIZER_Create has been called

Parameters

Parameters Descriptiontype GFX_EQUAL_SIGNAL_STRENGTH (for signal energy/amplitude) or

GFX_EQUAL_FILTER_GAIN (for filter gain)

channel GFX_EQUAL_CHANNEL_LEFT or GFX_EQUAL_CHANNEL_RIGHT

iBand channel band to be updated, 0 <= iBand < nBands used in GRAPHIC_EQUALIZER_Create

bandValue Signal strength or filter gain

Returns

None.

Remarks

Call GRAPHIC_EQUALIZER_BandDisplayRefresh to update the display.

To transform signal energy or filter gain into Q0.15 values see GRAPHIC_EQUALIZER_Scale.

Example #include "audio_equalizer.h" #include "audio_equalizer_fixedpoint.h" #include "myStereoFilters6x2_Q15.h" #define NBANDS 6 #define NFILTERS 2


1-24

1

uint16_t iBand; libq_q0d15_t XinLeft,XinRight,YoutBand, YoutLeft, YoutRight; libq_q15d16_t bandEnergyDBFS; // Define labels GRAPHIC_EQUALIZER_LabelsSet("Left","Right",(void*)LARGE_FONT); // Signal strength will be measured in RMS Volts in dB re Full scale, -30 dBFS to 0 dBFS GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_SIGNAL_STRENGTH,-30<<16,0<<16); // Filter gains will range from -10 dB to +10 dB GRAPHIC_EQUALIZER_DisplayScaleSet(GFX_EQUAL_FILTER_GAIN,-10<<16,10<<16); // Draw graphic equalizer display GRAPHIC_EQUALIZER_Create( 8, 6, //Xleft,Ytop 8, 4, //BarWidth, BarHeight 8,16);//nBands, nBars // Setup to measure signal energy in dB re Full Scale (dBFS) AUDIO_EQUALIZER_BandEnergySumsInit(2*NBANDS,BAND_ENERGY_RMS_DBFS); while ( 1 ) { if ( bGotInput() ) { // Get XinLeft,XinRight // Execute equalizer filtering and signal strength updates. // See Audio Equalizer Filtering Library for example code to implement this. FilterInputPlusEnergy(XinLeft,XinRight,&YoutLeft,&YoutRight); // Send YoutRight,YoutRight }//end if ( bGotInput ) if ( bUpdateDisplay() ) { // Update Display for ( iBand = 0; iBand < NBANDS; iBand++ ) { // Left channel bandEnergyDBFS = AUDIO_EQUALIZER_BandEnergyGetQ15(iBand,true); GRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_SIGNAL_STRENGTH,GFX_EQUAL_CHANNEL_LEFT,iBand,bandEnergyDBFS); // Right Channel bandEnergyDBFS = AUDIO_EQUALIZER_BandEnergyGetQ15(iBand+NBANDS,true); GRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_SIGNAL_STRENGTH,GFX_EQUAL_CHANNEL_RIGHT,iBand,bandEnergyDBFS); }//end for ( iBand = 0; iBand < NBANDS; iBand++ ) GRAPHIC_EQUALIZER_BandDisplayRefresh(GFX_EQUAL_CHANNEL_LEFT, -1); // Refresh display for left channel, all bands GRAPHIC_EQUALIZER_BandDisplayRefresh(GFX_EQUAL_CHANNEL_RIGHT,-1); // Refresh display for right channel, all bands }//end if ( bUpdateDisplay ) }//end while ( 1 )

1.6.1.5 GRAPHIC_EQUALIZER_BandDisplayRefresh Function C

void GRAPHIC_EQUALIZER_BandDisplayRefresh( GFX_EQUAL_CHANNEL channel,


1-25

1

int8_t iBand);

Description

Refreshes the display for given channel and band. Redraws the signal strength bars and the band filter gain icon when thesevalues have changed, otherwise no display changes are made.

Preconditions


Parameters

Parameters Descriptionchannel GFX_EQUAL_CHANNEL_LEFT or GFX_EQUAL_CHANNEL_RIGHT

iBand channel band to be refreshed on the display, 0 <= iBand < nBands used in GRAPHIC_EQUALIZER_Create. If iBand < 0 then all frequency bands for the channel are refreshed.

Returns

None.

Remarks

None.

Example

See GRAPHIC_EQUALIZER_BandValueUpdate.

1.6.1.6 GRAPHIC_EQUALIZER_ChannelFocus Function C

void GRAPHIC_EQUALIZER_ChannelFocus( bool enable, GFX_EQUAL_CHANNEL channel, uint8_t iBand);

Description

"Focus" graphic equalizer on specified channel/iBand. Next get user commands to update filter gain, then callGRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_FILTER_GAIN,...) to update commanded gain displayed on screen.Finally update corresponding filter gain to change filter output.

Preconditions


Parameters

Parameters Descriptionenable true to enable channel focus, false to disable it

channel GFX_EQUAL_CHANNEL_LEFT or GFX_EQUAL_CHANNEL_RIGHT

iBand band that will have gain adjustments, 0 <= iBand < nBands used in GRAPHIC_EQUALIZER_Create

Returns

None.


1-26

1

Remarks

None.

Example #include "audio_equalizer.h" #include "audio_equalizer_fixedpoint.h" #include "myStereoFilters6x2_Q15.h" #define NBANDS 6 #define NFILTERS 2 EQUALIZER_FILTER *pMyFilters; GFX_EQUAL_CHANNEL myChannel; uint8_t myBand; int16_t iGainAdj; libq_q0d15_t displayGainAdjQ15; while ( !GainAdjDone ) { switch ( gainAdjStateGet() ); { case GET_CHANNEL: myChannel = GetUserChannel(); if ( GFX_EQUAL_CHANNEL_LEFT == myChannel ) { pMyFilters = myFiltersLeft; } else { pMyFilters = myFiltersRight; } break; case GET_BAND: myBand = GetUserBand(); GRAPHIC_EQUALIZER_ChannelFocus(true,myChannel,myBand); bandGain = // Base all gain adjustments on this old value AUDIO_EQUALIZER_FilterGainGetQ15(pMyFilters, NBANDS, NFILTERS, myBand, NFILTERS ); break; case APPLY_GAIN_ADJ: iGainAdj = GetUserGainAdj(); // -50 dB <= iGainAdj <= +50 dB displayGainAdjQ15 = 327*iGainAdj + 16384; GRAPHIC_EQUALIZER_BandValueUpdate(GFX_EQUAL_FILTER_GAIN,channel,myBand,displayGainAdjQ15); adjBandGain = AUDIO_EQUALIZER_FilterGainAdjustQ15(bandGain,iGainAdj); AUDIO_EQUALIZER_FilterGainSetQ15(pMyFilters, NBANDS, NFILTERS, myBand, NFILTERS, adjBandGain ); GRAPHIC_EQUALIZER_BandDisplayRefresh(myChannel,myBand); break; case GAIN_ADJUST_DONE: GRAPHIC_EQUALIZER_ChannelFocus(false,myChannel,myBand); GainAdjDone = true; break; }//end switch ( gainAdjStateGet() ) }//end while ( !GainAdjustDone )

1.6 Library Interface Graphics Equalizer Display Library Help Data Types

1-27

1

1.6.2 Data Types

1.6.2.1 GFX_EQUAL_CHANNEL Enumeration C

typedef enum { GFX_EQUAL_CHANNEL_LEFT, GFX_EQUAL_CHANNEL_RIGHT, GFX_EQUAL_CHANNEL_CENTER, GFX_EQUAL_MAX_CHANNELS} GFX_EQUAL_CHANNEL;

Description

Graphic Equalizer Channel Enumeration

Supports audio channels for stereo music.

Members

Members DescriptionGFX_EQUAL_CHANNEL_LEFT Left stereo channel

GFX_EQUAL_CHANNEL_RIGHT Right stereo channel

GFX_EQUAL_CHANNEL_CENTER Center (subwoofer channel, not yet implemented)

Remarks

None.

1.6.2.2 GFX_EQUAL_MAX_BANDS Macro C

#define GFX_EQUAL_MAX_BANDS 8

Description

Graphic Equalizer Maximum Number of Bands

Defines the maximum number of bands supported.

Remarks

None.

1.6.2.3 GFX_EQUAL_VALUE_TYPE Enumeration C

typedef enum { GFX_EQUAL_SIGNAL_STRENGTH, GFX_EQUAL_FILTER_GAIN} GFX_EQUAL_VALUE_TYPE;

1.6 Library Interface Graphics Equalizer Display Library Help Data Types

1-28

1

Description

Graphic Equalizer Channel Value Type Enumeration

Each graphic equalizer band can show signal strength (energy) and filter gain values. This enumeration distinquishes betweenthe two in APIs.

Members

Members DescriptionGFX_EQUAL_SIGNAL_STRENGTH Signal strength/energy/amplitude

GFX_EQUAL_FILTER_GAIN Band filter gain

Remarks

None.

1.6.3 Fixed Point Data Types

1.6.3.1 libq_q0d15_t Type C

typedef int16_t libq_q0d15_t;

Description

Fixed Point Integer Typedef

Typedef for the Q0.15 fixed point data type into a 16 bit signed integer. Values for this data type are in the range [-1,+1), i.e. -1<= x < +1.

Remarks

This data type has one sign bit and 15 fractional bits in a 16 bit word.


Example float Xfloat; libq_q0d15_t Xq0d15; Xfloat = Xq0d15/32768.0;

1.6.3.2 libq_q15_t Type C

typedef libq_q0d15_t libq_q15_t;

Description


1.6 Library Interface Graphics Equalizer Display Library Help Fixed Point Data Types

1-29

1


Remarks



Example float Xfloat; libq_q15_t Xq15; Xfloat = Xq15/32768.0;


typedef uint16_t libq_q0d16_t;

Description


Typedef for the Q0.16 fixed point data type into a 16 bit unsigned integer. Values for this data type are in the range [0,+1], i.e. -1<= x <= +1.

Remarks

This data type has no sign bit and 16 fractional bits in a 16 bit word.

-----1---------- 5432109876543210 ----____----____ ffffffffffffffff




Description



Remarks



1-30

1


Example float Xfloat; libq_q0d31_t Xq0d31; Xfloat = Xq0d31/((float)2<<31);



Description



Remarks



Example float Xfloat; libq_q31_t Xq31; Xfloat = Xq31/((float)2<<31);



Description


Typedef for the Q15.16 fixed point data type into 32 bit signed integer Values for this data type are in the range [-32768,+32768),i.e. -32768 <= x < +32768.

Remarks

This data type has one sign bit, 15 integer bits, and 16 fractional bits.

-3---------2---------1---------- 10987654321098765432109876543210 ----____----____----____----____ Siiiiiiiiiiiiiiiffffffffffffffff

Example float Xfloat; libq_q15d16_t Xq15d31;


1-31

1

Xfloat = Xq15d31/65536.0;



Description


Typedef for the Q16d15 fixed point data type into a 32 bit signed integer Values for this data type are in the range[-65536,+65536), i.e. -65536 <= x < +65536.

Remarks

This data type has one sign bit, 16 integer bits, and 15 fractional bits.

-3---------2---------1---------- 10987654321098765432109876543210 ----____----____----____----____ Siiiiiiiiiiiiiiiifffffffffffffff




Description



Remarks

This data type has one sign bit and 63 fractional bits.

---6---------5---------4---------3---------2---------1---------- 3210987654321098765432109876543210987654321098765432109876543210 Sfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff



Description




1-32

1

Remarks

This data type has one sign bit and 63 fractional bits.

---6---------5---------4---------3---------2---------1---------- 3210987654321098765432109876543210987654321098765432109876543210 Sfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff


1-33

1

1.7 Files Files

Name Descriptionaudio_equalizer_fixedpoint.h Audio Equalizer (DSP) fixed point typedefs.

graphic_equalizer.h Supports graphic equalizer display.

graphic_equalizer_config.h Supports graphic equalizer display by defining various display colors

1.7.1 audio_equalizer_fixedpoint.h Audio Equalizer Library Fixedpoint Typedefs

Signed fixed point types are defined as follows:

Qn.m where:

• n is the number of data bits to the left of the radix point

• m is the number of data bits to the right of the radix point

• a signed bit is implied

Unique variable types for fractional representation are also defined:

Exact Name # Bits Required Type Q0.15 (Q15) 16 libq_q0d15_t Q0.31 (Q31) 32 libq_q0d31_t

Types

Name Descriptionlibq_q0d15_t Typedef for the Q0.15 fixed point data type.






libq_q16d15_t Typedef for the Q16d15 fixed point data type


libq_q63_t Typedef for the Q0.63 fixed point data type

File Name

audio_equalizer_fixedpoint.h

Company

Microchip Technology Inc.

1.7 Files Graphics Equalizer Display Library Help graphic_equalizer.h

1-34

1

1.7.2 graphic_equalizer.h Graphic Equalizer Interface Header File

Supports graphic equalizer display, with primitives that display frequency band signal energy and filter gain. It is used inconjuction with the Audio Equalizer Filtering Library (audio_equalizer.h).

Enumerations

Name DescriptionGFX_EQUAL_CHANNEL Supports audio channels for stereo music.

GFX_EQUAL_VALUE_TYPE Each graphic equalizer band can show signal strength (energy) and filter gain values. This enumeration distinquishes between the two in APIs.

Functions

Name DescriptionGRAPHIC_EQUALIZER_BandDisplayRefresh Refreshes the display for given channel and band

GRAPHIC_EQUALIZER_BandValueUpdate Update left/right channel and frequency band with new signal energy or filter gain

GRAPHIC_EQUALIZER_ChannelFocus "Focus" graphic equalizer on specified channel/iBand.

GRAPHIC_EQUALIZER_Create Creates a Graphic Equalizer display on the application's LCD screen.

GRAPHIC_EQUALIZER_DisplayScaleSet Sets the display scaling for signal strength or filter gain, allowing the conversion of data value into pixels on the display.

GRAPHIC_EQUALIZER_LabelsSet Sets left/right channel label strings and the font to be used in writing the labels.

File Name

graphic_equalizer.h

Company


1.7.3 graphic_equalizer_config.h Graphic Equalizer Interface Header File

Supports graphic equalizer display, with primitives that display frequency band signal energy and filter gain. It is used inconjuction with the Audio Equalizer Filtering Library (audio_equalizer.h).

Macros

Name DescriptionGFX_EQUAL_MAX_BANDS Defines the maximum number of bands supported.

File Name

graphic_equalizer_config.h

1.7 Files Graphics Equalizer Display Library Help graphic_equalizer_config.h

1-35

1

Company


1.7 Files Graphics Equalizer Display Library Help graphic_equalizer_config.h

1-36

1

Index

AApplication Examples 1-17

audio_equalizer_fixedpoint.h 1-34

CConfiguring The Library 1-15

DDisplay Overview 1-13

FFiles 1-34

Fixed Point Data and Mathematics 1-15

GGFX_EQUAL_CHANNEL enumeration 1-28

GFX_EQUAL_MAX_BANDS macro 1-28

GFX_EQUAL_VALUE_TYPE enumeration 1-28

Graphic Equalizer Display Library 1-1

graphic_equalizer.h 1-35

GRAPHIC_EQUALIZER_BandDisplayRefresh function 1-25

GRAPHIC_EQUALIZER_BandValueUpdate function 1-24

GRAPHIC_EQUALIZER_ChannelFocus function 1-26

graphic_equalizer_config.h 1-35

GRAPHIC_EQUALIZER_Create function 1-23

GRAPHIC_EQUALIZER_DisplayScaleSet function 1-22

GRAPHIC_EQUALIZER_LabelsSet function 1-22

IIntroduction 1-2

Llibq_q0d15_t type 1-29

libq_q0d16_t type 1-30



libq_q15_t type 1-29





Library Interface 1-21

RRelease Notes 1-11

Resource Requirements 1-10

SSW License Agreement 1-12

UUsing the Library 1-13

2 Graphics Equalizer Display Library Help

a

Graphics Equalizer Display Library Helpww1.microchip.com/downloads/en//softwarelibrary/pic32 audio...

Documents

Transcript of Graphics Equalizer Display Library Helpww1.microchip.com/downloads/en//softwarelibrary/pic32 audio...