diff options
Diffstat (limited to 'manual/advanced_topics/main.tex')
-rwxr-xr-x[-rw-r--r--] | manual/advanced_topics/main.tex | 243 |
1 files changed, 123 insertions, 120 deletions
diff --git a/manual/advanced_topics/main.tex b/manual/advanced_topics/main.tex index 9ddf680106..92dddb33db 100644..100755 --- a/manual/advanced_topics/main.tex +++ b/manual/advanced_topics/main.tex | |||
@@ -62,12 +62,12 @@ in the font package at \url{http://www.rockbox.org/daily.shtml}.} | |||
62 | 62 | ||
63 | \subsection{\label{ref:Loadinglanguages}Loading Languages} | 63 | \subsection{\label{ref:Loadinglanguages}Loading Languages} |
64 | \index{Language files}% | 64 | \index{Language files}% |
65 | Rockbox can load language files at runtime. Simply copy the \fname{.lng} file | 65 | Rockbox can load language files at runtime. Simply copy the \fname{.lng} file |
66 | \emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the | 66 | \emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the |
67 | Rockbox directory browser or select \setting{Settings $\rightarrow$ | 67 | Rockbox directory browser or select \setting{Settings $\rightarrow$ |
68 | General Settings $\rightarrow$ Language }from the \setting{Main Menu}.\\ | 68 | General Settings $\rightarrow$ Language }from the \setting{Main Menu}.\\ |
69 | 69 | ||
70 | \note{If you want a language to be loaded automatically every time you start | 70 | \note{If you want a language to be loaded automatically every time you start |
71 | up, it must be located in the \fname{/.rockbox/langs} directory and the filename | 71 | up, it must be located in the \fname{/.rockbox/langs} directory and the filename |
72 | must be a maximum of 24 characters long.\\} | 72 | must be a maximum of 24 characters long.\\} |
73 | 73 | ||
@@ -78,7 +78,7 @@ file find the instructions on the Rockbox website: | |||
78 | \opt{lcd_color}{ | 78 | \opt{lcd_color}{ |
79 | \subsection{\label{ref:ChangingFiletypeColours}Changing Filetype Colours} | 79 | \subsection{\label{ref:ChangingFiletypeColours}Changing Filetype Colours} |
80 | Rockbox has the capability to modify the \setting{File Browser} to show | 80 | Rockbox has the capability to modify the \setting{File Browser} to show |
81 | files of different types in different colours, depending on the file extension. | 81 | files of different types in different colours, depending on the file extension. |
82 | 82 | ||
83 | \subsubsection{Set-up} | 83 | \subsubsection{Set-up} |
84 | There are two steps to changing the filetype colours -- creating | 84 | There are two steps to changing the filetype colours -- creating |
@@ -100,7 +100,7 @@ file find the instructions on the Rockbox website: | |||
100 | \config{???:FFFFFF}\\* | 100 | \config{???:FFFFFF}\\* |
101 | 101 | ||
102 | The permissible extensions are as follows:\\* | 102 | The permissible extensions are as follows:\\* |
103 | \\ | 103 | \\ |
104 | \config{folder, m3u, m3u8, cfg, wps, lng, rock, bmark, cue, colours, mpa, | 104 | \config{folder, m3u, m3u8, cfg, wps, lng, rock, bmark, cue, colours, mpa, |
105 | \firmwareextension{}, % | 105 | \firmwareextension{}, % |
106 | \opt{swcodec}{mp1, }mp2, mp3% | 106 | \opt{swcodec}{mp1, }mp2, mp3% |
@@ -140,7 +140,7 @@ file find the instructions on the Rockbox website: | |||
140 | automatically understands the | 140 | automatically understands the |
141 | \fname{.colours} file format, but an external text editor can | 141 | \fname{.colours} file format, but an external text editor can |
142 | also be used. To edit the \fname{.colours} file using Rockbox, | 142 | also be used. To edit the \fname{.colours} file using Rockbox, |
143 | ``play'' it in the \setting{File Browser}. The file will open in | 143 | ``play'' it in the \setting{File Browser}. The file will open in |
144 | the \setting{Text Editor}. Upon selecting a line, the following choices | 144 | the \setting{Text Editor}. Upon selecting a line, the following choices |
145 | will appear:\\* | 145 | will appear:\\* |
146 | \\ | 146 | \\ |
@@ -172,7 +172,7 @@ file find the instructions on the Rockbox website: | |||
172 | \subsection{UI Viewport} | 172 | \subsection{UI Viewport} |
173 | By default, the UI is drawn on the whole screen. This can be changed so that | 173 | By default, the UI is drawn on the whole screen. This can be changed so that |
174 | the UI is confined to a specific area of the screen, by use of a UI | 174 | the UI is confined to a specific area of the screen, by use of a UI |
175 | viewport. This is done by adding the following line to the | 175 | viewport. This is done by adding the following line to the |
176 | \fname{.cfg} file for a theme:\\* | 176 | \fname{.cfg} file for a theme:\\* |
177 | 177 | ||
178 | \nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}} | 178 | \nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}} |
@@ -196,7 +196,7 @@ file find the instructions on the Rockbox website: | |||
196 | } | 196 | } |
197 | 197 | ||
198 | Only the first two parameters \emph{have} to be specified, the others can | 198 | Only the first two parameters \emph{have} to be specified, the others can |
199 | be omitted using `-' as a placeholder. The syntax is very similar to WPS | 199 | be omitted using `-' as a placeholder. The syntax is very similar to WPS |
200 | viewports (see \reference{ref:Viewports}). Briefly: | 200 | viewports (see \reference{ref:Viewports}). Briefly: |
201 | 201 | ||
202 | \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}} | 202 | \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}} |
@@ -226,7 +226,7 @@ file find the instructions on the Rockbox website: | |||
226 | 226 | ||
227 | \subsection{\label{ref:CreateYourOwnWPS}Themes -- Create Your Own} | 227 | \subsection{\label{ref:CreateYourOwnWPS}Themes -- Create Your Own} |
228 | The theme files are simple text files, and can be created (or edited) in your | 228 | The theme files are simple text files, and can be created (or edited) in your |
229 | favourite text editor. To make sure non-English characters | 229 | favourite text editor. To make sure non-English characters |
230 | display correctly in your theme you must save the theme files with UTF-8 | 230 | display correctly in your theme you must save the theme files with UTF-8 |
231 | character encoding. This can be done in most editors, for example Notepad in | 231 | character encoding. This can be done in most editors, for example Notepad in |
232 | Windows 2000 or XP (but not in 9x/ME) can do this. | 232 | Windows 2000 or XP (but not in 9x/ME) can do this. |
@@ -236,7 +236,7 @@ Windows 2000 or XP (but not in 9x/ME) can do this. | |||
236 | WPS files have the extension \fname{.wps}, FM screen files have the extension | 236 | WPS files have the extension \fname{.wps}, FM screen files have the extension |
237 | \fname{.fms}, and SBS files have the extension \fname{.sbs}. The main theme | 237 | \fname{.fms}, and SBS files have the extension \fname{.sbs}. The main theme |
238 | file has the extension \fname{.cfg}. All files should have the same name. | 238 | file has the extension \fname{.cfg}. All files should have the same name. |
239 | 239 | ||
240 | The theme \fname{.cfg} file should be placed in the \fname{/.rockbox/themes} | 240 | The theme \fname{.cfg} file should be placed in the \fname{/.rockbox/themes} |
241 | directory, while the \fname{.wps}, \fname{.fms} and \fname{.sbs} files should | 241 | directory, while the \fname{.wps}, \fname{.fms} and \fname{.sbs} files should |
242 | be placed in the \fname{/.rockbox/wps} directory. Any images used by the | 242 | be placed in the \fname{/.rockbox/wps} directory. Any images used by the |
@@ -269,19 +269,19 @@ are discussed below. | |||
269 | \subsubsection{\label{ref:Viewports}Viewports} | 269 | \subsubsection{\label{ref:Viewports}Viewports} |
270 | 270 | ||
271 | By default, a viewport filling the whole screen contains all the elements | 271 | By default, a viewport filling the whole screen contains all the elements |
272 | defined in each theme file. The | 272 | defined in each theme file. The |
273 | \opt{lcd_non-mono}{elements in this viewport are displayed | 273 | \opt{lcd_non-mono}{elements in this viewport are displayed |
274 | with the same background/\linebreak{}foreground | 274 | with the same background/\linebreak{}foreground |
275 | \opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the} | 275 | \opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the} |
276 | text is rendered in the | 276 | text is rendered in the |
277 | same font as in the main menu. To change this behaviour a custom viewport can | 277 | same font as in the main menu. To change this behaviour a custom viewport can |
278 | be defined. A viewport is a rectangular window on the screen% | 278 | be defined. A viewport is a rectangular window on the screen% |
279 | \opt{lcd_non-mono}{ with its own foreground/background | 279 | \opt{lcd_non-mono}{ with its own foreground/background |
280 | \opt{lcd_color}{colours}\nopt{lcd_color}{shades}}. | 280 | \opt{lcd_color}{colours}\nopt{lcd_color}{shades}}. |
281 | This window also has variable dimensions. To | 281 | This window also has variable dimensions. To |
282 | define a viewport a line starting \config{{\%V(\dots}} has to be | 282 | define a viewport a line starting \config{{\%V(\dots}} has to be |
283 | present in the theme file. The full syntax will be explained later in | 283 | present in the theme file. The full syntax will be explained later in |
284 | this section. All elements placed before the | 284 | this section. All elements placed before the |
285 | line defining a viewport are displayed in the default viewport. Elements | 285 | line defining a viewport are displayed in the default viewport. Elements |
286 | defined after a viewport declaration are drawn within that viewport. | 286 | defined after a viewport declaration are drawn within that viewport. |
287 | \opt{lcd_bitmap}{Loading images (see Appendix \reference{ref:wps_images}) | 287 | \opt{lcd_bitmap}{Loading images (see Appendix \reference{ref:wps_images}) |
@@ -390,25 +390,25 @@ and the WPS, but you can use multiple fonts in each of the individual screens.\\ | |||
390 | \item[If/else: ] | 390 | \item[If/else: ] |
391 | Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}} | 391 | Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}} |
392 | 392 | ||
393 | If the tag specified by ``\config{xx}'' has a value, the text between the | 393 | If the tag specified by ``\config{xx}'' has a value, the text between the |
394 | ``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true | 394 | ``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true |
395 | part), else the text between the ``\config{{\textbar}}'' and the | 395 | part), else the text between the ``\config{{\textbar}}'' and the |
396 | ``\config{{\textgreater}}'' is displayed (the false part). | 396 | ``\config{{\textgreater}}'' is displayed (the false part). |
397 | The else part is optional, so the ``\config{{\textbar}}'' does not have to be | 397 | The else part is optional, so the ``\config{{\textbar}}'' does not have to be |
398 | specified if no else part is desired. The conditionals nest, so the text in the | 398 | specified if no else part is desired. The conditionals nest, so the text in the |
399 | if and else part can contain all \config{\%} commands, including conditionals. | 399 | if and else part can contain all \config{\%} commands, including conditionals. |
400 | 400 | ||
401 | \item[Enumerations: ] | 401 | \item[Enumerations: ] |
402 | Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}} | 402 | Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}} |
403 | 403 | ||
404 | For tags with multiple values, like Play status, the conditional can hold a | 404 | For tags with multiple values, like Play status, the conditional can hold a |
405 | list of alternatives, one for each value the tag can have. | 405 | list of alternatives, one for each value the tag can have. |
406 | Example enumeration: | 406 | Example enumeration: |
407 | \begin{example} | 407 | \begin{example} |
408 | \%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater} | 408 | \%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater} |
409 | \end{example} | 409 | \end{example} |
410 | 410 | ||
411 | The last else part is optional, and will be displayed if the tag has no value. | 411 | The last else part is optional, and will be displayed if the tag has no value. |
412 | The WPS parser will always display the last part if the tag has no value, or if | 412 | The WPS parser will always display the last part if the tag has no value, or if |
413 | the list of alternatives is too short. | 413 | the list of alternatives is too short. |
414 | \end{description} | 414 | \end{description} |
@@ -419,8 +419,8 @@ about to play after the one currently playing (unless you change the | |||
419 | plan). | 419 | plan). |
420 | 420 | ||
421 | If you use the upper-case versions of the | 421 | If you use the upper-case versions of the |
422 | three tags: \config{F}, \config{I} and \config{D}, they will instead refer to | 422 | three tags: \config{F}, \config{I} and \config{D}, they will instead refer to |
423 | the next song instead of the current one. Example: \config{\%Ig} is the genre | 423 | the next song instead of the current one. Example: \config{\%Ig} is the genre |
424 | name used in the next song and \config{\%Ff} is the mp3 frequency.\\ | 424 | name used in the next song and \config{\%Ff} is the mp3 frequency.\\ |
425 | 425 | ||
426 | \note{The next song information \emph{will not} be available at all | 426 | \note{The next song information \emph{will not} be available at all |
@@ -430,8 +430,8 @@ name used in the next song and \config{\%Ff} is the mp3 frequency.\\ | |||
430 | 430 | ||
431 | \subsubsection{\label{ref:AlternatingSublines}Alternating Sublines} | 431 | \subsubsection{\label{ref:AlternatingSublines}Alternating Sublines} |
432 | 432 | ||
433 | It is possible to group items on each line into 2 or more groups or | 433 | It is possible to group items on each line into 2 or more groups or |
434 | ``sublines''. Each subline will be displayed in succession on the line for a | 434 | ``sublines''. Each subline will be displayed in succession on the line for a |
435 | specified time, alternating continuously through each defined subline. | 435 | specified time, alternating continuously through each defined subline. |
436 | 436 | ||
437 | Items on a line are broken into sublines with the semicolon | 437 | Items on a line are broken into sublines with the semicolon |
@@ -439,9 +439,9 @@ Items on a line are broken into sublines with the semicolon | |||
439 | each subline defaults to 2 seconds unless modified by using the | 439 | each subline defaults to 2 seconds unless modified by using the |
440 | `\config{\%t}' tag to specify an alternate | 440 | `\config{\%t}' tag to specify an alternate |
441 | time (in seconds and optional tenths of a second) for the subline to be | 441 | time (in seconds and optional tenths of a second) for the subline to be |
442 | displayed. | 442 | displayed. |
443 | 443 | ||
444 | Subline related special characters and tags: | 444 | Subline related special characters and tags: |
445 | \begin{description} | 445 | \begin{description} |
446 | \item[;] Split items on a line into separate sublines | 446 | \item[;] Split items on a line into separate sublines |
447 | \item[\%t] Set the subline display time. The | 447 | \item[\%t] Set the subline display time. The |
@@ -469,7 +469,7 @@ Example subline with conditionals: | |||
469 | %?it{\textless}%t(8)%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t(3)%s%ia{\textbar}%t(0){\textgreater}\\ | 469 | %?it{\textless}%t(8)%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t(3)%s%ia{\textbar}%t(0){\textgreater}\\ |
470 | \end{example} | 470 | \end{example} |
471 | 471 | ||
472 | The format above will do two different things depending if ID3 tags are | 472 | The format above will do two different things depending if ID3 tags are |
473 | present. If the ID3 artist and title are present: | 473 | present. If the ID3 artist and title are present: |
474 | \begin{itemize} | 474 | \begin{itemize} |
475 | \item Display id3 title for 8 seconds, | 475 | \item Display id3 title for 8 seconds, |
@@ -481,17 +481,17 @@ If the ID3 artist and title are not present: | |||
481 | \item Display the filename continuously. | 481 | \item Display the filename continuously. |
482 | \end{itemize} | 482 | \end{itemize} |
483 | Note that by using a subline display time of 0 in one branch of a conditional, | 483 | Note that by using a subline display time of 0 in one branch of a conditional, |
484 | a subline can be skipped (not displayed) when that condition is met. | 484 | a subline can be skipped (not displayed) when that condition is met. |
485 | 485 | ||
486 | \subsubsection{Using Images} | 486 | \subsubsection{Using Images} |
487 | You can have as many as 52 images in your WPS. There are various ways of | 487 | You can have as many as 52 images in your WPS. There are various ways of |
488 | displaying images: | 488 | displaying images: |
489 | \begin{enumerate} | 489 | \begin{enumerate} |
490 | \item Load and always show the image, using the \config{\%x} tag | 490 | \item Load and always show the image, using the \config{\%x} tag |
491 | \item Preload the image with \config{\%xl} and show it with \config{\%xd}. | 491 | \item Preload the image with \config{\%xl} and show it with \config{\%xd}. |
492 | This way you can have your images displayed conditionally. | 492 | This way you can have your images displayed conditionally. |
493 | \nopt{archos}{% | 493 | \nopt{archos}{% |
494 | \item Load an image and show as backdrop using the \config{\%X} tag. The | 494 | \item Load an image and show as backdrop using the \config{\%X} tag. The |
495 | image must be of the same exact dimensions as your display. | 495 | image must be of the same exact dimensions as your display. |
496 | }% | 496 | }% |
497 | \end{enumerate} | 497 | \end{enumerate} |
@@ -514,12 +514,12 @@ Example on bitmap preloading and use: | |||
514 | %xl(e,rep\_shuffle.bmp,16,64) | 514 | %xl(e,rep\_shuffle.bmp,16,64) |
515 | %?mm<%xd(b)|%xd(c)|%xd(d)|%xd(e)> | 515 | %?mm<%xd(b)|%xd(c)|%xd(d)|%xd(e)> |
516 | \end{example} | 516 | \end{example} |
517 | Four images at the same x and y position are preloaded in the example. Which | 517 | Four images at the same x and y position are preloaded in the example. Which |
518 | image to display is determined by the \config{\%mm} tag (the repeat mode). | 518 | image to display is determined by the \config{\%mm} tag (the repeat mode). |
519 | 519 | ||
520 | \subsubsection{Example File} | 520 | \subsubsection{Example File} |
521 | \begin{example} | 521 | \begin{example} |
522 | %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]> | 522 | %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]> |
523 | %pb%pc/%pt | 523 | %pb%pc/%pt |
524 | \end{example} | 524 | \end{example} |
525 | That is, ``tracknum -- title [artist, album]'', where most fields are only | 525 | That is, ``tracknum -- title [artist, album]'', where most fields are only |
@@ -531,7 +531,7 @@ title [artist]''. | |||
531 | % %s%?it<%?in<%in. |>%it|%fn> | 531 | % %s%?it<%?in<%in. |>%it|%fn> |
532 | % %s%?ia<%ia|%?d2<%d(2)|(root)>> | 532 | % %s%?ia<%ia|%?d2<%d(2)|(root)>> |
533 | % %s%?id<%id|%?d1<%d(1)|(root)>> %?iy<(%iy)|> | 533 | % %s%?id<%id|%?d1<%d(1)|(root)>> %?iy<(%iy)|> |
534 | % | 534 | % |
535 | % %al%pc/%pt%ar[%pp:%pe] | 535 | % %al%pc/%pt%ar[%pp:%pe] |
536 | % %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)> | 536 | % %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)> |
537 | % %pb | 537 | % %pb |
@@ -552,25 +552,25 @@ a \fname{car.cfg} file for the settings that you use while playing your | |||
552 | jukebox in your car, and a \fname{headphones.cfg} file to store the | 552 | jukebox in your car, and a \fname{headphones.cfg} file to store the |
553 | settings that you use while listening to your \dap{} through headphones. | 553 | settings that you use while listening to your \dap{} through headphones. |
554 | 554 | ||
555 | See \reference{ref:cfg_specs} below for an explanation of the format | 555 | See \reference{ref:cfg_specs} below for an explanation of the format |
556 | for configuration files. See \reference{ref:manage_settings_menu} for an | 556 | for configuration files. See \reference{ref:manage_settings_menu} for an |
557 | explanation of how to create, edit and load configuration files. | 557 | explanation of how to create, edit and load configuration files. |
558 | 558 | ||
559 | \subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} Files} | 559 | \subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} Files} |
560 | 560 | ||
561 | The Rockbox configuration file is a plain text file, so once you use the | 561 | The Rockbox configuration file is a plain text file, so once you use the |
562 | \setting{Save .cfg file} option to create the file, you can edit the file on | 562 | \setting{Save .cfg file} option to create the file, you can edit the file on |
563 | your computer using any text editor program. See | 563 | your computer using any text editor program. See |
564 | Appendix \reference{ref:config_file_options} for available settings. Configuration | 564 | Appendix \reference{ref:config_file_options} for available settings. Configuration |
565 | files use the following formatting rules: % | 565 | files use the following formatting rules: % |
566 | 566 | ||
567 | \begin{enumerate} | 567 | \begin{enumerate} |
568 | \item Each setting must be on a separate line. | 568 | \item Each setting must be on a separate line. |
569 | \item Each line has the format ``setting: value''. | 569 | \item Each line has the format ``setting: value''. |
570 | \item Values must be within the ranges specified in this manual for each | 570 | \item Values must be within the ranges specified in this manual for each |
571 | setting. | 571 | setting. |
572 | \item Lines starting with \# are ignored. This lets you write comments into | 572 | \item Lines starting with \# are ignored. This lets you write comments into |
573 | your configuration files. | 573 | your configuration files. |
574 | \end{enumerate} | 574 | \end{enumerate} |
575 | 575 | ||
576 | Example of a configuration file: | 576 | Example of a configuration file: |
@@ -586,17 +586,17 @@ Example of a configuration file: | |||
586 | lang: /.rockbox/afrikaans.lng | 586 | lang: /.rockbox/afrikaans.lng |
587 | \end{example} | 587 | \end{example} |
588 | 588 | ||
589 | \note{As you can see from the example, configuration files do not need to | 589 | \note{As you can see from the example, configuration files do not need to |
590 | contain all of the Rockbox options. You can create configuration files | 590 | contain all of the Rockbox options. You can create configuration files |
591 | that change only certain settings. So, for example, suppose you | 591 | that change only certain settings. So, for example, suppose you |
592 | typically use the \dap{} at one volume in the car, and another when using | 592 | typically use the \dap{} at one volume in the car, and another when using |
593 | headphones. Further, suppose you like to use an inverse LCD when you are | 593 | headphones. Further, suppose you like to use an inverse LCD when you are |
594 | in the car, and a regular LCD setting when you are using headphones. You | 594 | in the car, and a regular LCD setting when you are using headphones. You |
595 | could create configuration files that control only the volume and LCD | 595 | could create configuration files that control only the volume and LCD |
596 | settings. Create a few different files with different settings, give | 596 | settings. Create a few different files with different settings, give |
597 | each file a different name (such as \fname{car.cfg}, | 597 | each file a different name (such as \fname{car.cfg}, |
598 | \fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg | 598 | \fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg |
599 | files} option to quickly change settings.\\} | 599 | files} option to quickly change settings.\\} |
600 | 600 | ||
601 | A special case configuration file can be used to force a particular setting | 601 | A special case configuration file can be used to force a particular setting |
602 | or settings every time Rockbox starts up (e.g. to set the volume to a safe | 602 | or settings every time Rockbox starts up (e.g. to set the volume to a safe |
@@ -604,35 +604,35 @@ Example of a configuration file: | |||
604 | and save it into the \fname{/.rockbox} directory with the filename | 604 | and save it into the \fname{/.rockbox} directory with the filename |
605 | \fname{fixed.cfg}. | 605 | \fname{fixed.cfg}. |
606 | 606 | ||
607 | \subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings} | 607 | \subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings} |
608 | menu} The \setting{Manage Settings} menu can be found in the \setting{Main | 608 | menu} The \setting{Manage Settings} menu can be found in the \setting{Main |
609 | Menu}. The \setting{Manage Settings} menu allows you to save and load | 609 | Menu}. The \setting{Manage Settings} menu allows you to save and load |
610 | \fname{.cfg} files. | 610 | \fname{.cfg} files. |
611 | 611 | ||
612 | \begin{description} | 612 | \begin{description} |
613 | 613 | ||
614 | \item [Browse .cfg Files]Opens the \setting{File Browser} in the | 614 | \item [Browse .cfg Files]Opens the \setting{File Browser} in the |
615 | \fname{/.rockbox} directory and displays all \fname{.cfg} (configuration) | 615 | \fname{/.rockbox} directory and displays all \fname{.cfg} (configuration) |
616 | files. Selecting a \fname{.cfg} file will cause Rockbox to load the settings | 616 | files. Selecting a \fname{.cfg} file will cause Rockbox to load the settings |
617 | contained in that file. Pressing \ActionStdCancel{} will exit back to the | 617 | contained in that file. Pressing \ActionStdCancel{} will exit back to the |
618 | \setting{Manage Settings} menu. See the \setting{Write .cfg files} option on | 618 | \setting{Manage Settings} menu. See the \setting{Write .cfg files} option on |
619 | the \setting{Manage Settings} menu for details of how to save and edit a | 619 | the \setting{Manage Settings} menu for details of how to save and edit a |
620 | configuration file. | 620 | configuration file. |
621 | 621 | ||
622 | \item [Reset Settings]This wipes the saved settings | 622 | \item [Reset Settings]This wipes the saved settings |
623 | in the \dap{} and resets all settings to their default values. | 623 | in the \dap{} and resets all settings to their default values. |
624 | 624 | ||
625 | \opt{IRIVER_H100_PAD,IRIVER_H300_PAD,IAUDIO_X5_PAD,SANSA_E200_PAD,SANSA_C200_PAD% | 625 | \opt{IRIVER_H100_PAD,IRIVER_H300_PAD,IAUDIO_X5_PAD,SANSA_E200_PAD,SANSA_C200_PAD% |
626 | ,PBELL_VIBE500_PAD,SAMSUNG_YH92X_PAD,SAMSUNG_YH820_PAD}{ | 626 | ,PBELL_VIBE500_PAD,SAMSUNG_YH92X_PAD,SAMSUNG_YH820_PAD}{ |
627 | \note{You can also reset all settings to their default | 627 | \note{You can also reset all settings to their default |
628 | values by turning off the \dap, turning it back on, and holding the | 628 | values by turning off the \dap, turning it back on, and holding the |
629 | \ButtonRec{} button immediately after the \dap{} turns on.} | 629 | \ButtonRec{} button immediately after the \dap{} turns on.} |
630 | } | 630 | } |
631 | \opt{IRIVER_H10_PAD}{\note{You can also reset all settings to | 631 | \opt{IRIVER_H10_PAD}{\note{You can also reset all settings to |
632 | their default values by turning off the \dap, and turning it back on | 632 | their default values by turning off the \dap, and turning it back on |
633 | with the \ButtonHold{} button on.} | 633 | with the \ButtonHold{} button on.} |
634 | } | 634 | } |
635 | \opt{IPOD_4G_PAD}{\note{You can also reset all settings to their default | 635 | \opt{IPOD_4G_PAD}{\note{You can also reset all settings to their default |
636 | values by turning off the \dap, turning it back on, and activating the | 636 | values by turning off the \dap, turning it back on, and activating the |
637 | \ButtonHold{} button immediately after the backlight comes on.} | 637 | \ButtonHold{} button immediately after the backlight comes on.} |
638 | } | 638 | } |
@@ -641,23 +641,23 @@ Example of a configuration file: | |||
641 | \ButtonA{} button immediately after the \dap{} turns on.} | 641 | \ButtonA{} button immediately after the \dap{} turns on.} |
642 | } | 642 | } |
643 | 643 | ||
644 | \item [Save .cfg File]This option writes a \fname{.cfg} file to | 644 | \item [Save .cfg File]This option writes a \fname{.cfg} file to |
645 | your \daps{} disk. The configuration file has the \fname{.cfg} | 645 | your \daps{} disk. The configuration file has the \fname{.cfg} |
646 | extension and is used to store all of the user settings that are described | 646 | extension and is used to store all of the user settings that are described |
647 | throughout this manual. | 647 | throughout this manual. |
648 | 648 | ||
649 | Hint: Use the \setting{Save .cfg File} feature (\setting{Main Menu | 649 | Hint: Use the \setting{Save .cfg File} feature (\setting{Main Menu |
650 | $\rightarrow$ Manage Settings}) to save the current settings, then | 650 | $\rightarrow$ Manage Settings}) to save the current settings, then |
651 | use a text editor to customize the settings file. See Appendix | 651 | use a text editor to customize the settings file. See Appendix |
652 | \reference{ref:config_file_options} for the full reference of available | 652 | \reference{ref:config_file_options} for the full reference of available |
653 | options. | 653 | options. |
654 | 654 | ||
655 | \item [Save Sound Settings]This option writes a \fname{.cfg} file to | 655 | \item [Save Sound Settings]This option writes a \fname{.cfg} file to |
656 | your \daps{} disk. The configuration file has the \fname{.cfg} | 656 | your \daps{} disk. The configuration file has the \fname{.cfg} |
657 | extension and is used to store all of the sound related settings. | 657 | extension and is used to store all of the sound related settings. |
658 | 658 | ||
659 | \item [Save Theme Settings]This option writes a \fname{.cfg} file to | 659 | \item [Save Theme Settings]This option writes a \fname{.cfg} file to |
660 | your \daps{} disk. The configuration file has the \fname{.cfg} | 660 | your \daps{} disk. The configuration file has the \fname{.cfg} |
661 | extension and is used to store all of the theme related settings. | 661 | extension and is used to store all of the theme related settings. |
662 | 662 | ||
663 | \end{description} | 663 | \end{description} |
@@ -665,16 +665,16 @@ Example of a configuration file: | |||
665 | \section{\label{ref:FirmwareLoading}Firmware Loading} | 665 | \section{\label{ref:FirmwareLoading}Firmware Loading} |
666 | \opt{player,recorder,recorderv2fm,ondio}{ | 666 | \opt{player,recorder,recorderv2fm,ondio}{ |
667 | When your \dap{} powers on, it loads the Archos firmware in ROM, which | 667 | When your \dap{} powers on, it loads the Archos firmware in ROM, which |
668 | automatically checks your \daps{} root directory for a file named | 668 | automatically checks your \daps{} root directory for a file named |
669 | \firmwarefilename. Note that Archos firmware can only read the first | 669 | \firmwarefilename. Note that Archos firmware can only read the first |
670 | ten characters of each filename in this process, so do not rename your old | 670 | ten characters of each filename in this process, so do not rename your old |
671 | firmware files with names like \firmwarefilename.\fname{old} and so on, | 671 | firmware files with names like \firmwarefilename.\fname{old} and so on, |
672 | because it is possible that the \dap{} will load a file other than the one | 672 | because it is possible that the \dap{} will load a file other than the one |
673 | you intended. | 673 | you intended. |
674 | } | 674 | } |
675 | 675 | ||
676 | \subsection{\label{ref:using_rolo}Using ROLO (Rockbox Loader)} | 676 | \subsection{\label{ref:using_rolo}Using ROLO (Rockbox Loader)} |
677 | Rockbox is able to load and start another firmware file without rebooting. | 677 | Rockbox is able to load and start another firmware file without rebooting. |
678 | You just ``play'' a file with the extension % | 678 | You just ``play'' a file with the extension % |
679 | \opt{recorder,recorderv2fm,ondio}{\fname{.ajz}.} % | 679 | \opt{recorder,recorderv2fm,ondio}{\fname{.ajz}.} % |
680 | \opt{player}{\fname{.mod}.} % | 680 | \opt{player}{\fname{.mod}.} % |
@@ -690,76 +690,79 @@ current version. | |||
690 | \opt{archos}{\input{advanced_topics/archos-flashing.tex}} | 690 | \opt{archos}{\input{advanced_topics/archos-flashing.tex}} |
691 | 691 | ||
692 | \section{Optimising battery runtime} | 692 | \section{Optimising battery runtime} |
693 | Rockbox offers a lot of settings that have high impact on the battery runtime | 693 | Rockbox offers a lot of settings that have high impact on the battery runtime |
694 | of your \dap{}. The largest power savings can be achieved through disabling | 694 | of your \dap{}. The largest power savings can be achieved through disabling |
695 | unneeded hardware components -- for some of those there are settings | 695 | unneeded hardware components -- for some of those there are settings |
696 | available. | 696 | available. |
697 | |||
698 | |||
697 | \opt{swcodec}{ | 699 | \opt{swcodec}{ |
698 | Another area of savings is avoiding or reducing CPU boosting | 700 | Another area of savings is avoiding or reducing CPU boosting |
699 | through disabling computing intense features (e.g. sound processing) or | 701 | through disabling computing intense features (e.g. sound processing) or |
700 | using effective audio codecs. | 702 | using effective audio codecs. |
701 | } The following provides a short overview of the most relevant settings and | 703 | } The following provides a short overview of the most relevant settings and |
702 | rules of thumb. | 704 | rules of thumb. |
703 | 705 | ||
704 | \nopt{ondio}{ | 706 | \nopt{ondio}{ |
705 | \subsection{Display backlight} | 707 | \subsection{Display backlight} |
706 | The active backlight consumes a lot of power. Therefore choose a setting that | 708 | The active backlight consumes a lot of power. Therefore choose a setting that |
707 | disables the backlight after timeout (for setting \setting{Backlight} see | 709 | disables the backlight after timeout (for setting \setting{Backlight} see |
708 | \reference{ref:Displayoptions}). Avoid to have the backlight enabled all the | 710 | \reference{ref:Displayoptions}). Avoid having the backlight enabled all the |
709 | time. | 711 | time (Activating \setting{selectivebacklight} |
712 | \reference{ref:selectivebacklight} can further reduce power consumption). | ||
710 | } | 713 | } |
711 | 714 | ||
712 | \opt{lcd_sleep}{ | 715 | \opt{lcd_sleep}{ |
713 | \subsection{Display power-off} | 716 | \subsection{Display power-off} |
714 | Shutting down the display and the display controller saves a reasonable amount | 717 | Shutting down the display and the display controller saves a reasonable amount |
715 | of power. Choose a setting that will put the display to sleep after timeout | 718 | of power. Choose a setting that will put the display to sleep after timeout |
716 | (for setting \setting{Sleep} see \reference{ref:Displayoptions}). Avoid to | 719 | (for setting \setting{Sleep} see \reference{ref:Displayoptions}). Avoid to |
717 | have the display enabled all the time -- even, if the display is transflective | 720 | have the display enabled all the time -- even, if the display is transflective |
718 | and is readable without backlight. Depending on your \dap{} it might be | 721 | and is readable without backlight. Depending on your \dap{} it might be |
719 | significantly more efficient to re-enable the display and its backlight for a | 722 | significantly more efficient to re-enable the display and its backlight for a |
720 | glimpse a few times per hour than to keep the display enabled. | 723 | glimpse a few times per hour than to keep the display enabled. |
721 | } | 724 | } |
722 | 725 | ||
723 | \opt{accessory_supply}{ | 726 | \opt{accessory_supply}{ |
724 | \subsection{Accessory power supply} | 727 | \subsection{Accessory power supply} |
725 | As default your \dap{}'s accessory power supply is always enabled to ensure | 728 | As default your \dap{}'s accessory power supply is always enabled to ensure |
726 | proper function of connected accessory devices. Disable this power supply, if | 729 | proper function of connected accessory devices. Disable this power supply, if |
727 | -- or as long as -- you do not use any accessory device with your \dap{} while | 730 | -- or as long as -- you do not use any accessory device with your \dap{} while |
728 | running Rockbox (see \reference{ref:AccessoryPowerSupply}). | 731 | running Rockbox (see \reference{ref:AccessoryPowerSupply}). |
729 | } | 732 | } |
730 | 733 | ||
731 | \opt{lineout_poweroff}{ | 734 | \opt{lineout_poweroff}{ |
732 | \subsection{Line Out} | 735 | \subsection{Line Out} |
733 | Rockbox allows to switch off the line-out on your \dap{}. If you do not need | 736 | Rockbox allows to switch off the line-out on your \dap{}. If you do not need |
734 | the line-out, switch it off (see \reference{ref:LineoutOnOff}). | 737 | the line-out, switch it off (see \reference{ref:LineoutOnOff}). |
735 | } | 738 | } |
736 | 739 | ||
737 | \opt{spdif_power}{ | 740 | \opt{spdif_power}{ |
738 | \subsection{Optical Output} | 741 | \subsection{Optical Output} |
739 | Rockbox allows to switch off the S/PDIF output on your \dap{}. If you do not | 742 | Rockbox allows to switch off the S/PDIF output on your \dap{}. If you do not |
740 | need this output, switch it off (see \reference{ref:SPDIF_OnOff}). | 743 | need this output, switch it off (see \reference{ref:SPDIF_OnOff}). |
741 | } | 744 | } |
742 | 745 | ||
743 | \opt{disk_storage}{ | 746 | \opt{disk_storage}{ |
744 | \subsection{Anti-Skip Buffer} | 747 | \subsection{Anti-Skip Buffer} |
745 | Having a large anti-skip buffer tends to use more power, and may reduce your | 748 | Having a large anti-skip buffer tends to use more power, and may reduce your |
746 | battery life. It is recommended to always use the lowest possible setting | 749 | battery life. It is recommended to always use the lowest possible setting |
747 | that allows correct and continuous playback (see \reference{ref:AntiSkipBuf}). | 750 | that allows correct and continuous playback (see \reference{ref:AntiSkipBuf}). |
748 | } | 751 | } |
749 | 752 | ||
750 | \opt{swcodec}{ | 753 | \opt{swcodec}{ |
751 | \subsection{Replaygain} | 754 | \subsection{Replaygain} |
752 | Replaygain is a post processing that equalises the playback volume of audio | 755 | Replaygain is a post processing that equalises the playback volume of audio |
753 | files to the same perceived loudness. This post processing applies a factor | 756 | files to the same perceived loudness. This post processing applies a factor |
754 | to each single PCM sample and is therefore consuming additional CPU time. If | 757 | to each single PCM sample and is therefore consuming additional CPU time. If |
755 | you want to achieve some (minor) savings in runtime, switch this feature off | 758 | you want to achieve some (minor) savings in runtime, switch this feature off |
756 | (see \reference{ref:ReplayGain}). | 759 | (see \reference{ref:ReplayGain}). |
757 | } | 760 | } |
758 | 761 | ||
759 | \opt{lcd_bitmap}{ | 762 | \opt{lcd_bitmap}{ |
760 | \subsection{Peak Meter} | 763 | \subsection{Peak Meter} |
761 | The peak meter is a feature of the While Playing Screen and will be updated with a | 764 | The peak meter is a feature of the While Playing Screen and will be updated with a |
762 | high framerate. Depending on your \dap{} this might result in a high CPU load. To | 765 | high framerate. Depending on your \dap{} this might result in a high CPU load. To |
763 | save battery runtime you should switch this feature off (see \reference{ref:peak_meter}). | 766 | save battery runtime you should switch this feature off (see \reference{ref:peak_meter}). |
764 | \opt{ipodvideo}{ | 767 | \opt{ipodvideo}{ |
765 | \note{Especially the \playerman{} \playertype{} suffers from an enabled peak meter.} | 768 | \note{Especially the \playerman{} \playertype{} suffers from an enabled peak meter.} |
@@ -770,36 +773,36 @@ current version. | |||
770 | \subsection{Audio format and bitrate} | 773 | \subsection{Audio format and bitrate} |
771 | \opt{swcodec}{ | 774 | \opt{swcodec}{ |
772 | In general the fastest decoding audio format will be the best in terms of | 775 | In general the fastest decoding audio format will be the best in terms of |
773 | battery runtime on your \dap{}. An overview of different codec's performance | 776 | battery runtime on your \dap{}. An overview of different codec's performance |
774 | on different \dap{}s can be found at \wikilink{CodecPerformanceComparison}. | 777 | on different \dap{}s can be found at \wikilink{CodecPerformanceComparison}. |
775 | } | 778 | } |
776 | 779 | ||
777 | \opt{flash_storage}{ | 780 | \opt{flash_storage}{ |
778 | Your target uses flash that consumes a certain amount of power during access. | 781 | Your target uses flash that consumes a certain amount of power during access. |
779 | The less often the flash needs to be switched on for buffering and the shorter | 782 | The less often the flash needs to be switched on for buffering and the shorter |
780 | the buffering duration is, the lower is the overall power consumption. | 783 | the buffering duration is, the lower is the overall power consumption. |
781 | Therefore the bitrate of the audio files does have an impact on the battery | 784 | Therefore the bitrate of the audio files does have an impact on the battery |
782 | runtime as well. Lower bitrate audio files will result in longer battery | 785 | runtime as well. Lower bitrate audio files will result in longer battery |
783 | runtime. | 786 | runtime. |
784 | } | 787 | } |
785 | \opt{disk_storage}{ | 788 | \opt{disk_storage}{ |
786 | Your target uses a hard disk which consumes a large amount of power while | 789 | Your target uses a hard disk which consumes a large amount of power while |
787 | spinning -- up to several hundred mA. The less often the hard disk needs to | 790 | spinning -- up to several hundred mA. The less often the hard disk needs to |
788 | spin up for buffering and the shorter the buffering duration is, the lower is | 791 | spin up for buffering and the shorter the buffering duration is, the lower is |
789 | the power consumption. Therefore the bitrate of the audio files does have an | 792 | the power consumption. Therefore the bitrate of the audio files does have an |
790 | impact on the battery runtime as well. Lower bitrate audio files will result | 793 | impact on the battery runtime as well. Lower bitrate audio files will result |
791 | in longer battery runtime. | 794 | in longer battery runtime. |
792 | } | 795 | } |
793 | 796 | ||
794 | Please do not re-encode any existing audio files from one lossy format to | 797 | Please do not re-encode any existing audio files from one lossy format to |
795 | another based upon the above mentioned. This will reduce the audio quality. | 798 | another based upon the above mentioned. This will reduce the audio quality. |
796 | If you have the choice, select the best suiting codec when encoding the | 799 | If you have the choice, select the best suiting codec when encoding the |
797 | original source material. | 800 | original source material. |
798 | } | 801 | } |
799 | 802 | ||
800 | \opt{swcodec}{ | 803 | \opt{swcodec}{ |
801 | \subsection{Sound settings} | 804 | \subsection{Sound settings} |
802 | In general all kinds of sound processing will need more CPU time and therefore | 805 | In general all kinds of sound processing will need more CPU time and therefore |
803 | consume more power. The less sound processing you use, the better it is for | 806 | consume more power. The less sound processing you use, the better it is for |
804 | the battery runtime (for options see \reference{ref:configure_rockbox_sound}). | 807 | the battery runtime (for options see \reference{ref:configure_rockbox_sound}). |
805 | } | 808 | } |