Colour targets: Revert an optimisation from almost 18 months ago that actually turned...
[Rockbox.git] / docs / PLUGIN_API
blobfeba0868fb7a6c9020cb5c28fe25acfa65711850
1 $Id$
2                __________               __   ___.
3      Open      \______   \ ____   ____ |  | _\_ |__   _______  ___
4      Source     |       _//  _ \_/ ___\|  |/ /| __ \ /  _ \  \/  /
5      Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
6      Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
7                        \/            \/     \/    \/            \/
9                             Plugin API summmary
11 Plugin API Version 26
12 (backwards compability up to version 25)
14 Info: To get the latest plugin api specs:
15 look at struct plugin_api in apps/plugin.h
16 (and apps/plugins/helloworld.c for an example)
18 Plugin Skeleton
19 ===============
21 #include "plugin.h"
23 static struct plugin_api* rb;
25 //plugin entry point
26 enum plugin_status plugin_start(struct plugin_api* api, void* parameter)
28     TEST_PLUGIN_API(api);
29     (void)parameter;
30     rb = api;
31     
32     //insert your code here
33     
34     return PLUGIN_OK;
37 to call a function, use the plugin_api structure this way :  rb->function()
39 Plugin Internals
40 ================
42   int version;
44      Plugin version number.
46   int plugin_test(int api_version, int model, int memsize);
48      This function is called by the TEST_PLUGIN_API() macro to test
49      compability of the plugin with current software.
50      Returns PLUGIN_OK if plugin is supported.
51      Returns PLUGIN_WRONG_API_VERSION if plugin version isn't compatible.
52      Returns PLUGIN_WRONG_MODEL if the model or memsize is wrong.
54 LCD
55 ===
57   Generic
58   -------
60     Most LCD functions are specific for which output we work with, due to the
61     huge differences.
63     void lcd_clear_display(void);
64       
65       Clear the whole display
66    
67     void backlight_on(void);
68       
69       Turn the backlight on
70    
71     void backlight_off(void);
72       
73       Turn the backlight off
74    
75     void splash(int ticks, bool center, char *fmt, ...);
76       
77       Display a formated string in a box durring time ticks. If center is
78       FALSE, the display is left justified. If center is TRUE, the display
79       is centered horizontaly and verticaly. The string is formated as with
80       the printf function.
81       (There are HZ ticks per second)
82    
83     void lcd_puts(int x, int y, const unsigned char *string);
84       
85       Write a string at given character position.
86    
87     void lcd_puts_scroll(int x, int y, unsigned char* string);
88       
89       Print a scrolling string at screen coordinates (x,y). The scrolling
90       style is STYLE_DEFAULT.
91    
92     void lcd_stop_scroll(void);
93       
94       Stop all scrolling lines on the screen.
95    
96     void lcd_set_contrast(int val);
97       
98       Set the screen contrast. Argument val should be a value between
99       MIN_CONTRAST_SETTING and MAX_CONTRAST_SETTING.
101   Recorder
102   --------
104     All the functions operate on a display buffer. You make the buffer get
105     shown on screen by calling lcd_update().
107     void lcd_update(void);
108    
109        Update the LCD according to the internal buffer.
111     void lcd_update_rect(int x, int y, int width, int height);
113        Update the given rectangle to the LCD. Give arguments measured in
114        pixels. Notice that the smallest vertical resolution in updates that the
115        hardware supports is even 8 pixels. This function will adjust to those.
117     void lcd_setfont(int font);
118    
119        Set default font
120       
121     struc font* font_get(int font);
123        Return a pointer to an incore font structure. If the requested font
124        isn't loaded/compiled-in, decrement the font number and try again.
125       
126     void lcd_putsxy(int x, int y, const unsigned char *string);
127    
128        Put a string at given coordinates.
129    
130     void lcd_puts_style(int x, int y, const unsigned char *str, int style);
132        Put a string at given coordinates. Intger style can be STYLE_DEFAULT
133        for black text display or STYLE_INVERT for white text display.
134       
135     void lcd_puts_scroll_style(int x, int y, unsigned char* string, int style);
136   
137       Same as lcd_puts_style and scrolling is enabled.
138       {new in plugin API version 26}
139       
140     void lcd_bitmap(const unsigned char *src, int x, int y, int width,
141                     int height, bool clear);
142    
143        Put a bitmap at given coordinates. If clear is true, the area is
144        cleared before the bitmap is put.
145        Element src[i] is the binary representation of column number i of
146        the bitmap read from bottom to top.
147    
148     void lcd_clearrect(int x, int y, int width, int height);
149    
150        Clear a rectangle area.
151    
152     void lcd_fillrect(int x, int y, int width, int height);
153    
154        Fill a rectangle area.
155       
156     void lcd_drawrect(int x, int y, int width, int height);
157    
158        Draw a rectangle.
159     
160     void lcd_invertrect(int x, int y, int width, int height);
161    
162        Revert the graphics of the given area.
163       
164     void lcd_drawline(int x1, int y1, int x2, int y2);
165    
166        Draw a line between the coordinates.
167       
168     void lcd_clearline(int x1, int y1, int x2, int y2);
169    
170        Clear a line between two coordinates.
171       
172     void lcd_drawpixel(int x, int y);
173    
174        Draw a pixel on the given coordinate.
175       
176     void lcd_clearpixel(int x, int y);
177    
178        Clear the pixel at the given coordinate.
179       
180     int lcd_getstringsize(const unsigned char *str, int *w, int *h);
182        Get the height and width of string str as it would appear on display.
183        Return value is the width.
184       
185     void scrollbar(int x, int y, int width, int height, int items,
186                    int min_shown, int max_shown, int orientation);
187       
188        Print a scroll bar at coordinates (x,y) of size width*height.
189        orientation can be VERTICAL for a vertical scroll bar or anything else
190        for a horizontal scroll bar.
191        Item is the total number of items which the scroll bar refers to,
192        min_show the rank of the first item displayed and max_show the 
193        rank of the last displayed item.
194       
195     void checkbox(int x, int y, int width, int height, bool checked);
197        Draw a checkbox area. If checked is TRUE, the checkbox is drawn
198        checked !
199       
200     void lcd_blit(unsigned char* p_data, int x, int y, int width,
201                   int height, int stride);
202    
203        ??? (see firmware/drivers/lcd-recorder.c:168)
204       
205     void lcd_roll(int pixels);
206    
207        Rolls up the lcd display by the specified amount of lines.
208        Lines that are rolled out over the top of the screen are rolled in
209        from the bottom again. This is a hardware remapping only and all
210        operations on the lcd are affected.
211        The screen is rolled up of pixel lines. The value must be between
212        0 and LCD_HEIGHT.
213        [Not for simulator]
215   Player
216   ------
218     void lcd_define_pattern(int pat, char *pattern);
219    
220        Define a custom pattern of index pat. char *pattern is a 8x8 pixel
221        bitmap.
223     unsigned char lcd_get_locked_pattern(void);
225        Get a locked pattern index.
226        (see firmware/drivers/lcd-player.c:382)
227       
228     void lcd_unlock_pattern(unsigned char pat);
230        Unlock pattern of index pat.
231       
232     void lcd_putc(int x, int y, unsigned char ch);
234        Put character c at coordinates (x,y).
235       
236     void lcd_put_cursor(int x, int y, char cursor_char);
238        Put cursor at coordinated (x,y).
239        See firmware/export/lcd.h for possible cursor_char values.
240       
241     void lcd_remove_cursor(void);
243        Remove the cursor from the screen.
244       
245     void lcd_icon(int icon, bool enable);
247        ??? (see firmware/drivers/lcd-player.c:463)
250 Buttons
251 =======
253   These functions work the same regardless of which keypad you have, but they
254   return a different set of values. Note that the Recorder keypad has 10
255   keys, while the Player keypad only features 6.
257   Possible return values can be found in the firmware/export/button.h file.
259   int button_get(bool block);
261      Returns a bitmask for which keys were pressed. If 'block' is set TRUE it
262      won't return until a key is pressed.
264   int button_get_w_tmo(int ticks);
266      Wait for a key press for ticks ticks. (There are HZ ticks per second)
267      Returns a bitmask for which keys were pressed. If no key was pressed,
268      return BUTTON_NONE.
270   int button_status(void);
272      Returns a bitmask for which keys are currently pressed.
274   void button_clear_queue(void);
276      Empty the button queue.
277   
279 Files
280 =====
282   (These functions are POSIX look-alikes)
284   int open(const char *pathname, int flags);
286      The open() function establishes the connection between a file and a file
287      descriptor. It creates an open file description that refers to a file
288      and a file descriptor that refers to that open file description. The file
289      descriptor is used by other I/O functions to refer to that file.
291   ssize_t read(int fd, void *buf, size_t count);
293      The read() function attempts to read count bytes from the file associated
294      with the open file descriptor, fd, into the buffer pointed to by buf.
296   off_t lseek(int fd, off_t offset, int whence);
298      The lseek() function sets the file pointer associated with the open file
299      descriptor specified by fd as follows:
301         o  If whence is SEEK_SET, the pointer is set to offset bytes.
303         o  If whence is SEEK_CUR,  the  pointer  is  set  to  its
304            current location plus offset.
306         o  If whence is SEEK_END, the pointer is set to the  size
307            of the file plus offset.
309   int creat(const char *pathname, mode_t mode)
311      Create a file with mode O_RDONLY, O_WRONLY or O_RDWR. Returns the
312      file descriptor associated to this file.
314   ssize_t write(int fd, const void *buf, size_t count);
316      Write writes up to count bytes to the file referenced by the file
317      descriptor fd from the buffer starting at buf.
319   int close(int fd);
321      The close() function will deallocate the file descriptor indicated by
322      fd.  To deallocate means to make the file descriptor available for
323      return by subsequent calls to open() or other functions that allocate
324      file descriptors.
325      Returns 0 upon success.
327   int rename(const char *path, const char *newname);
329      The rename() function changes the name of a file. The path argument
330      points to the pathname of the file to be renamed. The newname argument
331      points to the new pathname of the file.
333   int remove(const char *pathname);
335      remove() deletes a name from the filesystem.  It calls unlink for files,
336      and rmdir for directories.
338   int ftruncate(int fd, off_t length);
340      Truncate file to the specified length.
342   int filesize(int fd);
344      Returns size of a file. Upon error, returns -1.
346   int fdprintf(int fd, const char *fmt, ...);
348      Write a formated string in the fd.
349      Returns the number of characters writen to file.
350      Returns a negative value upon error.
352   int read_line(int fd, char* buffer, int buffer_size);
354      Read (up to) a line of text from fd into buffer and return number of bytes
355      read (which may be larger than the number of bytes stored in buffer). If 
356      an error occurs, -1 is returned (and buffer contains whatever could be 
357      read). A line is terminated by a LF char. Neither LF nor CR chars are 
358      stored in buffer.    
360   int settings_parseline(char* line, char** name, char** value);
362      Parse a line from a configuration file. The line format is: 
363      name: value
364      Any whitespace before setting name or value (after ':') is ignored.
365      A # as first non-whitespace character discards the whole line.
366      Function sets pointers to null-terminated setting name and value.
367      Returns false if no valid config entry was found
369   int ata_sleep(void)
371      Give the disk some rest.
372      [Not for simulator]
375 Directories
376 ===========
378   DIR *opendir(const char *name);
380      The opendir() function opens a directory stream corresponding to the
381      directory name, and returns a pointer to the directory stream.  The
382      stream is positioned at the first entry in the directory.
384   struct dirent *readdir(DIR *dir);
386      The readdir() function returns a pointer to a dirent structure
387      representing the next directory entry in the directory stream pointed to
388      by dir.  It returns NULL on reaching the end-of-file or if an error
389      occurred.
391      struct dirent {
392          unsigned char d_name[MAX_PATH];
393          int attribute;
394          int size;
395          int startcluster;
396          unsigned short wrtdate; /*  Last write date */
397          unsigned short wrttime; /*  Last write time */
398      };
400   int closedir(DIR *dir);
402      The closedir() function closes the directory stream associated with dir.
403      The directory stream descriptor dir is not available after this call.
406 Kernel
407 ======
409   void sleep(ticks);
411      Sleep a specified number of ticks, we have HZ ticks per second.
413   void yield(void);
415      Let another thread run. This should be used as soon as you have to "wait"
416      for something or similar, and also if you do anything that takes "a long
417      time". This function is the entire foundation that our "cooperative
418      multitasking" is based on. Use it.
420   void usb_screen(void);
422      Show the usb connection screen.
423      
424   long current_tick;
426      The global tick variable.
427      
428   int default_event_handler(int event);
430      If event == SYS_USB_CONNECTED, call usb_screen and return
431      SYS_USB_CONNECTED. Else do nothing and return 0.
432      
433   int create_thread(void* function, void* stack, int stack_size,
434                     const char *name IF_PRIO(int priority)
435                     IF_COP(, unsigned int core, bool fallback));
437      Create a thread.
438      ??? (see firmware/thread.c:145)
439      Return its ID if context area could be allocated, else return -1.
440      
441   void remove_thread(int threadnum);
443      Remove a thread from the scheduler.
444      Parameter is the ID as returned from create_thread().
445      
446   void reset_poweroff_timer(void);
448      The function name pretty much says what it's supposed to do.
451 String/Memory
452 =============
454   int strcmp(const char *a, const char *b);
456      strcmp compares the string a to string b. If a sorts lexicographically
457      after b, strcmp returns a number greater than zero. If the two strings
458      match, strcmp returns zero. If a sorts lexicographically before b,
459      strcmp returns a number less than zero.
460      
461   char *strcpy(char *dst, const char *src);
463      strcpy copies the string pointed to by src (including the terminating
464      null character) to the arra pointed to by dst.
465      This function returns the initial value of dst.
466      
467   void *memcpy(void *out, const void *in, size_t length);
469      Copies length bytes of data in memory from source to dest.
470   
471   void *memset(void *dst, int c, size_t length);
473      Fills a memory region with specified byte value.
474      
475   int snprintf(char *buf, size_t size, const char *fmt, ...);
477      Write a formated formated string in buffer buf of size size
478      (including the trailing '\0').
479      Upon success, return the number of characters printed or that would have
480      been printed if the output was truncated (not including the trailing 
481      '\0').
482      These support %c, %s, %d and %x only with the width and zero padding
483      flag only.
484      
485   char *strncpy(char *dst, const char *src, size_t length);
487      strncpy copies not more than length characters from the string pointed
488      to by src (including the terminating null character) to the array pointed
489      to by dst. If the string pointed to by src is shorter than length
490      characters, null characters are apended to the destination array until
491      a total of length characters have been written.
492      This function returns the initial value of dst.
493      
494   size_t strlen(const char *str);
496      The strlen function works out the length of the string starting at str
497      by counting characters until it reaches a null character.
498      strlen returns the character count.
499      
500   char *strrchr(const char *string, int c);
502      This function finds the last occurence of c (converted to a char) in the
503      string pointed to by string (including the terminating null character).
504      Returns a pointer to the located character, or a null pointer if c
505      does not occur in string.
506      
507   int strcasecmp(const char *s1, const char *s2);
509      The  strcasecmp() function compares the two strings s1 and s2, ignoring
510      the case of the characters.  It returns an integer less than, equal to,
511      or  greater than zero if s1 is found, respectively, to be less than, to
512      match, or be greater than s2.
513      
514   int strncasecmp(const char *s1, const char *s2, size_t n);
516      Like strncasecmp() but only on the first n characters.
517      {new in plugin API version 26}
518      
519   const char *_ctype_;
521      ??? (see firmware/common/ctype.c)
522      [Not for simulator]
523      
524   int atoi(const char *str);
526      The atoi() function converts the initial portion of a string pointed
527      to by str to int.
530 Sound
531 =====
533   void mpeg_sound_set(int setting, int value);
535      The function mpeg_sound_set() is used to set sound output characteristics.
536      This characterisitic is chosen with the setting argument. Possible
537      settings (and the effective values) are :
538        SOUND_VOLUME
539          0 <= value <= 100
540        SOUND_BALANCE (only effective with MAS3587F)
541          -100 <= value <= 100
542        SOUND_BASS
543          -32 <= value <= 32
544        SOUND_TREBLE
545          -32 <= value <= 32
546        SOUND_CHANNEL
547          value : MPEG_SOUND_STEREO
548                  MPEG_SOUND_MONO
549                  MPEG_SOUND_MONO_LEFT
550                  MPEG_SOUND_MONO_RIGHT
551                  MPEG_SOUND_STEREO_NARROW
552                  MPEG_SOUND_STEREO_WIDE
553                  MPEG_SOUND_KARAOKE
555        only available with MAS3587F :
556        SOUND_LOUDNESS
557          0 <= value <= 17
558        SOUND_AVC  
559          value :  1 : 20ms
560                   2 : 2s
561                   3 : 4s
562                   4 : 8s
563                   -1 : off then on
564                   other : off
565        SOUND_MDB_STRENGTH
566          0 <= value <= 127
567        SOUND_MDB_HARMONICS
568          0 <= value <= 100
569        SOUND_MDB_CENTER
570          value : ???
571        SOUND_MDB_SHAPE
572          value : ???
573        SOUND_MDB_ENABLE
574          value == 0 : off
575          other : on
576        SOUND_SUPERBASS
577          value == 0 : off
578          other : on
579          
580      
581   void mp3_play_data(unsigned char* start, int size,
582                      void (*get_more)(unsigned char** start, int* size));
583   
584      Plays a chunk of an mp3 file.
585      start points to the begining of the file to play.
586      size is the size to play.
587      getmore is a callback function.
588      ??? (see firmware/mp3_playback.c:1062)
589      [Not for simulator]
590      
591   void mp3_play_pause(bool play);
592   
593      If playback was paused and play is TRUE, resume playback.
594      If playback isn't paused and play is FALSE, pause playback.
595      [Not for simulator]
596      
597   void mp3_play_stop(void);
598   
599      Stop playback.
600      [Not for simulator]
601      
602   bool mp3_is_playing(void);
603   
604      Return true if an mp3 is playing, else return false. Note : a paused
605      mp3 is considered as a playing mp3.
606      [Not for simulator]
607      
608   void bitswap(unsigned char *data, int length);
609   
610      Swap the bits for each element of array data of size length.
611      [Not for simulator]
614 Playback Control
615 ================
617   void mpeg_play(int offset);
619      Start playback.
620      ??? what does offset do (see firmware/mpeg.c:2459)
621      
622   void mpeg_stop(void);
624      Stop playback.
625      
626   void mpeg_pause(void);
628      Pause playback.
629      
630   void mpeg_resume(void);
632      Resume playback.
633      
634   void mpeg_next(void);
636      Play the next item in playlist.
637      
638   void mpeg_prev(void);
640      Play the previous item in playlist.
641      
642   void mpeg_ff_rewind(int newtime);
644      Change playback time.
645      Has no effect in simulator.
646      
647   struct mp3entry *mpeg_next_track(void);
649      Return info about the next track.
650      struct mp3entry is defined in file firmware/export/id3.h
651      
652   int playlist_amount(void);
654      Returns the number of tracks in current playlist.
655      
656   int mpeg_status(void);
658      Returns a bitmask about current mpeg stream status.
659      Possibilities are :
660        MPEG_STATUS_PLAY
661        MPEG_STATUS_PAUSE
662        MPEG_STATUS_RECORD [MAS3587F only]
663        MPEG_STATUS_PRERECORD [MAS3587F only]
664        MPEG_STATUS_ERROR
665      
666   bool mpeg_has_changed_track(void);
668      Returns true if track has changed since last call of this function.
669      Else returns false.
670      
671   struct mp3entry *mpeg_current_track(void);
673      Return info about current track
674      struct mp3entry is defined in file firmware/export/id3.h
677 MAS communication
678 =================
680   [Not for simulator]
681   
682   int mas_readmem(int bank, int addr, unsigned long* dest, int len);
684      ???
685      
686   int mas_writemem(int bank, int addr, unsigned long* src, int len);
688      ???
689      
690   int mas_readreg(int reg);
692      ???
693      
694   int mas_writereg(int reg, unsigned int val);
695   
696      ???
697      
698   int mas_codec_writereg(int reg, unsigned int val);
699   
700      ???
701      [MAS3587F only]
702      
703   int mas_codec_readreg(int reg);
704   
705      ???
706      [MAS3587F only]
709 Misc
710 ====
712   void srand(unsigned int seed);
714      Seed the random number generator.
715      
716   int rand(void);
718      Return a pseudo random number between 0 and 0x7fffffff.
719      
720   void qsort(void *base, size_t nmemb, size_t size,
721              int(*compar)(const void *, const void *));
723      qsort sorts an array (begining at base) of nmemb objects, size
724      describes the size of each element of the array.
726      You must supply a pointer to a comparison function, using the 
727      argument shown as compar. (This permits the sorting objects of
728      unknown properties.) Define the comparison function to accept
729      two arguments, each a pointer to an element of the array starting
730      at base. The result of (*compar) must be negative if the first
731      argument is less than the second, zero if the two arguments match,
732      and positive if the first argument is greater than the second 
733      (chere ``less than'' and ``greter than'' refer to whatever
734      arbitrary ordering is appropriate).
736      The arra is sorted in place; that is, when qsort returns, the array
737      elements begining at base have been reordered.
738      
739   int kbd_input(char *buffer, int buflen);
741      Prompt for a string to be stored in buffer which is of length buflen.
742      Return FALSE upon success.
743      
744   struct tm *get_time(void);
746      Return current time.
747      struct tm
748      {
749        int   tm_sec;
750        int   tm_min;
751        int   tm_hour;
752        int   tm_mday;
753        int   tm_mon;
754        int   tm_year;
755        int   tm_wday;
756        int   tm_yday;
757        int   tm_isdst;
758      };
759      
760   int set_time(struct tm *tm);
762      Set current time.
763      Return FALSE upon success.
764      (see get_time() for a description of struct tm)
765      
766   void *plugin_get_buffer(int *buffer_size);
768      Returns a pointer to the portion of the plugin buffer that is not
769      already being used. If no plugin is loaded, returns the entire
770      plugin buffer.
771      Upon return, *buffer_size is the memory size left in plugin buffer.
772      
773   void *plugin_get_mp3_buffer(int *buffer_size);
775      Returns a pointer to the mp3 buffer.
776      Playback gets stopped to avoid conflicts.
777      
778   int plugin_register_timer(int cycles, int prio,
779                             void (*timer_callback)(void));
780   
781      Register a periodic time callbeck, called every 'cycles' CPU clocks.
782      Note that this function will be called in interrupt context!
783      [Not for simulator]
784      
785   void plugin_unregister_timer(void);
786   
787      Disable the user timer.
788      [Not for simulator]
789      
790   void plugin_tsr(void (*exit_callback)(void));
792      The plugin wants to stay resdent after leaving its main function, e.g.
793      runs from timer or own thread. The callback is registered to later
794      instruct it to free its resources before a new plugin gets loaded.
795      
796   void debugf(char *fmt, ...);
797   
798      Debug output in formated string format.
799      [Simulator or debug only]
800      
801   struct user_settings *global_settings;
803      Access to rockbox's settings.
804      struct user_settings is defined in apps/settings.h
805      
806   void backlight_set_timeout(int index);
808      Set the backlight timeout.
809      index possible values :
810        0 : backlight always off
811        1 : no time out
812        2 : 1s
813        3 : 2s
814        4 : 3s
815        5 : 4s
816        6 : 5s
817        7 : 6s
818        8 : 7s
819        9 : 8s
820        10 : 9s
821        11 : 10s
822        12 : 15s
823        13 : 20s
824        14 : 25s
825        15 : 30s
826        16 : 45s
827        17 : 60s
828        18 : 90s
829        other : backlight always off
830   
831   bool mp3info(mp3entry *entry, char *filename);
833      Return FALSE if successful. The given mp3entry is then filled in with
834      whatever id3 info it could find about the given file.
835      struct mp3entry is defined in file firmware/export/id3.h
837   int count_mp3_frames(int fd, int startpos, int filesize,
838                        void (*progressfunc)(int));
840      ??? (see firmware/mp3data.c:531)
841      something related to VBR files
842      
843   int create_xing_header(int fd, int startpos, int filesize,
844                          unsigned char *buf, int num_frames,
845                          unsigned long header_template,
846                          void (*progressfunc)(int), bool generate_toc);
848      ??? (see firmware/mp3data.c:593)
849      
850   int battery_level(void);
852      Returns battery level in percent.
853      On the simulator, battery_level always returns 75.
855   void mpeg_set_pitch(int pitch);
856   
857      Change the pitch of audio playback. pitch is given in tenths of
858      percent.
859      [MAS3587F only]
860      {new in plugin API version 26}
861      
862   unsigned short peak_meter_scale_value(unsigned short val, int meterwidth);
863   
864      Scales a peak value as read from the MAS to the range of meterwidth.
865      The scaling is performed according to the scaling method (dBfs / linear)
866      and the range (peak_meter_range_min .. peak_meter_range_max).
867      unsigned short val is the volume value. Range: 0 <= val < MAX_PEAK
868      int meterwidht is the widht of the meter in pixel
869      Returns an a value between 0 and meterwidth
870      [MAS3587F only]
871      {new in plugin API version 26}
872      
873   void peak_meter_set_use_dbfs(int use);
874   
875      Specifies wether the values displayed are scaled as dBfs or as
876      linear percent values. If use is 0 use linear percent scale, else
877      use dBfs.
878      [MAS3587F only]
879      {new in plugin API version 26}
880      
881   int peak_meter_get_use_dbfs(void);
882   
883      Returns 1 if the meter currently is displaying dBfs values, 0
884      if the meter is displaying percent values.
885      [MAS3587F only]
886      {new in plugin API version 26}
888   void mpeg_flush_and_reload_tracks(void);
890      ??? Flush the mpeg buffer and reload data ???
891      (see firmware/mpeg.c:2597)
892      (has no effect on simulator)
893      {new in plugin API version 26}
894      
895   int mpeg_get_file_pos(void);
897      ??? Returns the current cursor position in mpeg file ???
898      (see firmware/mpeg.c:260)
899      {new in plugin API version 26}
900      
901   unsigned long find_next_frame(int fd, int *offset, int max_offset,
902                                 unsigned long last_header);
904      ???
905      (see firmware/mp3data.c:262)
906      {new in plugin API version 26}
907      
908   unsigned long mpeg_get_last_header(void);
910      ???
911      (see firmware/mpeg.c:320)
912      {new in plugin API version 26}