diff options
Diffstat (limited to 'tde-i18n-pt/docs/tdemultimedia/artsbuilder')
20 files changed, 10930 insertions, 0 deletions
diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/Makefile.am b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/Makefile.am new file mode 100644 index 00000000000..6869837a64a --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/Makefile.am @@ -0,0 +1,4 @@ +KDE_LANG = pt +SUBDIRS = $(AUTODIRS) +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/Makefile.in b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/Makefile.in new file mode 100644 index 00000000000..62e0407a1f5 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/Makefile.in @@ -0,0 +1,635 @@ +# Makefile.in generated by automake 1.10.1 from Makefile.am. +# KDE tags expanded automatically by am_edit - $Revision: 483858 $ +# @configure_input@ + +# Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, +# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ +VPATH = @srcdir@ +pkgdatadir = $(datadir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +subdir = docs/tdemultimedia/artsbuilder +DIST_COMMON = $(srcdir)/Makefile.am $(srcdir)/Makefile.in +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/acinclude.m4 \ + $(top_srcdir)/configure.in +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +SOURCES = +DIST_SOURCES = +#>- RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ +#>- html-recursive info-recursive install-data-recursive \ +#>- install-dvi-recursive install-exec-recursive \ +#>- install-html-recursive install-info-recursive \ +#>- install-pdf-recursive install-ps-recursive install-recursive \ +#>- installcheck-recursive installdirs-recursive pdf-recursive \ +#>- ps-recursive uninstall-recursive +#>+ 7 +RECURSIVE_TARGETS = all-recursive check-recursive dvi-recursive \ + html-recursive info-recursive install-data-recursive \ + install-dvi-recursive install-exec-recursive \ + install-html-recursive install-info-recursive \ + install-pdf-recursive install-ps-recursive install-recursive \ + installcheck-recursive installdirs-recursive pdf-recursive \ + ps-recursive uninstall-recursive nmcheck-recursive bcheck-recursive +RECURSIVE_CLEAN_TARGETS = mostlyclean-recursive clean-recursive \ + distclean-recursive maintainer-clean-recursive +ETAGS = etags +CTAGS = ctags +DIST_SUBDIRS = $(SUBDIRS) +#>- DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +#>+ 1 +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) $(KDE_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +ARTSCCONFIG = @ARTSCCONFIG@ +AUTOCONF = @AUTOCONF@ +AUTODIRS = @AUTODIRS@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CONF_FILES = @CONF_FILES@ +CYGPATH_W = @CYGPATH_W@ +DCOPIDL = @DCOPIDL@ +DCOPIDL2CPP = @DCOPIDL2CPP@ +DCOPIDLNG = @DCOPIDLNG@ +DCOP_DEPENDENCIES = @DCOP_DEPENDENCIES@ +DEFS = @DEFS@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +GMSGFMT = @GMSGFMT@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KCFG_DEPENDENCIES = @KCFG_DEPENDENCIES@ +KCONFIG_COMPILER = @KCONFIG_COMPILER@ +KDECONFIG = @KDECONFIG@ +KDE_EXTRA_RPATH = @KDE_EXTRA_RPATH@ +KDE_RPATH = @KDE_RPATH@ +KDE_XSL_STYLESHEET = @KDE_XSL_STYLESHEET@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MAKEKDEWIDGETS = @MAKEKDEWIDGETS@ +MCOPIDL = @MCOPIDL@ +MEINPROC = @MEINPROC@ +MKDIR_P = @MKDIR_P@ +MSGFMT = @MSGFMT@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TOPSUBDIRS = @TOPSUBDIRS@ +VERSION = @VERSION@ +XGETTEXT = @XGETTEXT@ +XMLLINT = @XMLLINT@ +X_RPATH = @X_RPATH@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +am__leading_dot = @am__leading_dot@ +am__tar = @am__tar@ +am__untar = @am__untar@ +#>- bindir = @bindir@ +#>+ 2 +DEPDIR = .deps +bindir = @bindir@ +build_alias = @build_alias@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host_alias = @host_alias@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +kde_appsdir = @kde_appsdir@ +kde_bindir = @kde_bindir@ +kde_confdir = @kde_confdir@ +kde_datadir = @kde_datadir@ +kde_htmldir = @kde_htmldir@ +kde_icondir = @kde_icondir@ +kde_kcfgdir = @kde_kcfgdir@ +kde_libs_htmldir = @kde_libs_htmldir@ +kde_libs_prefix = @kde_libs_prefix@ +kde_locale = @kde_locale@ +kde_mimedir = @kde_mimedir@ +kde_moduledir = @kde_moduledir@ +kde_servicesdir = @kde_servicesdir@ +kde_servicetypesdir = @kde_servicetypesdir@ +kde_sounddir = @kde_sounddir@ +kde_styledir = @kde_styledir@ +kde_templatesdir = @kde_templatesdir@ +kde_wallpaperdir = @kde_wallpaperdir@ +kde_widgetdir = @kde_widgetdir@ +tdeinitdir = @tdeinitdir@ +libdir = @libdir@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +xdg_appsdir = @xdg_appsdir@ +xdg_directorydir = @xdg_directorydir@ +xdg_menudir = @xdg_menudir@ +KDE_LANG = pt +#>- SUBDIRS = $(AUTODIRS) +#>+ 1 +SUBDIRS =. +KDE_DOCS = AUTO +KDE_MANS = AUTO +#>- all: all-recursive +#>+ 1 +all: docs-am all-recursive + +.SUFFIXES: +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) +#>- @for dep in $?; do \ +#>- case '$(am__configure_deps)' in \ +#>- *$$dep*) \ +#>- cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ +#>- && exit 0; \ +#>- exit 1;; \ +#>- esac; \ +#>- done; \ +#>- echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu docs/tdemultimedia/artsbuilder/Makefile'; \ +#>- cd $(top_srcdir) && \ +#>- $(AUTOMAKE) --gnu docs/tdemultimedia/artsbuilder/Makefile +#>+ 12 + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu docs/tdemultimedia/artsbuilder/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu docs/tdemultimedia/artsbuilder/Makefile + cd $(top_srcdir) && perl ../scripts/admin/am_edit -p../scripts/admin docs/tdemultimedia/artsbuilder/Makefile.in +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +# This directory's subdirectories are mostly independent; you can cd +# into them and run `make' without going through this Makefile. +# To change the values of `make' variables: instead of editing Makefiles, +# (1) if the variable is set in `config.status', edit `config.status' +# (which will cause the Makefiles to be regenerated when you run `make'); +# (2) otherwise, pass the desired values on the `make' command line. +$(RECURSIVE_TARGETS): + @failcom='exit 1'; \ + for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=* | --[!k]*);; \ + *k*) failcom='fail=yes';; \ + esac; \ + done; \ + dot_seen=no; \ + target=`echo $@ | sed s/-recursive//`; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + dot_seen=yes; \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done; \ + if test "$$dot_seen" = "no"; then \ + $(MAKE) $(AM_MAKEFLAGS) "$$target-am" || exit 1; \ + fi; test -z "$$fail" + +$(RECURSIVE_CLEAN_TARGETS): + @failcom='exit 1'; \ + for f in x $$MAKEFLAGS; do \ + case $$f in \ + *=* | --[!k]*);; \ + *k*) failcom='fail=yes';; \ + esac; \ + done; \ + dot_seen=no; \ + case "$@" in \ + distclean-* | maintainer-clean-*) list='$(DIST_SUBDIRS)' ;; \ + *) list='$(SUBDIRS)' ;; \ + esac; \ + rev=''; for subdir in $$list; do \ + if test "$$subdir" = "."; then :; else \ + rev="$$subdir $$rev"; \ + fi; \ + done; \ + rev="$$rev ."; \ + target=`echo $@ | sed s/-recursive//`; \ + for subdir in $$rev; do \ + echo "Making $$target in $$subdir"; \ + if test "$$subdir" = "."; then \ + local_target="$$target-am"; \ + else \ + local_target="$$target"; \ + fi; \ + (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) $$local_target) \ + || eval $$failcom; \ + done && test -z "$$fail" +tags-recursive: + list='$(SUBDIRS)'; for subdir in $$list; do \ + test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) tags); \ + done +ctags-recursive: + list='$(SUBDIRS)'; for subdir in $$list; do \ + test "$$subdir" = . || (cd $$subdir && $(MAKE) $(AM_MAKEFLAGS) ctags); \ + done + +ID: $(HEADERS) $(SOURCES) $(LISP) $(TAGS_FILES) + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonemtpy = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + mkid -fID $$unique +tags: TAGS + +TAGS: tags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + tags=; \ + here=`pwd`; \ + if ($(ETAGS) --etags-include --version) >/dev/null 2>&1; then \ + include_option=--etags-include; \ + empty_fix=.; \ + else \ + include_option=--include; \ + empty_fix=; \ + fi; \ + list='$(SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test ! -f $$subdir/TAGS || \ + tags="$$tags $$include_option=$$here/$$subdir/TAGS"; \ + fi; \ + done; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + if test -z "$(ETAGS_ARGS)$$tags$$unique"; then :; else \ + test -n "$$unique" || unique=$$empty_fix; \ + $(ETAGS) $(ETAGSFLAGS) $(AM_ETAGSFLAGS) $(ETAGS_ARGS) \ + $$tags $$unique; \ + fi +ctags: CTAGS +CTAGS: ctags-recursive $(HEADERS) $(SOURCES) $(TAGS_DEPENDENCIES) \ + $(TAGS_FILES) $(LISP) + tags=; \ + list='$(SOURCES) $(HEADERS) $(LISP) $(TAGS_FILES)'; \ + unique=`for i in $$list; do \ + if test -f "$$i"; then echo $$i; else echo $(srcdir)/$$i; fi; \ + done | \ + $(AWK) '{ files[$$0] = 1; nonempty = 1; } \ + END { if (nonempty) { for (i in files) print i; }; }'`; \ + test -z "$(CTAGS_ARGS)$$tags$$unique" \ + || $(CTAGS) $(CTAGSFLAGS) $(AM_CTAGSFLAGS) $(CTAGS_ARGS) \ + $$tags $$unique + +GTAGS: + here=`$(am__cd) $(top_builddir) && pwd` \ + && cd $(top_srcdir) \ + && gtags -i $(GTAGS_ARGS) $$here + +distclean-tags: + -rm -f TAGS ID GTAGS GRTAGS GSYMS GPATH tags + +#>- distdir: $(DISTFILES) +#>+ 1 +distdir: distdir-nls $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + fi; \ + cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + else \ + test -f $(distdir)/$$file \ + || cp -p $$d/$$file $(distdir)/$$file \ + || exit 1; \ + fi; \ + done + list='$(DIST_SUBDIRS)'; for subdir in $$list; do \ + if test "$$subdir" = .; then :; else \ + test -d "$(distdir)/$$subdir" \ + || $(MKDIR_P) "$(distdir)/$$subdir" \ + || exit 1; \ + distdir=`$(am__cd) $(distdir) && pwd`; \ + top_distdir=`$(am__cd) $(top_distdir) && pwd`; \ + (cd $$subdir && \ + $(MAKE) $(AM_MAKEFLAGS) \ + top_distdir="$$top_distdir" \ + distdir="$$distdir/$$subdir" \ + am__remove_distdir=: \ + am__skip_length_check=: \ + distdir) \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-recursive +all-am: Makefile +installdirs: installdirs-recursive +installdirs-am: +install: install-recursive +install-exec: install-exec-recursive +install-data: install-data-recursive +#>- uninstall: uninstall-recursive +#>+ 1 +uninstall: uninstall-docs uninstall-nls uninstall-recursive + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-recursive +install-strip: + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + `test -z '$(STRIP)' || \ + echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install +mostlyclean-generic: + +clean-generic: + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +#>- clean: clean-recursive +#>+ 1 +clean: kde-rpo-clean clean-recursive + +#>- clean-am: clean-generic mostlyclean-am +#>+ 1 +clean-am: clean-docs clean-bcheck clean-generic mostlyclean-am + +distclean: distclean-recursive + -rm -f Makefile +distclean-am: clean-am distclean-generic distclean-tags + +dvi: dvi-recursive + +dvi-am: + +html: html-recursive + +info: info-recursive + +info-am: + +#>- install-data-am: +#>+ 1 +install-data-am: install-docs install-nls + +install-dvi: install-dvi-recursive + +install-exec-am: + +install-html: install-html-recursive + +install-info: install-info-recursive + +install-man: + +install-pdf: install-pdf-recursive + +install-ps: install-ps-recursive + +installcheck-am: + +maintainer-clean: maintainer-clean-recursive + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-recursive + +mostlyclean-am: mostlyclean-generic + +pdf: pdf-recursive + +pdf-am: + +ps: ps-recursive + +ps-am: + +uninstall-am: + +.MAKE: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) install-am \ + install-strip + +.PHONY: $(RECURSIVE_CLEAN_TARGETS) $(RECURSIVE_TARGETS) CTAGS GTAGS \ + all all-am check check-am clean clean-generic ctags \ + ctags-recursive distclean distclean-generic distclean-tags \ + distdir dvi dvi-am html html-am info info-am install \ + install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + installdirs-am maintainer-clean maintainer-clean-generic \ + mostlyclean mostlyclean-generic pdf pdf-am ps ps-am tags \ + tags-recursive uninstall uninstall-am + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: + +#>+ 2 +KDE_DIST=future.docbook index.docbook porting.docbook glossary.docbook helping.docbook artsbuilder.docbook detail.docbook midiintro.docbook modules.docbook mcop.docbook gui.docbook faq.docbook index.cache.bz2 midi.docbook tools.docbook Makefile.in digitalaudio.docbook references.docbook apis.docbook Makefile.am + +#>+ 24 +index.cache.bz2: $(srcdir)/index.docbook $(KDE_XSL_STYLESHEET) glossary.docbook porting.docbook apis.docbook gui.docbook references.docbook mcop.docbook index.docbook detail.docbook future.docbook artsbuilder.docbook digitalaudio.docbook faq.docbook modules.docbook tools.docbook midi.docbook helping.docbook midiintro.docbook + @if test -n "$(MEINPROC)"; then echo $(MEINPROC) --check --cache index.cache.bz2 $(srcdir)/index.docbook; $(MEINPROC) --check --cache index.cache.bz2 $(srcdir)/index.docbook; fi + +docs-am: index.cache.bz2 + +install-docs: docs-am install-nls + $(mkinstalldirs) $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder + @if test -f index.cache.bz2; then \ + echo $(INSTALL_DATA) index.cache.bz2 $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/; \ + $(INSTALL_DATA) index.cache.bz2 $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/; \ + elif test -f $(srcdir)/index.cache.bz2; then \ + echo $(INSTALL_DATA) $(srcdir)/index.cache.bz2 $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/; \ + $(INSTALL_DATA) $(srcdir)/index.cache.bz2 $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/; \ + fi + -rm -f $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/common + $(LN_S) $(kde_libs_htmldir)/$(KDE_LANG)/common $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/common + +uninstall-docs: + -rm -rf $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder + +clean-docs: + -rm -f index.cache.bz2 + + +#>+ 13 +install-nls: + $(mkinstalldirs) $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder + @for base in glossary.docbook porting.docbook apis.docbook gui.docbook references.docbook mcop.docbook index.docbook detail.docbook future.docbook artsbuilder.docbook digitalaudio.docbook faq.docbook modules.docbook tools.docbook midi.docbook helping.docbook midiintro.docbook ; do \ + echo $(INSTALL_DATA) $$base $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/$$base ;\ + $(INSTALL_DATA) $(srcdir)/$$base $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/$$base ;\ + done + +uninstall-nls: + for base in glossary.docbook porting.docbook apis.docbook gui.docbook references.docbook mcop.docbook index.docbook detail.docbook future.docbook artsbuilder.docbook digitalaudio.docbook faq.docbook modules.docbook tools.docbook midi.docbook helping.docbook midiintro.docbook ; do \ + rm -f $(DESTDIR)$(kde_htmldir)/$(KDE_LANG)/artsbuilder/$$base ;\ + done + + +#>+ 5 +distdir-nls: + for file in glossary.docbook porting.docbook apis.docbook gui.docbook references.docbook mcop.docbook index.docbook detail.docbook future.docbook artsbuilder.docbook digitalaudio.docbook faq.docbook modules.docbook tools.docbook midi.docbook helping.docbook midiintro.docbook ; do \ + cp $(srcdir)/$$file $(distdir); \ + done + +#>+ 15 +force-reedit: + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ + && exit 0; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu docs/tdemultimedia/artsbuilder/Makefile'; \ + cd $(top_srcdir) && \ + $(AUTOMAKE) --gnu docs/tdemultimedia/artsbuilder/Makefile + cd $(top_srcdir) && perl ../scripts/admin/am_edit -p../scripts/admin docs/tdemultimedia/artsbuilder/Makefile.in + + +#>+ 21 +clean-bcheck: + rm -f *.bchecktest.cc *.bchecktest.cc.class a.out + +bcheck: bcheck-recursive + +bcheck-am: + @for i in ; do \ + if test $(srcdir)/$$i -nt $$i.bchecktest.cc; then \ + echo "int main() {return 0;}" > $$i.bchecktest.cc ; \ + echo "#include \"$$i\"" >> $$i.bchecktest.cc ; \ + echo "$$i"; \ + if ! $(CXX) $(DEFS) -I. -I$(srcdir) -I$(top_builddir) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(CXXFLAGS) $(KDE_CXXFLAGS) --dump-class-hierarchy -c $$i.bchecktest.cc; then \ + rm -f $$i.bchecktest.cc; exit 1; \ + fi ; \ + echo "" >> $$i.bchecktest.cc.class; \ + perl $(top_srcdir)/admin/bcheck.pl $$i.bchecktest.cc.class || { rm -f $$i.bchecktest.cc; exit 1; }; \ + rm -f a.out; \ + fi ; \ + done + + +#>+ 3 +final: + $(MAKE) all-am + +#>+ 3 +final-install: + $(MAKE) install-am + +#>+ 3 +no-final: + $(MAKE) all-am + +#>+ 3 +no-final-install: + $(MAKE) install-am + +#>+ 3 +kde-rpo-clean: + -rm -f *.rpo + +#>+ 3 +nmcheck: +nmcheck-am: nmcheck diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/apis.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/apis.docbook new file mode 100644 index 00000000000..e7c21dfb17e --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/apis.docbook @@ -0,0 +1,434 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-apis"> +<title +>Interfaces de Programação de Aplicações do &arts;</title> + +<sect1 id="api-overview"> +<title +>Introdução</title> +<para +>O aRts não é apenas um pedaço de 'software', também fornece uma variedade de APIs para uma variedade de fins. Nesta secção, será dada uma "ideia geral", uma breve apresentação do que essas APIs supostamente deverão fazer e como interagem. </para> + +<para +>Existe uma distinção importante a fazer: a maioria das APIs são <emphasis +>independentes da linguagem e da localização</emphasis +> dado que são especificadas no <emphasis +>mcopidl</emphasis +>. Isto é, você pode basicamente usar os serviços que elas oferecem a partir de qualquer linguagem, implementá-las em qualquer linguagem e não terá de se preocupar se está a falar com objectos locais ou remotos. Aqui está uma lista destes, em primeiro lugar: </para> + + +<variablelist> +<varlistentry> +<term +>core.idl</term> + <listitem +><para +>As definições básicas que formam o núcleo da funcionalidade do MCOP, como por exemplo o próprio protocolo, as definições do objecto, o mediador, o sistema de fluxo e assim por diante. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>artsflow.idl</term> + + <listitem +><para +>Estes contêm o sistema de fluxo que você irá usar para se ligar às sequências de áudio, a definição do <emphasis +>Arts::SynthModule</emphasis +> que é a base de qualquer interface que emita sequências multimédia e, finalmente, alguns objectos de áudio úteis </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>kmedia2.idl</term> + + + <listitem +><para +>Aqui está definido um objecto que poderá reproduzir conteúdos multimédia, o <emphasis +>Arts::PlayObject</emphasis +>. Os leitores multimédia como o 'noatun', o reprodutor multimédia serão capazes de reproduzir qualquer conteúdo multimédia para o qual exista um PlayObject. Por isso, faz sentido implementar os PlayObjects para os vários formatos (como o MP3, o vídeo MPEG, MIDI, WAV, ...) nessa base, e já existem alguns de facto. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>soundserver.idl</term> + + <listitem +><para +>Aqui está definida uma interface para o servidor de som do sistema, o 'artsd'. A interface chama-se <emphasis +>Arts::SoundServer</emphasis +>, e implementa alguma funcionalidade como a aceitação de sequências multimédia da rede, a reprodução de amostras, a criação de outros objectos personalizados do aRts, e assim por diante. A transparência da rede está implícita devido à utilização do MCOP (como em tudo o resto, de facto). </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>artsbuilder.idl</term> + <listitem +><para +>Este módulo define a funcionalidade básica do grafo de fluxo, isto é, a combinação de objectos mais simples de modo a criar objectos mais complexos, definindo para tal um grafo com eles. Ele define a interface básica <emphasis +>Arts::StructureDesc</emphasis +>, a <emphasis +>Arts::ModuleDesc</emphasis +> e a <emphasis +>Arts::PortDesc</emphasis +>, as quais contêm uma descrição de uma estrutura, um módulo e um porto. Existe também uma forma de obter uma "rede viva de objectos" com essas descrições de ligações e valores, usando uma 'factory' (fábrica). </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>artsmidi.idl</term> + + <listitem +><para +>Este módulo define a funcionalidade básica de MIDI, com os objectos que produzem os eventos do MIDI, o que é um evento do MIDI, um <emphasis +>Arts::MidiManager</emphasis +> para se ligar aos produtores e aos consumidores de eventos MIDI, e assim por diante. Como sempre, está implícita a transparência da rede. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>artsmodules.idl</term> + <listitem +><para +>Aqui existem vários filtros, osciladores, efeitos, atrasos adicionais, entre outros objectos, sendo tudo necessário para o processamento útil de sinal, e para criar instrumentos e efeitos complexos a partir destes blocos de construção básicos. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>artsgui.idl</term> + + <listitem +><para +>Este preocupa-se com os objectos visuais. Ele define o tipo básico <emphasis +> Arts::Widget</emphasis +> a partir do qual todos os módulos gráficos derivam. Isto irá produzir uma independência da plataforma e .... edição gráfica visual, assim como a noção de GUIs com capacidades de serialização. Do mesmo modo, dado que os elementos gráficos têm atributos normais, os seus valores poderão ser ligados com facilidade a alguns módulos de processamento de sinal (isto é, o valor de uma barra deslizante à frequência de corte de um filtro). Como sempre: transparência de rede. </para +></listitem> + +</varlistentry> + +</variablelist> +<para +>Sempre que possível, o próprio aRts está implementado usando a IDL. Por outro lado, existem algumas APIs <emphasis +>específicas da linguagem</emphasis +>, usando tanto C++ ou C normal. É normalmente aconselhado usar as interfaces IDL sempre que possível, usando as outras APIs quando for mesmo necessário. Aqui está uma lista das APIs específicas da linguagem: </para> + +<variablelist> + +<varlistentry> +<term +>KNotify, KAudioPlayer (incluídos na 'libtdecore')</term> + + <listitem +><para +>Estas são APIs do KDE de conveniência para os casos simples e comuns, onde você apenas deseja tocar uma amostra. As APIs são em C++ normal, optimizado para o Qt/KDE, e o mais simples possíveis. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>libartsc</term> + <listitem +><para +>Uma interface em C simples para o servidor de som. Muito útil ao transformar aplicações legadas. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>libmcop</term> + + <listitem +><para +>Aqui é onde acontece toda a mágica do MCOP. A biblioteca contém as noções básicas que precisa de saber para criar uma aplicação de MCOP simples, o 'dispatcher', os temporizadores, a gestão de E/S e os pormenores internos que fazem o protocolo do MCOP funcionar em si. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>libartsflow</term> + <listitem +><para +>Para além da implementação do 'artsflow.idl', contém alguns utilitários como a conversão da taxa de amostragem. </para +></listitem> + +</varlistentry> + +<varlistentry> +<term +>libqiomanager</term> + + <listitem +><para +>A integração do MCOP no ciclo de eventos do Qt, quando você cria aplicações do Qt com o MCOP. </para +></listitem> + +</varlistentry> + +</variablelist> + + + +</sect1> +<sect1 id="knotify"> +<title +>knotify</title> +<para +>Ainda não escrito </para> +</sect1> + +<sect1 id="kaudioplayer"> +<title +>kaudioplayer</title> +<para +>Ainda não escrito </para> +</sect1> + +<sect1 id="libkmid"> +<title +>libkmid</title> +<para +>Ainda não escrito </para> +</sect1> + +<sect1 id="kmedia2"> +<title +>kmedia2</title> +<para +>Ainda não escrito </para> +</sect1> + +<sect1 id="soundserver"> +<title +>servidor de som</title> +<para +>Ainda não escrito </para> +</sect1> + +<sect1 id="artsflow"> +<title +>artsflow</title> +<para +>Ainda não escrito </para> +</sect1> + +<sect1 id="capi"> +<title +><acronym +>API</acronym +> do C</title> + +<sect2 id="capiintro"> +<title +>Introdução</title> + +<para +>A <acronym +>API</acronym +> de C do &arts; foi desenhada para tornar simples a criação e a transformação de aplicações simples de C para tirarem partido do servidor de som &arts;. Ele contém algumas funcionalidades de difusão (o envio de sequências de amostras para o <application +>artsd</application +>), quer bloqueantes quer não-bloqueantes). Para a maioria das aplicações, você simplesmente irá retirar as poucas chamadas de sistema que lidam com o seu dispositivo de áudio e substitui-las com as chamadas de &arts; apropriadas.</para> + +<para +>Foram feitas duas passagens como prova da teoria: o <application +>mpg123</application +> e o <application +>quake</application +>. Você poderá obter as correcções <ulink url="http://space.twc.de/~stefan/kde/download/artsc-patches.tar.gz" +>aqui</ulink +>. Sinta-se à vontade para enviar as suas próprias alterações para os responsáveis pelo &arts; ou pelos pacotes de 'software' multimédia, de modo a que possam integrar o suporte do &arts; no seu código.</para> + +</sect2> + +<sect2 id="capiwalkthru"> +<title +>Percurso Rápido</title> + +<para +>O envio de áudio para o servidor de som com a <acronym +>API</acronym +> é bastante simples:</para> +<procedure> +<step +><para +>incluir o ficheiro da API usando o <userinput +>#include <artsc.h></userinput +></para +></step> +<step +><para +>inicializar a <acronym +>API</acronym +> com o <function +>arts_init()</function +></para +></step> +<step +><para +>criar um canal com o <function +>arts_play_stream()</function +></para +></step> +<step +><para +>configurar os parâmetros específicos com o <function +>arts_stream_set()</function +></para +></step> +<step +><para +>escrever os dados das amostras para o canal com o <function +>arts_write()</function +></para +></step> +<step +><para +>fechar o canal com o <function +>arts_close_stream()</function +></para +></step> +<step +><para +>libertar a <acronym +>API</acronym +> com o <function +>arts_free()</function +></para +></step> +</procedure> + +<para +>Aqui está um pequeno programa de exemplo que ilustra isto:</para> + +<programlisting +>#include <stdio.h> +#include <artsc.h> +int main() +{ + arts_stream_t canal; + char dados[8192]; + int bytes; + int erro; + + erro = arts_init(); + if (erro < 0) + { + fprintf(stderr, "erro do arts_init: %s\n", arts_error_text(erro)); + return 1; + } + + canal = arts_play_stream(44100, 16, 2, "testeartsc"); + + while((bytes = fread(dados, 1, 8192, stdin)) > 0) + { + erro = arts_write(canal, dados, bytes); + if(erro < 0) + { + fprintf(stderr, "erro do arts_write: %s\n", arts_error_text(erro)); + return 1; + } + } + + arts_close_stream(canal); + arts_free(); + + return 0; +} +</programlisting> +</sect2> + +<sect2 id="capiartscconfig"> +<title +>Compilar e Gerar o Executável: <application +>artsc-config</application +></title> + +<para +>Para compilar e gerar os binários com facilidade, usando a <acronym +>API</acronym +> de C do &arts;, o utilitário <application +>artsc-config</application +> é fornecido e indica quais as bibliotecas que você precisa para compilar e onde se encontram os ficheiros de inclusão. É invocado com o comando</para> + +<screen +><userinput +><command +>artsc-config</command +> <option +>--libs</option +></userinput +> +</screen> + +<para +>para saber quais as bibliotecas e </para> + +<screen +><userinput +><command +>artsc-config</command +> <option +>--cflags</option +></userinput +> +</screen> + +<para +>para saber quais as opções adicionais do compilador de C. O exemplo acima poderia ter sido compilado com a linha de comandos:</para> + +<screen +><userinput +><command +>cc</command +> <option +>-o testeartsc testeartsc.c `artsc-config --cflags` `artsc-config --libs`</option +></userinput> + +<userinput +><command +>cc</command +> <option +>-o testeartsc</option +> <option +>testeartsc.c</option +> <option +>`artsc-config --cflags`</option +> <option +>`artsc-config --libs`</option +></userinput +> +</screen> + +</sect2> + +<sect2 id="c-api-reference"> +<title +>Referência das Bibliotecas</title> + +<para +>[TODO: gerar a documentação do artsc.h com o 'kdoc'] </para> + +</sect2> + +</sect1> +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/artsbuilder.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/artsbuilder.docbook new file mode 100644 index 00000000000..fd49688924d --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/artsbuilder.docbook @@ -0,0 +1,917 @@ +<chapter id="artsbuilder"> +<title +>&arts-builder;</title> + +<sect1 id="overview"> +<title +>Introdução</title> + +<para +>Primeiro que tudo, ao tentar correr o &arts-builder; , você deverá correr também o servidor de som (o &artsd;). Normalmente, quando você usa o &kde; 2.1, este já deverá ser o caso. Se não for, você poderá configurar o arranque automático do servidor de som no &kcontrol; em <menuchoice +><guilabel +>Som</guilabel +><guilabel +>Servidor de Som</guilabel +></menuchoice +>. </para> + +<para +>Quando você está a executar o &arts;, ele corre sempre módulos pequenos. O &arts-builder; é uma ferramenta para criar estruturas novas a partir de pequenos módulos interligados. Você simplesmente carrega os módulos para dentro da grelha. Para o fazer, escolha-os no menu <guimenu +>Módulos</guimenu +>, e carregue então algures no avião verde-e-cinzento. </para> + +<para +>Os módulos normalmente têm portos (onde normalmente entram e saem os sinais de áudio). Para ligar dois portos, carregue no primeiro, o que normalmente faz com que ele fique laranja, e carregue depois no segundo. Você poderá ligar apenas um porto de entrada (na parte de cima) com um porto de saída (na parte inferior de um módulo). Se você quiser atribuir um valor fixo a um porto (ou desligá-lo), faça duplo-click no mesmo. </para> + +</sect1> + +<sect1 id="artsbuilder-tutorial"> +<title +>Tutorial</title> + +<sect2 id="step-1"> +<title +>Passo 1</title> + +<para +>Inicie o &arts-builder;. </para> + +<para +>Você precisa de um módulo Synth_AMAN_PLAY para ouvir a saída que está a criar. Por isso crie um módulo Synth_AMAN_PLAY, seleccionando-o em <menuchoice +><guimenu +>Módulos</guimenu +> <guisubmenu +>Síntese</guisubmenu +> <guisubmenu +>E/S de Som</guisubmenu +> <guisubmenu +>Synth_AMAN_PLAY</guisubmenu +></menuchoice +> e carregue no espaço em branco do módulo. Coloque-o por baixo da quinta linha ou algo do género, porque serão adicionadas aqui algumas coisas. </para> + +<para +>O módulo irá ter um parâmetro <parameter +>title</parameter +> ou título (o porto do lado esquerdo), um <parameter +>autoRestoreID</parameter +> (ao lado do porto do lado esquerdo) para o encontrar. Para os preencher, faça duplo-click nesses portos, seleccione um valor constante e escreva <userinput +>tutorial</userinput +> no campo de texto. Carregue em <guibutton +>OK</guibutton +> para aplicar. </para> + +<para +>Seleccione <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Executar a estrutura</guimenuitem +> </menuchoice +>. Você não irá ouvir absolutamente nada. O módulo de reprodução ainda necessita de uma entrada... ;) Se você tiver 'ouvido' o silêncio um pouco, carregue em <guibutton +>OK</guibutton +> e vá para o Passo 2 </para> +</sect2> + +<sect2 id="step-2"> +<title +>Passo 2</title> + +<para +>Crie um módulo Synth_WAVE_SIN (em <menuchoice +> <guimenu +>Módulos</guimenu +> <guimenuitem +>Síntese</guimenuitem +> <guimenuitem +>Formas de onda</guimenuitem +></menuchoice +>) e coloque-o por cima do módulo Synth_AMAN_PLAY. (Deixe um espaço de uma linha entre eles). </para> + +<para +>Como poderá ver, ele produz algum resultado, mas necessita de um <guilabel +>pos</guilabel +> como entrada. Primeiro, vai-se ligar a saída ao altifalante. Carregue no porto <guilabel +>out</guilabel +> (saída) do módulo Synth_WAVE_SIN e depois no porto <guilabel +>left</guilabel +> (esquerda) do Synth_AMAN_PLAY. Pronto, você acabou de ligar dois módulos. </para> + +<para +>Todos os osciladores no &arts; não precisam de uma frequência à entrada, mas si de uma posição na onda. A posição deverá ser entre 0 e 1, o que se mapeia num objecto normal do Synth_WAVE_SIN no intervalo 0..2*pi. Para gerar os valores oscilantes para uma frequência, é usado um módulo Synth_FREQUENCY. </para> + +<para +>Crie um módulo Synth_FREQUENCY (em <menuchoice +> <guimenu +>Módulos</guimenu +> <guimenu +>Síntese</guimenu +> <guimenu +>Oscilação & Modulação</guimenu +> </menuchoice +>) e ligue a sua saída <quote +>pos</quote +> na entrada <quote +>pos</quote +> do seu Synth_WAVE_SIN. Indique o porto 'frequency' (frequência) do gerador FREQUENCY com um valor constante 440. </para> + + +<para +>Seleccione o <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Executar a estrutura</guimenuitem +></menuchoice +>. Irá ouvir uma onda sinusoidal de 440 Hz num dos seus altifalantes. Se você a tiver ouvido durante algum tempo, carregue em <guibutton +>OK</guibutton +> e vá para o Passo 3. </para> + +</sect2> + +<sect2 id="step-3"> +<title +>Passo 3</title> + +<para +>OK, seria melhor se você ouvir a onda sinusoidal em ambos os altifalantes. Ligue o porto 'right' (direita) do Synth_PLAY ao 'outvalue' (saída) do Synth_WAVE_SIN. </para> + +<para +>Crie um objecto Synth_SEQUENCE (em <menuchoice +><guimenu +>Módulos</guimenu +> <guisubmenu +>Síntese</guisubmenu +><guisubmenu +>MIDI & Sequenciação</guisubmenu +></menuchoice +>). Dever-se-á encontrar no topo do ecrã. Se precisar de mais espaço, você poderá mover os outros módulos, seleccionando-os (para seleccionar vários módulos use o &Shift;) e arrastando-os. </para> + +<para +>Agora ligue a saída 'frequency' (frequência) do Synth_SEQUENCE à entrada 'frequency' do módulo Synth_FREQUENCY. Depois, indique a velocidade da sequência como um valor constante 0,13 (o 'speed' ou velocidade é o porto mais à esquerda). </para> + +<para +>Agora vá ao porto mais à direita (o 'sequence' ou sequência) do Synth_SEQUENCE e escreva como valor constante <userinput +>A-3;C-4;E-4;C-4;</userinput +>; isto corresponde a uma sequência. Poderá ver mais sobre isto na Referência do Módulo. </para> + +<note> +<para +>O Synth_SEQUENCE <emphasis +>necessita</emphasis +> mesmo de uma sequência e da sua velocidade. Sem isto, você irá obter provavelmente alguns estoiros. </para> +</note> + +<para +>Seleccione o <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Executar a Estrutura</guimenuitem +></menuchoice +>. Você irá ver uma sequência bonita a tocar. Se gostou da sensação, carregue em <guibutton +>OK</guibutton +> e vá para o Passo 4. </para> +</sect2> + +<sect2 id="step-4"> +<title +>Passo 4</title> + +<para +>Crie um módulo Synth_PSCALE (em <menuchoice +><guimenu +>Módulos</guimenu +> <guisubmenu +>Síntese</guisubmenu +> <guisubmenu +>Envelopes</guisubmenu +> </menuchoice +>). Desligue o 'outvalue' (saída) da onda sinusoidal, fazendo duplo-click nela e escolher a opção <guilabel +>não ligado</guilabel +>. Ligue </para> + +<orderedlist +><listitem> +<para +>O valor de saída do SIN ao valor de entrada do PSCALE</para> +</listitem> +<listitem> +<para +>O valor de saída do PSCALE à esquerda do AMAN_PLAY</para> +</listitem> +<listitem> +<para +>O valor de saída do PSCALE à direita do AMAN_PLAY</para> +</listitem> +<listitem> +<para +>A posição do SEQUENCE à posição do PSCALE</para> +</listitem> +</orderedlist> + +<para +>Finalmente, configure o topo do PSCALE para um valor qualquer, por exemplo 0,1. </para> + +<para +>Como é que funciona então: o Synth_SEQUENCE dá informações adicionais sobre a posição da nota que está a tocar de momento, onde o 0 significa que começou agora e 1 significa que terminou. O módulo Synth_PSCALE irá ajustar o facto de escala do canal de áudio que é passado por ele, desde um volume 0 (silêncio) até 1 (volume original), voltando outra vez a 0 (silêncio), de acordo com a posição. A posição onde o pico deverá ocorrer poderá ser indicada no 'pos'. Um valor igual a 0,1 significa que, depois de ter tocado 10% da nota, o volume terá atingido o seu máximo, começando a decair a partir daí. </para> + + +<para +>Seleccione <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Executar a Estrutura</guimenuitem +></menuchoice +>. Você irá ouvir uma sequência bonita a tostou da situação, carregue em <guibutton +>OK</guibutton +> e vá para o Passo 5. </para> + +</sect2> + +<sect2 id="step-5-starting-to-beam-data-around"> +<title +>Passo 5: Começar a emitir os dados ;)</title> + +<para +>Inicie outro &arts-builder;</para> + +<para +>Coloque um Synth_AMAN_PLAY nele e configure-o para um nome aceitável. Coloque um Synth_BUS_DOWNLINK nele e:</para> + +<orderedlist> +<listitem> +<para +>Configure o barramento do Synth_BUS_DOWNLINK para áudio (isto é apenas um nome, chame-lhe 'manel' se quiser) </para> +</listitem> +<listitem> +<para +>Ligue a esquerda do Synth_BUS_DOWNLINK à esquerda do Synth_AMAN_PLAY </para> +</listitem> +<listitem> +<para +>Ligue a direita do Synth_BUS_DOWNLINK à direita do Synth_AMAN_PLAY </para> +</listitem> +</orderedlist> + +<para +>Comece a executar a estrutura. Como seria de esperar, não ouve nada, ... ainda. </para> + +<para +>Volte à estrutura com as coisas do Synth_WAVE_SIN e substitua o módulo Synth_AMAN_PLAY module por um Synth_BUS_UPLINK, configurando o seu nome para 'áudio' (ou 'manel', se preferir); os módulos poderão ser removidos se os seleccionar e escolher <menuchoice +><guimenu +>Editar</guimenu +> <guimenuitem +>Remover</guimenuitem +></menuchoice +> no menu (ou carregando na tecla <keycap +>Del</keycap +>). </para> + +<para +>Carregue em <menuchoice +><guimenu +>Ficheiro</guimenu +> <guilabel +>Executar a estrutura</guilabel +></menuchoice +>. Irá ouvir a sequência com as notas em escala, transportadas no barramento. </para> + +<para +>Se quiser saber porque é que algo como isto poderá de facto ser útil, carregue em <guibutton +>OK</guibutton +> (no &arts-builder; que está a executar o bloco do Synth_SEQUENCE; você poderá deixar o outro a correr) e ir para o Passo 6. </para> +</sect2> + +<sect2 id="step-6-beaming-for-advanced-users"> +<title +>Passo 6: Apontar para utilizadores avançados</title> + +<para +>Escolha a estrutura <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Mudar o nome</guimenuitem +> </menuchoice +> no menu do 'artsbuilder' que contém as coisas do Synth_SEQUENCE, chamando-lhe de 'tutorial'. Carregue em <guibutton +>OK</guibutton +>. </para> + +<para +>Seleccione <menuchoice +><guimenu +>Ficheiro</guimenu +> <guimenuitem +>Gravar</guimenuitem +> </menuchoice +> </para> + +<para +>Inicie ainda mais outro &arts-builder; e escolha <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Abrir</guimenuitem +> </menuchoice +>, e carregar o tutorial de novo. </para> + +<para +>Agora poderá seleccionar <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Executar a estrutura</guimenuitem +> </menuchoice +> em ambos os &arts-builder;s que têm estrutura. Você irá ouvir agora duas vezes a mesma coisa. Dependendo da altura em que os inicia, irá soar melhor ou pior. </para> + +<para +>Outra coisa boa para fazer nesta altura é: iniciar o &noatun; e tocar um <literal role="extension" +>mp3</literal +> qualquer. Inicie o &artscontrol;. Vá a <menuchoice +><guimenu +>Ver</guimenu +><guimenuitem +>Ver o gestor de áudio</guimenuitem +></menuchoice +>. O que irá ver será o &noatun; e a sua estrutura de reprodução <quote +>tutorial</quote +> a tocar algo. Uma coisa interessante que poderá fazer é o seguinte: faça duplo-click no &noatun;. Irá agora obter uma lista com os barramentos disponíveis. Verá também que poderá indicar ao &noatun; para enviar a sua saída através do barramento de áudio que a sua estrutura do tutorial oferece. </para> +</sect2> + +<sect2 id="step-7-midi-synthesis"> +<title +>Passo 7: Síntese MIDI</title> + +<para +>Finalmente, você deverá agora ser capaz de transformar a sua onda sinusoidal num instrumento real. Só faz sentido se você tiver algo útil que possa enviar eventos de &MIDI; para o &arts;. Será descrito aqui como você poderá usar um teclado externo qualquer, mas uma solução de sequenciação MIDI como o &brahms; irá funcionar da mesma forma. </para> + +<para +>Primeiro que tudo, limpe o seu ecrã até que você tenha apenas um &arts-builder; com a estrutura da onda sinusoidal aberta (mas não em execução). De seguida, vá três vezes a <menuchoice +><guimenu +>Portos</guimenu +> <guisubmenu +>Criar sinal de áudio IN</guisubmenu +></menuchoice +>, e outras três a <menuchoice +><guimenu +>Portos</guimenu +> <guisubmenu +>Criar sinal de áudio OUT</guisubmenu +></menuchoice +>. Coloque esses portos algures. </para> + +<para +>Finalmente, vá a <menuchoice +><guimenu +>Portos</guimenu +> <guilabel +>Mudar as posições e nomes</guilabel +></menuchoice +> e chame aos portos 'frequency' (frequência), 'velocity' (velocidade), 'pressed' (carregado), 'left' (esquerdo), 'right' (direito), 'done' (pronto). </para> + +<para +>Finalmente, você poderá remover o módulo Synth_SEQUENCE e ligar o porto de entrada 'frequency' (frequência) da estrutura ao porto 'frequency' do Synth_FREQUENCY. Hm... Mas o que fazer com o 'pos'?</para +> <para +>Não existe isso, porque não há nenhum algoritmo no mundo onde você possa prever quando é que o utilizador solta a nota que acabou de carregar no teclado MIDI. Por isso, existe um parâmetro 'pressed' (carregado) que indica se o utilizador ainda tem a tecla pressionada ou não ('pressed' = 1: a tecla ainda está carregada, 'pressed' = 0: tecla solta) </para> + +<para +>Isto significa que o objecto Synth_PSCALE também precisa de ser substituído agora. Ligue um Synth_ENVELOPE_ADSR em alternativa (em <menuchoice +><guimenu +>Módulos</guimenu +> <guisubmenu +>Síntese</guisubmenu +> <guisubmenu +>Envelopes</guisubmenu +> </menuchoice +>). Ligue: </para> + +<orderedlist> +<listitem> +<para +>A entrada 'pressed' da estrutura ao 'active' (activo) do ADSR</para> +</listitem> +<listitem> +<para +>O valor de saída do SIN ao valor de entrada do PSCALE</para> +</listitem> +<listitem> +<para +>O valor de saída do ADSR à saída 'left' (esquerda) da estrutura</para> +</listitem +><listitem> +<para +>O valor de saída do ADSR à saída 'right' (direita) da estrutura</para> +</listitem> +</orderedlist> + +<para +>Configure os parâmetros 'attack' (ataque) igual a 0,1, 'decay' (decaimento) igual a 0,2, 'sustain' (sustentação) igual a 0,7 e 'release' (soltura) igual a 0,1. </para> + +<para +>Outra coisa em que é preciso pensar é que a estrutura do instrumento precisa de saber de alguma forma quando é que está pronta para tocar e quando poderá ser limpa, porque caso contrário nunca seria interrompida, mesmo que a nota tivesse sido solta. Felizmente, o envelope do ADSR sabes quando não há mais nada para se ouvir, dado que ele iguala o sinal a zero nalgum ponto em que a nota foi solta. </para> + +<para +>Isto é indicado ao pôr a saída 'done' (pronto) igual a 1. Por isso, ligue isto à saída 'done' da estrutura. A mesma será removida logo que o 'done' passe a 1. </para> + +<para +>Mude o nome da sua estrutura para 'instrument_tutorial' (em <menuchoice +><guimenu +> Ficheiro</guimenu +> <guimenuitem +>Mudar o nome da estrutura</guimenuitem +></menuchoice +>. De seguida, grave-a usando o Gravar Como (o nome por omissão que é oferecido deverá ser agora igual a 'instrument_tutorial').</para +><para +>Inicie o 'artscontrol' e vá a <menuchoice +><guimenu +>Ver</guimenu +><guimenuitem +>Gestor de MIDI</guimenuitem +></menuchoice +>, escolhendo depois a opção <menuchoice +><guimenu +>Adicionar</guimenu +><guimenuitem +>Saída MIDI de Síntese do aRts</guimenuitem +></menuchoice +>. Finalmente, você deverá ser capaz de seleccionar o seu instrumento de tutorial aqui. </para> + +<para +>Abra um terminal e escreva <userinput +><command +>midisend</command +></userinput +>. Você irá ver que o <command +>midisend</command +> e o instrumento estão agora listados no gestor de &MIDI; do &arts;. Depois de seleccionar ambos e de carregar em <guibutton +>Ligar</guibutton +>, é tudo. Pegue no seu teclado e comece a tocar (obviamente, terá de estar ligado ao seu computador). </para> +</sect2> + +<sect2 id="suggestions"> +<title +>Sugestões</title> + +<para +>Agora você deverá ser capaz de trabalhar com o &arts;. Ficam aqui algumas dicas que você poderá tentar para melhorar com as suas estruturas: </para> + +<itemizedlist> +<listitem> +<para +>Tente usar outras coisas para além de uma onda sinusoidal. Quando ligar uma onda triangular, você irá pensar que o som não é grande coisa. Mas tente adicionar um filtro SHELVE_CUTOFF logo a seguir à onda triangular para cortar as frequências acima de uma dada frequência (tente algo do género de 1000 Hz, ou mesmo duas vezes a frequência de entrada ou igual à frequência de entrada+200Hz, ou qualquer outra coisa do género). </para> +</listitem> +<listitem> +<para +>Tente usar mais do que um oscilador. O Synth_XFADE poderá ser usado para misturar dois sinais; use por outro lado o Synth_ADD para os adicionar. </para> +</listitem> +<listitem> +<para +>Tente configurar as frequências dos osciladores para valores diferentes; isto dará umas oscilações engraçadas. </para> +</listitem> +<listitem> +<para +>Experimente com mais do que um envelope. </para> +</listitem> +<listitem> +<para +>Tente sintetizar os instrumentos com resultados diferentes do lado esquerdo e do direito. </para> +</listitem> +<listitem> +<para +>Tente fazer o pós-processamento depois de sair da ligação de recepção do barramento. Você poderá misturar, por exemplo, uma versão atrasada do sinal ao sinal original para obter um efeito de eco. </para> +</listitem> +<listitem> +<para +>Tente usar a opção 'velocity' (velocidade), a qual corresponde à força com que a nota foi carregada, e poderá também dizer 'volume'). O efeito especial consiste em não só modificar o volume do sinal resultante, mas também o som do instrumento (como por exemplo a frequência de corte). </para> +</listitem> +<listitem> +<para +>...</para> +</listitem> +</itemizedlist> + +<para +>Se você criou algo engraçado, pense por favor em fornecê-lo à página Web do &arts; ou para ser incluído na próxima versão. </para> +</sect2> + +</sect1> + +<sect1 id="artsbuilder-examples"> +<title +>Exemplos</title> + +<para +>O &arts-builder; vem com vários exemplos, os quais poderão ser acedidos através da opção <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Abrir um Exemplo...</guimenuitem +> </menuchoice +>. Alguns deles estão na sua pasta correspondente, enquanto que outros (os quais não funcionam por uma razão qualquer na versão actual) são deixados na pasta 'todo'. </para> +<para +>Os exemplos caem em várias categorias: </para> + +<itemizedlist> +<listitem> +<para +>Os exemplos autónomos que ilustram como usar cada um dos módulos incorporados do 'arts' (chamados <filename +>example_*.arts</filename +>). Estes tipicamente enviam um resultado qualquer para uma placa de som. </para> +</listitem> + +<listitem> +<para +>Os instrumentos que são criados a partir de módulos de nível mais baixo (chamados de <filename +>instrument_*.arts</filename +>). Estes seguem uma convenção normal para os portos de entrada e saída para que possam ser usados no gestor de &MIDI; no &artscontrol;. </para> +</listitem> + +<listitem> +<para +>Os modelos para criar novos módulos (denominados por <filename +>template_*.arts</filename +>). </para> +</listitem> + +<listitem> +<para +>Os efeitos que poderão ser usados como blocos de construção reutilizáveis (chamados de <filename +>effect_*.arts</filename +>) [ tudo no 'todo' ] </para> +</listitem> + +<listitem> +<para +>Os elementos de mistura usados para criar mesas de mistura, incluindo os controlos gráficos (chamados de <filename +>mixer_element_*.arts</filename +>). [ tudo no 'todo' ] </para> +</listitem> + +<listitem> +<para +>Módulos diversos que não se encaixam em nenhuma das categorias acima. </para> +</listitem> +</itemizedlist> + +<variablelist> +<title +>Descrição Detalhada de Cada Módulo:</title> +<varlistentry> +<term +><filename +>example_stereo_beep.arts</filename +></term> +<listitem> +<para +>Gera uma onda sinusoidal de 440Hz no canal esquerdo e uma onda sinusoidal no canal direito, enviando o resultado para a saída da placa de som. Isto é referenciado na documentação do &arts;. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_sine.arts</filename +></term> +<listitem> +<para +>Gera uma onda sinusoidal de 440 Hx. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_pulse.arts</filename +></term> +<listitem> +<para +>Gera uma onda de impulsos de 440 Hz com um tempo de actividade de 20%. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_softsaw.arts</filename +></term> +<listitem> +<para +>Gera uma onda de dente-de-serra de 440 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_square.arts</filename +></term> +<listitem> +<para +>Gera uma onda quadrada de 440 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_tri.arts</filename +></term> +<listitem> +<para +>Gera uma onda triangular de 440 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_noise.arts</filename +></term> +<listitem> +<para +>Gera 'ruído branco'. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_dtmf1.arts</filename +></term> +<listitem> +<para +>Gera um tom duplo, produzindo para tal ondas sinusoidais de 697 e 1209 Hz, ajustando a escala para 0,5 e adicionando-as em conjunto. Isto é o tom DTMF para o número "1" num teclado de telefone. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_atan_saturate.arts</filename +></term> +<listitem> +<para +>Corre uma onda triangular com o filtro de saturação 'atan' (arco-tangente). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_autopanner.arts</filename +></term> +<listitem> +<para +>Usa um deslocador automático para deslocar uma onda sinusoidal de 400 Hz entre os altifalantes esquerdo e direito a um ritmo de 2 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_brickwall.arts</filename +></term> +<listitem> +<para +>Ajusta a escala de uma onda sinusoidal por um factor de 5 e passa-a por um limitador. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_bus.arts</filename +></term> +<listitem> +<para +>Recebe de um barramento chamado <quote +>Bus</quote +> (Barramento) e envia para o barramento <quote +>out_soundcard</quote +> (saída da placa de som) com os canais esquerdo e direito invertidos. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_cdelay.arts</filename +></term> +<listitem> +<para +>Recebe de um barramento chamado <quote +>Delay</quote +> (Atraso), envia o canal direito através de um atraso de 0,5 segundos e o esquerdo sem alterações. Você poderá usar o &artscontrol; para ligar o efeito a um reprodutor de som e observar os resultados. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_delay.arts</filename +></term> +<listitem> +<para +>Este é o mesmo que o <filename +>example_cdelay.arts</filename +> mas usando o efeito de atraso. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_capture_wav.arts</filename +></term> +<listitem> +<para +>Isto usa o Synth_CAPTURE_WAV para gravar uma onda sinusoidal de 400 Hz como um ficheiro WAV. Execute o módulo durante uns segundos e examine depois o ficheiro criado em <filename class="directory" +>/tmp</filename +>. Você poderá tocar o ficheiro com um leitor multimédia como o <application +>noatun</application +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_data.arts</filename +></term> +<listitem> +<para +>Isto usa o módulo Data (Dados) para gerar uma sequência constante com o valor <quote +>3</quote +> e envia-a para um módulo Debug (Depuração) que o mostra periodicamente. Também contém um módulo Nil (Nada), que ilustra como poderá ser usado para não fazer absolutamente nada. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_adsr.arts</filename +></term> +<listitem> +<para +>Mostra como criar um único som de um instrumento com o módulo 'Envelope Adsr' (ADSR do Envelope), despoletado repetidamente por uma onda quadrada. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_fm.arts</filename +></term> +<listitem> +<para +>Isto usa o módulo de Fonte FM para gerar uma onda sinusoidal de 440 Hz que é modulada na frequência a uma taxa de 5 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_freeverb.arts</filename +></term> +<listitem> +<para +>Isto liga o efeito do Freeverb a partir do canal de recepção de um barramento a um canal de envio de outro barramento. Você poderá usar o &artscontrol; para ligar o efeito a um leitor de áudio e observar os resultados. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_flanger.arts</filename +></term> +<listitem> +<para +>Isto implementa um efeito simples de 'flanger' (não parece funcionar ainda, no entanto). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_moog.arts</filename +></term> +<listitem> +<para +>Esta estrutura combina os dois canais de um barramento num só, passando-o através do filtro VCF Moog, e envia o resultado para o barramento 'out_soundcard'. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_pitch_shift.arts</filename +></term> +<listitem> +<para +>Esta estrutura passa o canal esquerdo dos dados da placa de som através do efeito 'Pitch Shift' (Desvio de Tom). Ajuste o parâmetro 'speed' (velocidade) para variar o efeito. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_rc.arts</filename +></term> +<listitem> +<para +>Esta estrutura passa um gerador de 'ruído branco' através de um filtro RC para a placa de som. Ao ver no Osciloscópio de FFT do &artscontrol;, você poderá ver como isto varia numa forma de onda de ruído não filtrada. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_sequence.arts</filename +></term> +<listitem> +<para +>Isto demonstra o módulo Sequence (sequência), tocando para tal uma sequência de notas. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_shelve_cutoff.arts</filename +></term> +<listitem> +<para +>Esta estrutura passa um gerador de 'ruído branco' através de um filtro 'Shelve Cutoff' para a placa de som. Ao ver no Osciloscópio de FFT do &artscontrol;, você poderá ver como isto varia numa forma de onda de ruído não filtrada. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_equalizer.arts</filename +></term> +<listitem> +<para +>Isto demonstra o módulo 'Std_Equalizer'. Ele aumenta de 6 dB as frequências altas e baixas. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_tremolo.arts</filename +></term> +<listitem> +<para +>Isto demonstra o efeito Tremolo. Ele modula os canais esquerdo e direito usando um tremolo de 10 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_xfade.arts</filename +></term> +<listitem> +<para +>Este exemplo mistura ondas sinusoidais de 440 e 880 Hz com um misturador cruzado. Ajuste o valor da percentagem do misturador de -1 até 1 para controlar a mistura dos dois sinais. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_pscale.arts</filename +></term> +<listitem> +<para +>Isto ilustra o módulo do Pscale (não é certo se este será um exemplo compreensível). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><filename +>example_play_wav.arts</filename +></term> +<listitem> +<para +>Isto ilustra o módulo 'Play Wave' (Tocar um WAVE). Você terá de indicar a localização completa de um ficheiro <literal role="extension" +>.wav</literal +> como valor do parâmetro 'filename' (nome do ficheiro). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>example_multi_add.arts</term> +<listitem> +<para +>Isto mostra o módulo Multi Add (Adição Múltipla), o qual aceita um número qualquer de entradas. Ele soma três módulos de dados que produzem entradas de 1, 2 e 3, mostrando depois o resultado 6. </para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/detail.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/detail.docbook new file mode 100644 index 00000000000..1f4d3e43f63 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/detail.docbook @@ -0,0 +1,1388 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-in-detail"> +<title +>O &arts; em Detalhe</title> + +<sect1 id="architecture"> +<title +>Arquitectura</title> + +<mediaobject> +<imageobject> +<imagedata fileref="arts-structure.png" format="PNG"/> +</imageobject> +<textobject +><phrase +>A estrutura do &arts;.</phrase +></textobject> +</mediaobject> +</sect1> + +<sect1 id="modules-ports"> +<title +>Módulos & Portos</title> + +<para +>A ideia do &arts; é que a síntese pode ser feita com módulos pequenos que só fazem uma coisa, voltando a combiná-los depois em estruturas complexas. Os pequenos módulos normalmente têm entradas, onde poderão obter alguns sinais ou parâmetros, e saídas, onde produzirão alguns sinais. </para> + +<para +>Um módulo (o Synth_ADD), por exemplo, apanha simplesmente os dois sinais à entrada e adiciona-os em conjunto. O resultado fica disponível como um sinal de saída. Os locais onde os módulos oferecem os seus sinais de entrada e saída chamam-se portos. </para> + +</sect1> + +<sect1 id="structures"> +<title +>Estruturas</title> + +<para +>Uma estrutura é uma combinação de módulos ligados, alguns dos quais têm parâmetros codificados directamente nos seus portos de entrada, outros que poderão estar ligados e outros ainda que não estão ligados de todo. </para> + +<para +>O que você pode fazer com o &arts-builder; é descrever as estruturas. Você descreve quais os módulos que quer que estejam ligados com outros módulos. Quando terminar, você poderá gravar a descrição dessa estrutura num ficheiro, ou dizer ao &arts; para criar essa estrutura que descreveu (Executar). </para> + +<para +>Aí você irá provavelmente ouvir algum som, se fez tudo correctamente. </para> +</sect1> + +<!-- TODO + +<sect1 id="streams"> +<title +>Streams</title> + +</sect1> + +--> + +<sect1 id="latency"> +<title +>Latência</title> + +<sect2 id="what-islatency"> +<title +>O Que é a Latência?</title> + +<para +>Suponha que tem uma aplicação chamada <quote +>pling_rato</quote +> (que fará um som de um <quote +>pling</quote +> se carregar num botão). A latência é o tempo que passa entre você pressionar o botão do rato com o seu dedo e você ouvir o som. A latência nesta configuração compõe-se por si só em várias latências, que poderão ter causas diferentes. </para> + +</sect2> + +<sect2 id="latenbcy-simple"> +<title +>Latência em Aplicações Simples</title> + +<para +>Nesta aplicação simples, a latência ocorre nestes sítios: </para> + +<itemizedlist> + +<listitem> +<para +>O tempo até o 'kernel' notificar o servidor do X11 que foi carregado um botão do rato. </para> +</listitem> + +<listitem> +<para +>O tempo até o servidor do X11 notificar a sua aplicação que um botão do rato foi pressionado. </para> +</listitem> + +<listitem> +<para +>O tempo até à aplicação 'pling_rato' decidir que este botão merece tocar um 'pling'. </para> +</listitem> + +<listitem> +<para +>O tempo que leva à aplicação 'pling_rato' dizer ao servidor de som que deverá tocar um 'pling'. </para> +</listitem> + +<listitem> +<para +>O tempo que leva para o 'pling' (que o servidor de som começa a misturar com a outra saída ao mesmo tempo) vá para os dados dos 'buffers', até que atinge a posição onde a placa de som reproduz o toque. </para> +</listitem> + +<listitem> +<para +>O tempo que leva o som do 'pling' dos altifalantes a atingir o seu ouvido. </para> +</listitem> +</itemizedlist> + +<para +>Os primeiros três itens são latências externas ao &arts;. Elas são interessantes, mas saem do âmbito deste documento. Todavia, tenha em atenção que elas existem, por isso, mesmo que você tenha optimizado tudo o resto para valores muito baixos, você poderá não obter exactamente o resultado que calculou. </para> + +<para +>Indicar ao servidor para tocar qualquer coisa envolve normalmente uma única chamada de &MCOP;. Existem medidas que confirmam isso, na mesma máquina e usando 'sockets' do domínio Unix, que dizem que, para dizer ao servidor para tocar algo, poderão ser feitas cerca de 9000 invocações por segundo na implementação actual. Espera-se que a maioria disto seja devido à sobrecarga no 'kernel', na mudança de uma aplicação para outra. Claro que este valor altera com o tipo exacto dos parâmetros. Se você transferir uma imagem inteira numa chamada, a chamada será mais lenta do que se transferir um valor inteiro. Aplica-se o mesmo para o valor devolvido. Contudo, para as cadeias de caracteres (como o nome do ficheiro <literal role="extension" +>WAV</literal +> a tocar), isto não deverá ser nenhum problema. </para> + +<para +>Isto significa que podemos aproximar este tempo a 1/9000 sec, o que fica abaixo de 0.15 ms. Concluir-se-á que isto não é relevante. </para> + +<para +>A seguir vem o tempo entre o servidor começar a tocar e a placa de som a obter algo. O servidor precisa de armazenar os dados temporariamente em tampões ('buffers'), por isso quando as outras aplicações começarem a executar, como o seu servidor de X11 ou a aplicação <quote +>pling_rato</quote +> não se poderão ouvir quebras. A forma como isso é feito no &Linux; é recorrendo a um conjunto de fragmentos de determinado tamanho. O servidor voltará a preencher os fragmentos, e a placa de som irá reproduzi-los. </para> + +<para +>Por isso, suponha que existem três fragmentos. O servidor preenche o primeiro, e a placa de som começa a tocá-lo. O servidor preenche o segundo e o terceiro, terminando assim a sua parte. As outras aplicações podem agora fazer algo. </para> + +<para +>Dado que a placa de som acabou de tocar o primeiro fragmento, começa a tocar o segundo e o servidor volta a preencher o primeiro, repetindo este processo indefinidamente. </para> + +<para +>A maior latência que você obtém com tudo isto é igual a (número de fragmentos)*(tamanho de cada fragmento)/(taxa amostragem * (tamanho de cada amostra)). Suponha que tem estéreo a 44kHz, com 7 fragmentos de 1024 bytes (o valor por omissão actual do &arts;): isso irá corresponder a 40 ms. </para> + +<para +>Estes valores poderão ser ajustados de acordo com as suas necessidades. Todavia, a utilização do <acronym +>CPU</acronym +> aumenta com latências menores, dado que o servidor de som terá de preencher os tampões com maior frequência e em menores partes. É também quase impossível atingir valores melhores sem dar ao servidor de som a prioridade de tempo-real, porque caso contrário irá ter frequentes quebras. </para> + +<para +>Contudo, é realista ter algo como 3 fragmentos de 256 bytes cada, o que iria fazer com que este valor fosse igual a 4,4 ms. Com um atraso de 4,4ms a utilização inactiva do <acronym +>CPU</acronym +> seria de aproximadamente 7,5% por parte do &arts;. Com um atraso de 40ms, seria de aproximadamente 3% (num PII-350, e este valor poderá depender da sua placa de som, versão do 'kernel', entre outros). </para> + +<para +>Agora, finalmente, tem o tempo que leva o som do 'pling' a sair dos altifalantes e a chegar ao seu ouvido. Suponha que a sua distância até aos altifalantes é de 2 metros. O som viaja à velocidade de 330 metros por segundo. Por isso, esse tempo poder-se-á aproximar a 6 ms. </para> + +</sect2> + +<sect2 id="latency-streaming"> +<title +>Latência em Aplicações de Transmissão</title> + +<para +>As aplicações de transmissão ou difusão são aquelas que produzem elas próprias o som, e que origina uma sequência constanted de amostras, e que será agora adapto para reproduzir as coisas através do &arts;. Por exemplo: quando se pressiona uma tecla, a figura que está a tocar salta, aparecendo um som de 'boing'. </para> + +<para +>Primeiro que tudo, você precisa de saber como é que o &arts; faz a transmissão. É bastante semelhante às E/S com a placa de som. O jogo envia alguns pacotes com amostras para o servidor de som. Imagine-se que são três pacotes. Assim que o servidor estiver pronto com o primeiro pacote, envia uma confirmação de volta para o jogo a dizer que este pacote está pronto. </para> + +<para +>O jogo cria outro pacote de som e envia-o para o servidor. Entretanto o servidor começa a consumir o segundo pacote de som, e assim por diante. A latência aqui é semelhante à do caso simples: </para> + +<itemizedlist> +<listitem> +<para +>O tempo até que o 'kernel' notifique o servidor de X11 que uma tecla foi carregada. </para> +</listitem> + +<listitem> +<para +>O tempo até que o servidor de X11 notifique o jogo de que uma tecla foi carregada. </para> +</listitem> + +<listitem> +<para +>O tempo até que o jogo se decida que esta tecla merece tocar um 'boing'. </para> +</listitem> + +<listitem> +<para +>O tempo até o pacote de som onde o jogo começou a colocar o som do 'boing' leva a chegar ao servidor de som. </para> +</listitem> + +<listitem> +<para +>O tempo que leva ao 'boing' (que o servidor de som começa a misturar para de uma vez) passe para os dados nos tampões ('buffers'), até que atinja a posição em que a placa de som começa a tocar. </para> +</listitem> + +<listitem> +<para +>O tempo que o 'boing' leva a sair dos altifalantes até atingir o seu ouvido. </para> +</listitem> + +</itemizedlist> + +<para +>As latências externas, tal como acima, estão fora do âmbito deste documento. </para> + +<para +>Obviamente, a latência da transmissão depende do tempo que leva a todos os pacotes que são usados na transmissão a serem tocados uma vez. Deste modo, é igual a (número de pacotes)*(taxa de amostragem * (tamanho de cada amostra)) </para> + +<para +>Como você vê, é a mesma fórmula que se aplica para os fragmentos. Contudo, para os jogos, não faz sentido fazer demoras tão pequenas. Pode-se dizer que uma configuração realista para os jogos seria de 2048 bytes por pacote, usando 3 pacotes. A latência resultante seria de 35 ms. </para> + +<para +>Isto baseia-se no seguinte: assuma que o jogo desenha 25 imagens por segundo. É provavelmente seguro assumir que você não notará nenhuma diferença na saída de som para uma imagem. Por isso, 1/25 segundos para a transmissão é aceitável, o que por sua vez significa que 40 ms seria ok. </para> + +<para +>A maioria das pessoas também não irão executar os seus jogos, com prioridade de tempo-real, onde o perigo de quebras no som não pode ser negligenciado. A transmissão com 3 pacotes de 256 bytes cada é possível (tentou-se isso) - mas provoca uma carga grande de <acronym +>CPU</acronym +> para a transmissão. </para> + +<para +>para as latências do lado do servidor, você pode calculá-las exactamente como está dito em cima. </para> + +</sect2> + +<sect2 id="cpu-usage"> +<title +>Algumas considerações de utilização do <acronym +>CPU</acronym +></title> + +<para +>Existem vários factores que influenciam a utilização do <acronym +>CPU</acronym +> num cenário complexo, com algumas aplicações de transmissão entre outras, alguns 'plugins' no servidor, &etc;. Só para indicar algumas: </para> + +<itemizedlist> +<listitem> +<para +>Utilização em bruto de <acronym +>CPU</acronym +> pelos cálculos que são necessários. </para> +</listitem> + +<listitem> +<para +>A sobrecarga do escalonamento interno do &arts; - como é que o &arts; decide qual o módulo que deve calcular o quê. </para> +</listitem> + +<listitem> +<para +>A sobrecarga da conversão de inteiros para números de vírgula flutuante. </para> +</listitem> + +<listitem> +<para +>A sobrecarga do protocolo &MCOP;. </para> +</listitem> + +<listitem> +<para +>'Kernel': mudança de contexto/processo. </para> +</listitem> + +<listitem> +<para +>'Kernel': sobrecarga nas comunicações </para> +</listitem> +</itemizedlist> + +<para +>Para a carga em bruto do <acronym +>CPU</acronym +> usada nos cálculos, se você tocar duas sequências em simultâneo, você terá de efectuar somas. Se você aplicar um filtro, estão envolvidos alguns cálculos. Para dar um exemplo simplificado, a adição de duas sequências envolve talvez quatro ciclos de <acronym +>CPU</acronym +> por soma, o que num processador a 350MHz corresponde a 44100*2*4/350000000 = 0,1% utilização do <acronym +>CPU</acronym +>. </para> + +<para +>Escalonamento interno do &arts;: o &arts; precisa de decidir qual o 'plugin' que irá calcular um dado conjunto de dados; isto leva tempo. Faça uma análise da performance se você estiver interessado nisso. Geralmente o que se pode dizer é: quanto menos de tempo-real fizer (&ie;. quanto maiores os blocos que poderão ser calculados numa dada altura), a menor sobrecarga de escalonamento você obterá. Acima do cálculo de blocos de 128 amostras de cada vez (usando deste modo tamanhos de fragmentos de 512 bytes), a sobrecarga no escalonamento não será grave. </para> + +<para +>Conversão de inteiros para números de vírgula flutuante: o &arts; usa números de vírgula flutuante internamente como formato de dados. Este são simples de usr e nos processadores mais recentes não são mais lentos do que as operações com inteiros. Contudo, se existirem clientes que lidem com dados que não estejam em vírgula flutuante (como um jogo que deverá fazer a sua saída de som através do &arts;), estes precisam de ser convertidos. O mesmo aplica-se que você quiser reproduzir os sons na sua placa de som. A placa de som está à espera de inteiros, por isso você terá de converter. </para> + +<para +>Aqui estão números para um Celeron, da quantidade aproximada de 'ticks' por amostra, com o egcs 2.91.66 com a opção -O2 (dados de Eugene Smith <email +>hamster@null.ru</email +>). Isto é altamente dependente do processador, como é óbvio: </para> + +<programlisting +>convert_mono_8_float: 14 +convert_stereo_i8_2float: 28 +convert_mono_16le_float: 40 +interpolate_mono_16le_float: 200 +convert_stereo_i16le_2float: 80 +convert_mono_float_16le: 80 +</programlisting> + +<para +>Por isso significa 1% de utilização do <acronym +>CPU</acronym +> para a conversão e 5% para a interpolação para este processador de 350 MHz. </para> + +<para +>A sobrecarga que o protocolo &MCOP; provoca; este protocolo origina, como regra de algibeira, 9000 invocações por segundo. Muitas destas não são culpa do protocolo &MCOP; em si, mas relaciona-se com as duas causas do 'kernel' indicadas em baixo. Contudo, isto fornece uma base para cálculo do quanto custa a transmissão. </para> + +<para +>Cada pacote de dados que é transmitido poderá ser considerado uma invocação do &MCOP;. Claro que os pacotes grandes são mais lentos do que 9000 pacotes/s, mas isto é a ideia básica. </para> + +<para +>Suponha que você usa tamanhos de pacotes de 1024 bytes. Deste modo, para transferir uma sequência estéreo de 44kHz, você precisa de transferir 44100*4/1024 = 172 pacotes por segundo. Suponha que po100% de utilização de CPU, 9000 pacotes, então iria obter (172*100)/9000 = 2% de utilização de <acronym +>CPU</acronym +> devido à transmissão de pacotes de 1024 bytes. </para> + +<para +>Existem aproximações. Contudo, estas mostram que você poderia estar muito melhor (se o poder fazer para o bem da latência), se usasse por exemplo pacotes de 4096 bytes. Pode-se fazer aqui uma fórmula compacta, calculando o tamanho do pacote que provoca uma utilização de 100% do <acronym +>CPU</acronym +> como sendo igual a 44100*4/9000 = 19,6 amostras, obtendo assim a fórmula rápida: </para> + +<para +>utilização de <acronym +>CPU</acronym +> na transmissão em percentagem = 1960/(tamanho do seu pacote) </para> + +<para +>o que dará 0,5% de utilização do <acronym +>CPU</acronym +> ao transmitir com pacotes de 4096 bytes. </para> + +<para +>Mudança de contextos/processos do 'kernel': isto faz parte da sobrecarga do protocolo &MCOP;. A mudança entre dois processos leva tempo. Existe um novo mapeamento de memória, as 'caches' são invalidadas, entre outras coisas (se existir alguém experiente no 'kernel' a ler isto - que diga quais são as causas exactas). Tudo isto para dizer: leva tempo. </para> + +<para +>Não é certo quantas mudanças de contexto o I &Linux; consegue fazer por segundo, mas esse número não é infinito. Por isso, muita parte da sobrecarga do protocolo &MCOP; deve-se, supostamente, em grande medida à mudança de contextos. No início do &MCOP;, foram feitos testes para usar a mesma comunicação dentro de um processo e isso era muito mais rápido (quatro vezes mais rápido, aproximadamente). </para> + +<para +>'Kernel': sobrecarga na comunicação: Isto faz parte da sobrecarga do protocolo &MCOP;. A transferência de dados entre processos é feita de momento, recorrendo a 'sockets'. Isto é conveniente, dado que os métodos normais do select() podem ser usados para determinar quando chegou uma mensagem. Também pode ser combinado com ou E/S de áudio, o servidor do X11 ou outras fontes, com relativa facilidade. </para> + +<para +>Contudo, estas chamadas de leitura e escrita custam certamente ciclos processador. Para as invocações pequenas (como a transferência de um evento MIDI), isso não é provavelmente assim tão mau, mas para as chamadas pesadas (como a transferência de uma imagem de vídeo com vários megabytes), isto é claramente um problema. </para> + +<para +>A utilização de memória partilhada no &MCOP;, sempre que apropriado, é provavelmente a melhor solução. Isto deverá ser feito de forma transparente para o programador da aplicação. </para> + +<para +>Obtenha um analisador ('profiler') ou faça outros testes para descobrir exactamente como é que a transmissão de áudio tem impacto se usar ou não memória partilhada. Contudo, não é mau, dado que a transmissão de áudio (reproduzir MP3s, por exemplo) poderá ser feita com utilização total de 6% de carga do <acronym +>CPU</acronym +> pelo &artsd; e pelo <application +>artscat</application +> (e 5% pelo descodificador de MP3). Contudo, isto inclui todas as coisas, desde os cálculos necessários até à sobrecarga nos 'sockets', por isso poder-se-á dizer que, nesta configuração, você poderá talvez poupar 1% se usar memória partilhada. </para> + +</sect2> + +<sect2 id="hard-numbers"> +<title +>Alguns Números em Bruto</title> + +<para +>Estes são retirados a partir da versão actual em desenvolvimento. Tentou-se obter também casos reais, porque isso não é o que as aplicações do dia-a-dia deverão usar. </para> + +<para +>Foi criada uma aplicação chamada 'som_sequencia' que transmite dados para o &arts;. Aqui está a correr com prioridade de tempo-real (sem problemas) e com um 'plugin' pequeno por parte do servidor (ajuste e recorte do volume): </para> + +<programlisting +>4974 stefan 20 0 2360 2360 1784 S 0 17.7 1.8 0:21 artsd +5016 stefan 20 0 2208 2208 1684 S 0 7.2 1.7 0:02 som_sequencia +5002 stefan 20 0 2208 2208 1684 S 0 6.8 1.7 0:07 som_sequencia +4997 stefan 20 0 2208 2208 1684 S 0 6.6 1.7 0:07 som_sequencia +</programlisting> + +<para +>Cada um deles está a transmitir com 3 fragmentos de 1024 bytes (18 ms). Existem três clientes do mesmo tipo a correr em simultâneo. É certo que isto parece demasiado, mas como foi dito: pegue num analisador ('profiler') e procure o que é que leva tempo e, se o desejar, tente melhorá-lo. </para> + +<para +>Contudo, não se deve pensar que a utilização da transmissão desta forma é realista ou faz sentido. Para levar isto ainda mais ao extremo, tentou-se a menor latência possível. Resultado: você poderá fazer transmissões sem interrupções com uma aplicação-cliente, se tiver 2 fragmentos de 128 bytes entre o &arts; e a placa de som e entre a aplicação-cliente e o &arts;. Isto significa que você tem uma latência total máxima de 128*4/44100*4 = 3 ms, onde 1,5 ms são gerados devido à E/S da placa de som e os outros 1,5 devem-se à comunicação com o &arts;. Ambas as aplicações precisam de correr em tempo-real. </para> + +<para +>Mas isto tem um custo enorme do <acronym +>CPU</acronym +>. Este exemplo custa-lhe cerca de 45% num P-II/350. Ele também começa a fazer 'clicks' se você iniciar o 'top', se mover as janelas no seu ecrã do X11 ou se fizer E/S de disco. Todas estas questões são respeitantes ao 'kernel'. O problema é que o escalonamento de duas ou mais aplicações em tempo-real custam-lhe uma quantidade enorme de esforço também, e ainda mais se elas comunicarem, notificarem-se uma à outra, &etc;. </para> + +<para +>Finalmente, um exemplo mais real. Isto é o &arts; com o &artsd; e um 'artscat' (um cliente de transmissão) que estão a correr 16 fragmentos de 4096 bytes: </para> + +<programlisting +>5548 stefan 12 0 2364 2364 1752 R 0 4.9 1.8 0:03 artsd +5554 stefan 3 0 752 752 572 R 0 0.7 0.5 0:00 top +5550 stefan 2 0 2280 2280 1696 S 0 0.5 1.7 0:00 artscat +</programlisting> + +</sect2> +</sect1> + +<!-- TODO + +<sect1 id="dynamic-instantiation"> +<title +>Dynamic Instantiation</title> + +</sect1> + +--> + +<sect1 id="busses"> +<title +>Barramentos</title> + +<para +>Os barramentos são ligações criadas dinamicamente que transferem o áudio. Basicamente, existem alguns canais de envio e de recepção e de envio. Todos os sinais dos canais de envio são adicionados e enviados para os canais de recepção. </para> + +<para +>Os barramentos, tal como são implementados actualmente, operam em estéreo, por isso você só poderá transferir dados em estéreo nos barramentos. Se você quiser dados mono, bem, transfira apenas por um canal e coloque o outro a zeros ou com outro valor qualquer. Tudo o que precisa de fazer é criar um ou mais objectos Synth_BUS_UPLINK e dar-lhes o nome de um barramento, com o qual eles deverão falar (⪚ <quote +>áudio</quote +> ou <quote +>bateria</quote +>). Basta largar os dados aí. </para> + +<para +>Aí, você terá de criar um ou mais objectos Synth_BUS_DOWNLINK, indicando-lhe o nome do barramento (<quote +>áudio</quote +> ou <quote +>bateria</quote +> ... se corresponde, os dados serão transferidos para aí), e os dados misturados irão sair de novo. </para> + +<para +>Os canais de envio e de recepção poderão residir em estruturas diferentes, e você até poderá ter vários &arts-builder;s diferentes a correr e iniciar um canal de envio num e receber os dados noutro, através do canal de recepção respectivo. </para> + +<para +>O que é interessante acerca dos barramentos é que eles são completamente dinâmicos. Os clientes poder-se-ão ligar instantaneamente. Não deverá haver nenhum 'click' ou ruído à medida que isto acontece. </para> + +<para +>Claro que você não deverá desligar um cliente que toca um sinal, dado que poderá não estar a um nível nulo quando for desligado do barramento, ao que se ouvirá então um 'click'. </para> +</sect1> + +<!-- TODO +<sect1 id="network-ransparency"> +<title +>Network Transparency</title> + +</sect1> + +<sect1 id="security"> +<title +>Security</title> + +</sect1> + + +<sect1 id="effects"> +<title +>Effects and Effect Stacks</title> + +</sect1> + +--> +<sect1 id="trader"> +<title +>Mediador</title> + +<para +>O &arts;/&MCOP; baseia-se em grande medida na divisão das coisas em pequenos componentes. Isto torna as coisas muito flexíveis, à medida que vai extendendo o sistema facilmente com a adição de componentes novos que implementam efeitos novos, formatos de ficheiros, osciladores, elementos gráficos.... Dado que quase tudo é um componente, quase tudo poderá ser extendido facilmente, sem alterar o código existente. Os componentes novos poderão ser simplesmente carregados dinamicamente para melhorar as aplicações já existentes. </para> + +<para +>Contudo, para isto funcionar, são necessárias duas coisas: </para> + +<itemizedlist> + +<listitem> +<para +>Os componentes têm de se publicitar a eles próprios - eles precisam de descrever quais as coisas que eles oferecem, para que as aplicações sejam capazes de as usar. </para> +</listitem> + +<listitem> +<para +>As aplicações precisam de procurar activamente os componentes que elas poderão usar, em vez de usar sempre a mesma coisa para uma dada tarefa. </para> +</listitem> + +</itemizedlist> + +<para +>A combinação disto - os componentes que dizem <quote +>aqui estou eu, sou bom, usem-me</quote +>, e as aplicações (ou, se preferir, outros componentes) que vão e procuram qual o componente que eles poderão usar para ter uma coisa feita - é o que é chamado de 'mediação' ou 'negociação'. </para> + +<para +>No &arts;, os componentes descrevem-se a si próprios, indicando valores que <quote +>suportam</quote +> para as propriedades.. Uma propriedade típica para um componente de leitura de ficheiros poderá ser a extensão dos ficheiros que pode processar. Os valores típicos poderão ser o <literal role="extension" +>wav</literal +>, o <literal role="extension" +>aiff</literal +> ou o <literal role="extension" +>mp3</literal +>. </para> + +<para +>De facto, todos os componentes poderão optar por oferecer vários valores diferentes para uma dada propriedade. Por isso, um único componente poder-se-á oferecer para ler tanto os ficheiros <literal role="extension" +>wav</literal +> como os <literal role="extension" +>aiff</literal +>, indicando que suporta estes valores para a propriedade <quote +>Extension</quote +> (Extensão). </para> + +<para +>Para o fazer, um componente terá de colocar um ficheiro <literal role="extension" +>.mcopclass</literal +> num local apropriado, contendo as propriedades que suporta; no caso do exemplo actual, isto poderá assemelhar-se ao seguinte (e estará instalado como <filename +><replaceable +>dir_componente</replaceable +>/Arts/WavPlayObject.mcopclass</filename +>): </para> + +<programlisting +>Interface=Arts::WavPlayObject,Arts::PlayObject,Arts::SynthModule,Arts::Object +Author="Stefan Westerfeld <stefan@space.twc.de>" +URL="http://www.arts-project.org" +Extension=wav,aiff +MimeType=audio/x-wav,audio/x-aiff +</programlisting> + +<para +>É importante que o nome do ficheiro <literal role="extension" +>.mcopclass</literal +> também diga como é que se chama a interface do componente. O mediador não olha para o conteúdo de todo, se o ficheiro (tal como está aqui) se chamar <filename +>Arts/WavPlayObject.mcopclass</filename +>, a interface do componente é chamada de <interfacename +>Arts::WavPlayObject</interfacename +> (os módulos mapeiam-se nas pastas). </para> + +<para +>Para ver os componentes, existem duas interfaces (que estão definidas em <filename +>core.idl</filename +>, por isso você irá tê-las em todas as aplicações), chamadas de <interfacename +>Arts::TraderQuery</interfacename +> e <interfacename +>Arts::TraderOffer</interfacename +>. Você poderá fazer uma <quote +>ida às compras</quote +> nos componentes deste tipo: </para> + +<orderedlist> +<listitem> +<para +>Crie um objecto de pesquisa: </para> +<programlisting +>Arts::TraderQuery pesquisa; +</programlisting> +</listitem> + +<listitem> +<para +>Indique o que pretende. Como viu em cima, os componentes descrevem-se a si próprios recorrendo a propriedades, para os quais eles oferecem determinados valores. Por isso, poderá indicar o que quiser através da selecção de componentes que suportem um dado valor para uma dada propriedade. Isto é feito se usar o método 'supports' de uma TraderQuery: </para> + +<programlisting +>pesquisa.supports("Interface","Arts::PlayObject"); + pesquisa.supports("Extension","wav"); +</programlisting> +</listitem> + +<listitem> +<para +>Finalmente, efectue a pesquisa usando o método 'query'. Aí, você irá obter (ou assim se espera) algumas ofertas: </para> + +<programlisting +>vector<Arts::TraderOffer> *ofertas = pesquisa.query(); +</programlisting> +</listitem> + +<listitem> +<para +>Agora você poderá examinar o que encontrou. O que é importante é o método 'interfaceName' do TraderOffer, o qual lhe dirá o nome do componente que correspondeu à pesquisa. Você poderá também encontrar mais propriedades com o método 'getProperty'. O código seguinte irá simplesmente iterar por todos os componentes, imprimir o nome das suas interfaces (que poderão ser usados na criação), e limpar os resultados da pesquisa de novo: </para> +<programlisting +>vector<Arts::TraderOffer>::iterator i; + for(i = ofertas->begin(); i != ofertas->end(); i++) + cout << i->interfaceName() << endl; + delete ofertas; +</programlisting> +</listitem> +</orderedlist> + +<para +>Para este tipo de serviço de mediação ser útil, é importante concordar de alguma forma nos tipos de propriedades que os componentes deverão definir normalmente. É essencial que mais ou menos todos os componentes de uma determinada área usem o mesmo conjunto de propriedades para se descreverem a si próprios (e o mesmo conjunto de valores, sempre que se aplicar), de modo a que as aplicações (ou as outras componentes) sejam capazes de os encontrar. </para> + +<para +>Author (tipo 'texto', opcional): Isto poderá ser usado para mostrar em última instância ao mundo que você fez algo. Aqui você poderá escrever tudo o que quiser, se bem que um endereço de e-mail é obviamente útil. </para> + +<para +>Buildable (tipo booleano, recomendado): Isto indica se o componente pode sre usado com ferramentas de <acronym +>RAD</acronym +> (como o &arts-builder;) que usam os componentes, atribuindo-lhes propriedades e ligando os seus portos. Recomenda-se ter este valor a 'true' (verdadeiro) para quase todos os componentes de processamento de sinal (como os filtros, efeitos, osciladores, ...) e para todas as outras coisas que podem usadas numa abordagem <acronym +>RAD</acronym +>, mas não para coisas internas como, por exemplo, o <interfacename +>Arts::InterfaceRepo</interfacename +>. </para> + +<para +>Extension (tipo texto, onde for relevante): Tudo o que lide com ficheiros deverá optar por usar isto. Você deverá colocar aqui a versão em minúsculas da extensão do ficheiro sem o <quote +>.</quote +>, como por exemplo <userinput +>wav</userinput +>. </para> + +<para +>Interface (tipo texto, obrigatório): Isto deverá incluir a lista completa de interfaces (úteis) que os seus componentes suportam, incluindo provavelmente o <interfacename +>Arts::Object</interfacename +> e, se se aplicar, o <interfacename +>Arts::SynthModule</interfacename +>. </para> + +<para +>Language (tipo texto, recomendado): Se você quiser que o seu componente seja carregado dinamicamente, você precisa de indicar aqui a linguagem. De momento, o único valor permitido é o <userinput +>C++</userinput +>, o que significa que o componente foi criado com a <acronym +>API</acronym +> normal de C++. Se o fizer, você também terá de definir a propriedade <quote +>Library</quote +> em baixo. </para> + +<para +>Library (tipo texto, usado quando relevante): Os componentes feitos em C++ podem ser carregados dinamicamente. Para o fazer, você terá de os compilar num módulo de biblioteca carregada dinamicamente (<literal role="extension" +>.la</literal +>). Aqui você poderá indicar o nome do ficheiro <literal role="extension" +>.la</literal +>. Lembre-se de usar o REGISTER_IMPLEMENTATION (como sempre). </para> + +<para +>MimeType (tipo texto, usado quando for relevante): Tudo o que lide com ficheiros deverá optar por usar isto. Você deverá colocar aqui a versão em minúsculas do tipo MIME normal, como por exemplo <userinput +>audio/x-wav</userinput +>. </para> + +<para +>&URL; (tipo texto, opcional): Se quiser que as pessoas saibam onde poderão obter uma nova versão do componente (ou uma página pessoal, ou algo do género), você podê-lo-á fazer aqui. Isto deverá ser um &URL; normal de &HTTP; ou de &FTP;. </para> + +</sect1> + +<!-- TODO +<sect1 id="midi-synthesis"> +<title +><acronym +>MIDI</acronym +> Synthesis</title> + +</sect1> + +<sect1 id="instruments"> +<title +>Instruments</title> + +</sect1> + +<sect1 id="session-management"> +<title +>Session Management</title> + +</sect1> + +<sect1 id="full-duplex"> +<title +>Full duplex Audio</title> + +</sect1> +--> + +<sect1 id="namespaces"> +<title +>Espaços de nomes no &arts;</title> + +<sect2 id="namespaces-intro"> +<title +>Introdução</title> + +<para +>Cada declaração de espaço de nomes corresponde à declaração de um <quote +>módulo</quote +> na &IDL; do &MCOP;. </para> + +<programlisting +>// idl de mcop + +module M { + interface A + { + } +}; + +interface B; +</programlisting> + +<para +>Neste caso, o código de C++ gerado para o excerto de &IDL; deverá ser algo semelhante a isto: </para> + +<programlisting +>// código de C++ + +namespace M { + /* declaração de A_base/A_skel/A_stub e itens semelhantes */ + class A { // Classe de interface de referência + /* [...] */ + }; +} + +/* declaração de B_base/B_skel/B_stub e itens semelhantes */ +class B { + /* [...] */ +}; +</programlisting> + +<para +>Por isso, quando se referir às classes do seu código em C++, você terá de escrever <classname +>M::A</classname +>, mas só B. Todavia, você poderá indicar <quote +>using M</quote +> algures - como em qualquer 'namespace' do C++. </para> + +</sect2> + +<sect2 id="namespaces-how"> +<title +>Como o &arts; usa os espaços de nomes</title> + +<para +>Existe um espaço de nomes global chamado <quote +>Arts</quote +>, o qual todos os programas e bibliotecas usam para colocar lá as suas declarações. Isto significa que, ao criar código em C++ que dependa do &arts;, você terá normalmente de anteceder cada classe que usar com o <classname +>Arts::</classname +>, tal como se segue: </para> + +<programlisting +>int main(int argc, char **argv) +{ + Arts::Dispatcher mediador; +" Arts::SimpleSoundServer servidor(Arts::Reference("global:Arts_SimpleSoundServer")); + + servidor.play("/var/xpto/um_ficheiro.wav"); +</programlisting> + +<para +>A outra alternativa é usar um 'using', tal como se segue: </para> + +<programlisting +>using namespace Arts; + +int main(int argc, char **argv) +{ + Dispatcher mediador; + SimpleSoundServer servidor(Reference("global:Arts_SimpleSoundServer")); + + servidor.play("/var/xpto/um_ficheiro.wav"); + [...] +</programlisting> + +<para +>Nos ficheiros &IDL;, você não tem de facto escolha alguma. Se estiver a fazer código que pertença ao &arts; em si, você terá de o pôr no módulo do &arts;. </para> + +<programlisting +>// Ficheiro IDL para código do aRts: +#include <artsflow.idl> +module Arts { // colocar no espaço de nomes Arts + interface Synth_AJUSTE : SynthModule + { + in audio stream entrada; + out audio stream saida; + attribute float factorAjuste; + }; +}; +</programlisting> + +<para +>Se você fizer código que não pertença ao &arts; em si, você não o deverá colocar no espaço de nomes <quote +>Arts</quote +>. Contudo, você poderá criar um espaço de nomes próprio se quiser. Em qualquer dos casos, você terá de anteceder as classes que usar do &arts;. </para> + +<programlisting +>// Ficheiro IDL para código que não pertence ao aRts: +#include <artsflow.idl> + +// pode criar sem declaração do módulo, onde as classes geradas não irão +// usar nenhum 'namespace' (espaço de nomes): +interface Synth_AJUSTE2 : Arts::SynthModule +{ + in audio stream entrada; + out audio stream saida; + attribute float factorAjuste; +}; + +// contudo, você também poderá escolher o seu espaço de nomes, se preferir, por +// isso se criar uma aplicação "Radio", você poderá fazê-lo da seguinte forma: +module Radio { + struct Estacao { + string nome; + float frequencia; + }; + + interface Sintonizador : Arts::SynthModule { + attribute Estacao estacao; // não é necessário anteceder o Estacao, por ser do mesmo módulo + out audio stream esquerda, direita; + }; +}; +</programlisting> + +</sect2> + +<sect2 id="namespaces-implementation"> +<title +>Detalhes Internos: Como Funciona a Implementação</title> + +<para +>Normalmente, nas interfaces, conversões ('casts'), assinaturas dos métodos e noutras situações semelhantes, o &MCOP; precisa de se referir aos nomes dos tipos ou das interfaces. Estes são representados como texto nas estruturas de dados comuns do &MCOP;, enquanto que o espaço de nomes é sempre representado por completo no estilo do C++. Isto significa que os textos iriam conter <quote +>M::A</quote +> e <quote +>B</quote +>, seguindo o exemplo acima. </para> + +<para +>Repare que isto se aplica mesmo se, dentro do texto do &IDL;, os qualificadores de espaços de nomes não foram indicados, dado que o contexto tornou claro qual a o espaço de nomes em que a interface <interfacename +>A</interfacename +> pretendia ser usada. </para> + +</sect2> +</sect1> + +<sect1 id="threads"> +<title +>Tarefas no &arts;</title> + +<sect2 id="threads-basics"> +<title +>Básicos</title> + +<para +>A utilização de tarefas ('threads') em todas as plataformas não é possível. Foi por isso que o &arts; originalmente foi feito sem qualquer suporte multitarefa. Para quase todos os problemas, para cada solução multitarefa para o problema, existe uma solução monotarefa que faz o mesmo. </para> + +<para +>Por exemplo, em vez de colocar a saída de áudio numa tarefa em separado, tornando-a bloqueante, o &arts; usa a saída de áudio não-bloqueante, e tenta descobrir quando deve escrever os próximos blocos de dados com o <function +>select()</function +>. </para> + +<para +>Contudo, o &arts; (em versões muito recentes) oferece pelo menos o suporte para as pessoas que queiram implementar os seus objectos com tarefas separadas. Por exemplo, se você já tiver código para um leitor de <literal role="extension" +>mp3</literal +> e o código do descodificador de <literal role="extension" +>mp3</literal +> está à espera de correr numa tarefa separada, é normalmente o acto mais fácil manter este desenho. </para> + +<para +>A implementação do &arts;/&MCOP; é desenhada tendo como ideia de base a partilha do estado entre os objectos separados, implementada de formas óbvias ou menos óbvias. Uma pequena lista do estado partilhado inclui: </para> + +<itemizedlist> +<listitem +><para +>O objecto Dispatcher (mediador) que faz a comunicação do &MCOP;. </para> +</listitem> + +<listitem> +<para +>A contagem de referências (interfaces inteligentes). </para> +</listitem> + +<listitem> +<para +>O IOManager (gestor de E/S) que vigia os temporizadores e descritores de ficheiros. </para> +</listitem> + +<listitem> +<para +>O ObjectManager (gestor de objectos), que cria os objectos e carrega automaticamente os 'plugins'. </para> +</listitem> + +<listitem> +<para +>O FlowSystem (sistema de fluxo) que invoca o 'calculateBlock' nas situações apropriadas. </para> +</listitem> +</itemizedlist> + +<para +>Todos os objectos acima não estão à espera de ser usados concorrentemente (&ie; chamados em tarefas separadas ao mesmo tempo). Normalmente, existem duas formas de resolver isto: </para> + +<itemizedlist> +<listitem> +<para +>Obrigar ao invocador de todas as funções nestes objectos a adquirir um bloqueio antes de as usar. </para> +</listitem> + +<listitem> +<para +>Tornar estes objectos realmente seguros em multitarefa e/ou criar instâncias por cada tarefa das mesmas. </para> +</listitem> +</itemizedlist> + +<para +>O &arts; segue a primeira aproximação: você terá de bloquear os objectos sempre que precisar de comunicar com qualquer um deles. A segunda aproximação é mais difícil de conseguir. Um truque que tenta obter isto está disponível em <ulink url="http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz" +> http://space.twc.de/~stefan/kde/download/arts-mt.tar.gz</ulink +>, mas nesta altura do campeonato, funcionará melhor uma aproximação minimalista, e causará menos problemas com as aplicações existentes. </para> + +</sect2> +<sect2 id="threads-locking"> +<title +>Quando/como efectuar o bloqueio?</title> + +<para +>Você poderá efectuar/libertar o bloqueio com as duas funções: </para> + +<itemizedlist> +<listitem> +<para> +<ulink +url="http://space.twc.de/~stefan/kde/arts-mcop-doc/arts-reference/headers/Arts__Dispatcher.html#lock" +><function +>Arts::Dispatcher::lock()</function +></ulink> +</para> +</listitem> +<listitem> +<para> +<ulink +url="http://space.twc.de/~stefan/kde/arts-mcop-doc/arts-reference/headers/Arts__Dispatcher.html#unlock" +><function +>Arts::Dispatcher::unlock()</function +></ulink> +</para> +</listitem> +</itemizedlist> + +<para +>Geralmente, você não terá de efectuar o bloqueio (e não deverá ter de tentar fazê-lo), se já foi efectuado anteriormente. Segue-se uma lista com as condições em que este é o caso: </para> + +<itemizedlist> +<listitem> +<para +>Você recebe uma chamada de resposta do IOManager (um temporizador ou um descritor). </para> +</listitem> + +<listitem> +<para +>Você é invocado devido a algum pedido do &MCOP;. </para> +</listitem> + +<listitem> +<para +>Você é chamado a partir do NotificationManager (gestor de notificações). </para> +</listitem> + +<listitem> +<para +>Você é invocado a partir do FlowSystem (pelo 'calculateBlock') </para> +</listitem> +</itemizedlist> + +<para +>Existem também algumas excepções de funções que você só poderá invocar na tarefa principal e que, por essa razão, nunca irá necessitar de bloquear para as chamar: </para> + +<itemizedlist> +<listitem> +<para +>O construtor/destrutor do Dispatcher/IOManager. </para> +</listitem> + +<listitem> +<para +><methodname +>Dispatcher::run()</methodname +> / <methodname +>IOManager::run()</methodname +> </para> +</listitem> + +<listitem> +<para +><methodname +>IOManager::processOneEvent()</methodname +></para> +</listitem> +</itemizedlist> + +<para +>Mas é tudo. Para tudo o resto que esteja relacionado de qualquer forma com o &arts;, você irá necessitar de obter o bloqueio e libertá-lo quando terminar - sempre. Aqui está um exemplo simples: </para> + +<programlisting +>class TarefaTempoSuspensao : Arts::Thread { +public: + void run() { + /* + * você precisa deste bloqueio porque: + * - a criação de uma referência necessita de um bloqueio (porque o + * 'global:' vai para o gestor de objectos, o qual poderá necessitar + * por seu turno do objecto GlobalComm para procurar onde se ligar) + * - a atribuição de uma interface inteligente necessita de um + * bloqueio + * - a construção de um objecto a partir de uma referência necessita * de um bloqueio (porque poderá necessitar de se ligar a um + * servidor) + */ + Arts::Dispatcher::lock(); + Arts::SoundServer servidor = Arts::Reference("global:Arts_SoundServer"); + Arts::Dispatcher::unlock(); + + for(;;) { /* + * você precisa de bloquear aqui, por que + * - libertar a referência a uma interface inteligente necessita + * de um bloqueio (porque poderá fazer uma criação tardia) + * - fazer uma invocação do MCOP necessita de efectuar um bloqueio + */ + Arts::Dispatcher::lock(); + long segundos = servidor.secondsUntilSuspend(); + Arts::Dispatcher::unlock(); + + printf("segundos até à suspensão = %d",segundos); + sleep(1); + } + } +} +</programlisting> + + +</sect2> + +<sect2 id="threads-classes"> +<title +>Classes relacionadas com tarefas</title> + +<para +>As seguintes classes relacionadas com tarefas estão disponíveis de momento: </para> + +<itemizedlist> +<listitem> +<para +>O <ulink url="http://www.arts-project.org/doc/headers/Arts__Thread.html" +><classname +> Arts::Thread</classname +></ulink +> - que encapsula uma tarefa. </para> +</listitem> + +<listitem> +<para +>O <ulink url="http://www.arts-project.org/doc/headers/Arts__Mutex.html" +> <classname +>Arts::Mutex</classname +></ulink +> - que encapsula um 'mutex' - uma exclusão mútua. </para> +</listitem> + +<listitem> +<para +>O <ulink url="http://www.arts-project.org/doc/headers/Arts__ThreadCondition.html" +> <classname +>Arts::ThreadCondition</classname +></ulink +> - que oferece o suporte para acordar as tarefas que estão à espera que uma dada condição se torne verdadeira. </para> +</listitem> + +<listitem> +<para +>O <ulink url="http://www.arts-project.org/doc/headers/Arts__SystemThreads.html" +><classname +>Arts::SystemThreads</classname +></ulink +> - que encapsula a camada do suporte multitarefa do sistema operativo (e que oferece algumas funções úteis para os programadores das aplicações). </para> +</listitem> +</itemizedlist> + +<para +>Veja os 'links' para obter mais documentação. </para> + +</sect2> +</sect1> + +<sect1 id="references-errors"> +<title +>Referências e Tratamento de Erros</title> + +<para +>As referências no &MCOP; são um dos conceitos mais centrais na programação com o &MCOP;. Esta secção irá tentar descrever como é que as referências são usadas ao certo, e irá também tentar especialmente cobrir os casos de falha ). </para> + +<sect2 id="references-properties"> +<title +>Propriedades básicas das referências</title> + +<itemizedlist> +<listitem> +<para +>Uma referência de &MCOP; não é um objecto, mas sim a referência a um objecto: Ainda que a seguinte declaração <programlisting> + Arts::Synth_PLAY p; +</programlisting +> se pareça com a definição de um objecto, apenas declara a referência a um objecto. Como programador de C++, você poderá pensar nisto como um Synth_PLAY *, um tipo de ponteiro para um objecto Synth_PLAY. Isto significa especialmente que o 'p' poderá ser a mesma coisas que um ponteiro nulo (NULL). </para> +</listitem> + +<listitem> +<para +>Você poderá criar uma referência a NULL (valor nulo), atribuindo este valor explicitamente </para> +<programlisting +>Arts::Synth_PLAY p = Arts::Synth_PLAY::null(); +</programlisting> +</listitem> + +<listitem> +<para +>Invocar objectos numa referência NULL irá conduzir a um estoiro </para> +<programlisting +>Arts::Synth_PLAY p = Arts::Synth_PLAY::null(); + string s = p.toString(); +</programlisting> +<para +>irá levar a um estoiro. Se comparar isto com um ponteiro, é exactamente o mesmo que <programlisting> + QWindow* janela = 0; + janela->show(); +</programlisting +>, o qual todos os programadores de C++ sabem que deverão evitar. </para> +</listitem> + +<listitem> +<para +>Os objectos não-inicializados tentar-se-ão criar 'a posteriori' quando forem usados pela primeira vez </para> + +<programlisting +>Arts::Synth_PLAY p; + string s = p.toString(); +</programlisting> +<para +>é algo diferente de fazer uma referência a um ponteiro NULL. Você não indicou ao objecto de todo o que ele é, e agora irá tentar usá-lo. A questão aqui é que você deseja ter uma instância local de um objecto Arts::Synth_PLAY. Claro que você poderá querer ter algo diferente (como criar o objecto noutro local qualquer, ou usar um objecto remoto existente). Contudo, é um atalho conveniente para criar objectos. A criação tardia não irá funcionar logo que tenha atribuído outra coisa qualquer (como por exemplo uma referência nula). </para> + +<para +>Os termos equivalentes em C++ seriam <programlisting> + QWidget* janela; + janela->show(); +</programlisting +> o que obviamente, em C++, iria dar um estoiro garantido. Por isso, isto é diferente aqui. Esta criação tardia é enganadora, porque não quer dizer que exista necessariamente uma implementação para a sua interface. </para> + +<para +>Por exemplo, considere uma coisa abstracta como um Arts::PlayObject. Existem decerto PlayObjects concretos como os que existem para tocar MP3s ou WAVs, mas o <programlisting> + Arts::PlayObject objecto; + objecto.play(); +</programlisting +> irá falhar de certeza. O problema é que, ainda que a criação tardia funcione e tente criar um PlayObject, irá falhar, dado que existem coisas do tipo Arts::WavPlayObject e outros do género. Daí, use a criação tardia apenas se tiver a certeza que existe uma implementação. </para> +</listitem> + +<listitem> +<para +>As referência podem apontar para o mesmo objecto </para> + +<programlisting +>Arts::SimpleSoundServer s = Arts::Reference("global:Arts_SimpleSoundServer"); + Arts::SimpleSoundServer s2 = s; +</programlisting> + +<para +>cria duas referências para o mesmo objecto. Isto não copia nenhum valor e não cria dois objectos. </para> +</listitem> + +<listitem> +<para +>Todos objectos fazem contagem das referências. Por isso, logo que um objecto já não seja mais referenciado por nenhum outro objecto, é removido. Não existe nenhuma forma explícita de remover um objecto, contudo poderá usar algo do género <programlisting> + Arts::Synth_PLAY p; + p.start(); + [...] + p = Arts::Synth_PLAY::null(); +</programlisting +> para fazer com que o objecto Synth_PLAY se vá embora no fim. Especialmente não deverá ser necessário usar o 'new' e o 'delete' em conjunto com as referências. </para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="references-failure"> +<title +>O caso de falha</title> + +<para +>Dado que as referências poderão apontar para objectos remotos, os servidores que contenham esses objectos poderão estoirar. O que acontece então? </para> + +<itemizedlist> + +<listitem> +<para +>Um estoiro não muda se uma referência é nula. Isto significa que, se o <function +>xpto.isNull()</function +> foi <returnvalue +>true</returnvalue +> antes de um estoiro do servidor, então também será <returnvalue +>true</returnvalue +> depois do estoiro (o que parece claro). Significa também que, se o <function +>xpto.isNull()</function +> foi <returnvalue +>false</returnvalue +> antes de um estoiro do servidor (o 'xpto' fazia referência a um objecto), então também será <returnvalue +>false</returnvalue +> depois do estoiro do servidor. </para> +</listitem> + +<listitem> +<para +>A invocação dos métodos numa referência válida mantém-se segura. Suponha que o servidor que contém o objecto 'calc' estoirou. Se continuar a invocar coisas do tipo <programlisting> + int k = calc.subtrair(i,j) +</programlisting +> estas serão seguras. Obviamente, o 'subtrair' terá de devolver algo aqui, o que não consegue porque o objecto remoto já não existe mais. Nesse caso, o (k == 0) será verdadeiro. Geralmente, as operações tentam devolver algo <quote +>neutro</quote +> como resultado, como por exemplo 0,0, uma referência nula para os objectos ou textos em branco, sempre que o objecto não existir mais. </para> +</listitem> + +<listitem> +<para +>Se invocar o <function +>error()</function +> verá se algo correu bem ou mal. </para> + +<para +>No caso de cima, o <programlisting> + int k = calc.subtrair(i,j) + if(k.error()) { + printf("O k não é igual a i-j!\n"); + } +</programlisting +> iria imprimir <computeroutput +>O k não é igual a i-j</computeroutput +> sempre que a invocação remota não funcionasse. Caso contrário, o <varname +>k</varname +> é de facto o resultado da operação 'subtrair' efectuada pelo objecto remoto (sem estoiro do servidor). Contudo, para os métodos que fazem coisas como remover ficheiros, você não poderá saber de certeza se isso de facto aconteceu. Claro que aconteceu se o <function +>.error()</function +> devolveu <returnvalue +>false</returnvalue +>. Contudo, se o <function +>.error()</function +> devolveu <returnvalue +>true</returnvalue +>, existem duas possibilidades: </para> + +<itemizedlist> +<listitem> +<para +>O ficheiro foi removido, e o servidor estoirou logo depois de o remover, mas antes de transferir o resultado. </para> +</listitem> + +<listitem> +<para +>O servidor estoirou antes de ser capaz de remover o ficheiro. </para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para +>O uso de invocações aninhadas é perigoso em programas resistentes a estoiros </para> + +<para +>Se usar algo do tipo <programlisting> + janela.titlebar().setTitle("xpto"); +</programlisting +> não é uma boa ideia. Suponha que você sabia que essa janela era uma referência de Window válida. Agora suponha que sabe que o <function +>janela.titlebar()</function +> iria devolver uma referência a Titlebar porque o objecto Window foi criado correctamente. Todavia, ainda a frase acima não é segura. </para> + +<para +>O que poderia acontecer é que o servidor que continha o objecto Window tinha estoirado. Aí, independentemente de quão válida fosse a implementação de Window, você iria obter uma referência nula como resultado da operação 'janela.titlebar()'. E aí, obviamente, a invocação de 'setTitle' nessa referência nula iria provocar um estoiro à mesma. </para> + +<para +>Por isso, uma variante segura disto seria <programlisting> + Titlebar titulo = janela.titlebar(); + if(!janela.error()) + titulo.setTitle("xpto"); +</programlisting +>, adicionando o tratamento de erros apropriado, se o desejar. Se você não confiar na implementação de Window, você poderá também usar <programlisting> + Titlebar titulo = janela.titlebar(); + if(!titulo.isNull()) + titulo.setTitle("xpto"); +</programlisting +> em que ambas são seguras. </para> +</listitem> +</itemizedlist> + +<para +>Existem outras condições de falha, como a quebra de rede (suponha que você retira o cabo entre o seu servidor e o cliente enquanto a sua aplicação corre). Contudo, o efeito é o mesmo que um estoiro do servidor. </para> + +<para +>De um modo geral, é claro uma questão de política a forma como você tenta eliminar os erros de comunicação na sua aplicação. Você poderá seguir o método de <quote +>se o servidor estoirar, é necessário depurar o servidor até que nunca mais estoire de novo</quote +>, o que significaria que você não se precisa de se incomodar com todos esses problemas. </para> + +</sect2> + +<sect2 id="references-internals"> +<title +>Detalhes Internos: Contagem de Referências Distribuída</title> + +<para +>Um objecto, para existir, precisa de pertencer a alguém. Se não pertencer, deixará de existir (mais ou menos) imediatamente. Internamente, a pertença é indicada ao chamar o <function +>_copy()</function +>, o qual incrementa uma contagem de referências e é devolvida ao invocar o <function +>_release()</function +>. Logo que a contagem de referências chegue a zero, será feito um 'delete'. </para> + +<para +>Como variação do tema, a utilização remota é indicada pelo <function +>_useRemote()</function +> e desfeita pelo <function +>_releaseRemote()</function +>. Estas funções mantêm uma lista dos servidores que invocaram o objecto (e que, por esse motivo, o possuem). Isto é usado no caso deste servidor se desligar (&ie; estoiro, falha de rede), para remover as referência que ainda existem nos objectos. Isto é feito com o <function +>_disconnectRemote()</function +>. </para> + +<para +>Agora existe um problema. Considere um valor devolvido. Normalmente, o objecto do valor devolvido não pertencerá mais à função que foi chamada. Também não pertencerá à função que chamou, até que a mensagem que mantém o objecto seja recebida. Deste modo, existe um tempo para os objectos <quote +>sem dono</quote +>. </para> + +<para +>Agora, ao enviar um objecto, poder-se-á assumir que, assim que seja recebido, passará a ter um dono de novo, a menos que, mais uma vez, o receptor morra. Contudo, isto significa que é preciso ter um cuidado especial com os objectos, pelo menos ao enviá-los e provavelmente ao recebê-los, de modo a que não morra de uma vez. </para> + +<para +>A forma como o &MCOP; faz isto é <quote +>marcando</quote +> os objectos que estão em vias de ser copiados para a rede. Antes de se dar início a uma cópia, o <function +>_copyRemote</function +> é invocado. Isto evita que o objecto seja libertado durante algum tempo (5 segundos). Logo que o receptor invoque o <function +>_useRemote()</function +>, a marca é removida de novo. Deste modo, todos os objectos que são enviado para a rede são marcados antes da transferência. </para> + +<para +>Se o receptor obtiver um objecto que está no seu servidor, é óbvio que ele não irá invocar o <function +>_useRemote()</function +>. Para esse caso especial, o <function +>_cancelCopyRemote()</function +> existe para remover a marca manualmente. Para além disso, existe também a remoção de marcas temporizada, se tiver sido feita a marcação mas o destinatário não recebeu de facto o objecto (devido a um estoiro ou falha de rede). Isto é feito com a classe <classname +>ReferenceClean</classname +>. </para> + +</sect2> + +</sect1> + +<sect1 id="detail-gui-elements"> +<title +>Elementos &GUI;</title> + +<para +>Os elementos &GUI; estão neste momento num estado experimental. Contudo, esta secção irá descrever o que é suposto acontecer aqui por isso, se você for um programador, você será capaz de perceber como é que o &arts; irá lidar com as &GUI;s no futuro. Existe já algum código, também. </para> + +<para +>Os elementos &GUI; deverão ser usados para permitir às estruturas de síntese interagirem com o utilizador. No caso mais simples, o utilizador deverá ser capaz de modificar alguns parâmetros de uma estrutura directamente (como um factor de ganho que é usado antes do módulo final de reprodução). </para> + +<para +>Nas opções mais complexas, pode-se imaginar que o utilizador deseja modificar os parâmetros de grupos de estruturas e/ou ainda não tem as estruturas a correr, como a modificação do envelope <acronym +>ADSR</acronym +> do instrumento &MIDI; activo no momento. Outra coisa seria mudar o nome do ficheiro de um instrumento baseado em amostras. </para +> + +<para +>Por outro lado, o utilizador poderá querer monitorizar o que o sintetizador está a fazer. Poderão existir osciloscópios, analisadores de espectro, medidores de volume e outras <quote +>experiências</quote +> que mostram a curva de transferência na frequência de um dado módulo de filtragem. </para> + +<para +>Finalmente, os elementos &GUI; deverão ser capazes de controlar a estrutura completa de o que é que está a correr dentro do &arts; e como. O utilizador deverá ser capaz de associar instrumentos a canais &MIDI;, iniciar novos processadores de efeitos, configurar a sua mesa de mistura principal (a qual é ela própria baseada em estruturas do &arts;) para ter mais um canal e usar outra estratégia para os seus equalizadores. </para> + +<para +>Você pode ver - os elementos <acronym +>GUI</acronym +> deverão trazer todas as possibilidades do estúdio virtual que o &arts; deverá simular para o utilizador. Claro, eles deverão interagir de forma ordeira com as entradas &MIDI; (assim como as barras se deverão mexer se elas tiverem entradas &MIDI; que mudem também esse parâmetro), e provavelmente até elas próprias gerarem eventos, para permitir a interacção com o utilizador ser registada com o sequenciador. </para> + +<para +>Tecnicamente, a ideia é ter uma classe de base de &IDL; para todos os elementos (a <classname +>Arts::Widget</classname +>), e derivar um conjunto de elementos comuns desta (como o <classname +>Arts::Poti</classname +>, o <classname +>Arts::Panel</classname +>, o <classname +>Arts::Window</classname +>, ...). </para> + +<para +>Aí, poder-se-á implementar estes elementos com uma biblioteca, como por exemplo o &Qt; ou o Gtk. Finalmente, os efeitos deverão criar as suas &GUI;s a partir dos elementos existentes. Por exemplo, um ' poderia criar a sua interface a partir de cinco objectos <classname +>Arts::Poti</classname +> e de uma <classname +>Arts::Window</classname +>. Por isso, SE existir uma implementação do &Qt; para esses elementos de base, o efeito deverá ser capaz de se apresentar, usando o &Qt;. Se existir uma implementação para Gtk, então deverá também funcionar para o Gtk (e assemelhar-se/funcionar mais ou menos da mesma forma). </para> + +<para +>Finalmente, dado que tem sido utilizada aqui a &IDL;, o &arts-builder; (ou outras ferramentas), serão capazes de ligar as interfaces visualmente, ou gerar automaticamente as interfaces com base nos parâmetros definidos, baseando-se apenas nas interfaces. Deverá ser relativamente simples criar uma classe para <quote +>criar uma &GUI; a partir da descrição</quote +>, que obtém uma descrição da &GUI; (contendo os vários parâmetros e elementos) e criar um objecto gráfico vivo a partir dele. </para> + +<para +>Baseando-se na &IDL; e no modelo de componentes do &arts;/&MCOP;, deverá ser simples extender os objectos possíveis que podem ser usados na &GUI; de forma tão simples como para adicionar um 'plugin' que implementa um novo filtro para o &arts;. </para> + +</sect1> + +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/digitalaudio.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/digitalaudio.docbook new file mode 100644 index 00000000000..d0fe3eb41c6 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/digitalaudio.docbook @@ -0,0 +1,16 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE appendix PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<appendix id="intro-digital-audio"> +<title +>Introdução ao Áudio Digital</title> + +<para +>amostragem digital, filtros, efeitos, &etc;</para> + +</appendix> + + + diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/faq.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/faq.docbook new file mode 100644 index 00000000000..b7a43cf8e04 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/faq.docbook @@ -0,0 +1,1312 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> +<chapter id="faq"> +<title +>Perguntas e respostas</title> + +<para +>Esta secção responde a algumas questões perguntadas frequentemente sobre o &arts;. </para> + +<qandaset id="faq-general"> +<title +>Perguntas Gerais</title> + +<qandaentry> +<question> +<para +>Será que o &kde; suporta a minha placa de som para a saída de áudio? </para> +</question> + +<answer> +<para +>O &kde; usa o &arts; para tocar som, e o &arts; usa os controladores do 'kernel' do &Linux;, sejam o <acronym +>OSS</acronym +> ou o <acronym +>ALSA</acronym +> (usando a emulação do <acronym +>OSS</acronym +>). Se a sua placa de som é suportada ou pelo <acronym +>ALSA</acronym +> ou pelo <acronym +>OSS</acronym +> e se estiver configurada convenientemente (&ie; qualquer outra aplicação do &Linux; consegue dar som), irá funcionar aqui também. Existem contudo alguns problemas com algum 'hardware' específico; por favor leia a <link linkend="faq-hardware-specific" +>secção sobre os problemas específicos do 'hardware'</link +> se estiver a ter problemas com o 'artsd' na sua máquina. </para> +<para +>Entretanto, também foi adicionado o suporte para outras plataformas. Aqui está uma lista completa de como a versão mais recente do &arts; poderá tocar som. Se você tiver uma plataforma que não está suportada, por favor pense e alterar o &arts; e migrá-lo para a sua plataforma. </para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry +>método de E/S de áudio do &arts;</entry> +<entry +>Comentário</entry> +</row> +</thead> + +<tbody> +<row> +<entry +>paud</entry> +<entry +>Suporte para o Dispositivo de Áudio Pessoal do AIX</entry> +</row> + +<row> +<entry +>alsa</entry> +<entry +>Controladores ALSA-0.5 e ALSA-0.9 do Linux</entry> +</row> + +<row> +<entry +>libaudioio</entry> +<entry +>O suporte para a biblioteca genérica LibAudioIO que funciona no Solaris</entry> +</row> + +<row> +<entry +>nas</entry> +<entry +>O servidor de som NAS, útil nos terminais X que têm suporte de NAS</entry> +</row> + +<row> +<entry +>null</entry> +<entry +>Dispositivo de áudio nulo; elimina o som silenciosamente</entry> +</row> + +<row> +<entry +>oss</entry> +<entry +>O suporte do OSS (Open Sound System) (funciona no Linux, em vários BSDs e outras plataformas com controladores OSS instalados).</entry> +</row> + +<row> +<entry +>toss</entry> +<entry +>Suporte multitarefa do OSS, o qual funciona melhor em certos casos onde o suporte normal do OSS não funciona bem</entry> +</row> + +<row> +<entry +>sgi</entry> +<entry +>O suporte do SGI Direct Media para o IRIX</entry> +</row> + +<row> +<entry +>sun</entry> +<entry +>O suporte para o Solaris</entry> +</row> + +</tbody> +</tgroup> +</informaltable> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Não consigo tocar ficheiros <literal role="extension" +>wav</literal +> com o &artsd;! </para> +</question> + +<answer> +<para +>Verifique se o &artsd; está compilado com a <filename +>libaudiofile</filename +> (faça <userinput +><command +>ldd</command +> <parameter +>artsd</parameter +></userinput +>). Se não estiver, obtenha o 'tdesupport', recompile tudo e irá funcionar. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Consigo ouvir som quando me ligo como <systemitem class="username" +>root</systemitem +>, mas os outros utilizadores não têm som! </para> +</question> + +<answer> +<para +>As permissões do ficheiro <filename class="devicefile" +>/dev/dsp</filename +> afectam os utilizadores que terão som. Para permitir que toda a gente o utilize, faça isto: </para> + +<procedure> +<step> +<para +>Ligue-se como <systemitem class="username" +>root</systemitem +>. </para> +</step> + +<step> +<para +>Abra uma janela do &konqueror;. </para> +</step> + +<step> +<para +>Vá para a pasta <filename class="directory" +>/dev</filename +>. </para> +</step> + +<step> +<para +>Carregue no ficheiro <filename +>dsp</filename +> com o botão <mousebutton +>direito</mousebutton +> do rato, escolhendo de seguida as Propriedades. </para> +</step> + +<step> +<para +>Carregue na página <guilabel +>Permissões</guilabel +>. </para> +</step> + +<step> +<para +>Assinale as opções <guilabel +>Ler</guilabel +> e <guilabel +>Escrever</guilabel +> em todas as secções. </para> +</step> + +<step> +<para +>Carregue em <guibutton +>OK</guibutton +>. </para> +</step> +</procedure> + +<para +>Você poderá obter o mesmo efeito numa janela de terminal com o comando <userinput +><command +>chmod</command +> <option +>666</option +> <parameter +>/dev/dsp</parameter +></userinput +>. </para> + +<para +>Para restringir o acesso ao som para apenas alguns utilizadores, você poderá usar as permissões do grupo. Em algumas distribuições de &Linux;, como por exemplo a Debian/Potato, o <filename class="devicefile" +>/dev/dsp</filename +> já pertence a um grupo chamado <systemitem class="groupname" +>audio</systemitem +>, por isso, tudo o que terá de fazer é adicionar os utilizadores a esse grupo. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Isto ajuda para o &artsd;, mas e então o &kmix;, o &kmid;, o &kscd;,&etc;? </para> +</question> +<answer> + +<para +>Existem vários outros dispositivos que oferecem funcionalidades acedidas pelas aplicações multimédia. Você poderá tratá-las da mesma forma, quer estando acessíveis para todos, quer usando grupos para controlar o acesso. Aqui está uma lista, a qual poderá estar à mesma incompleta (também se existirem vários dispositivos num formato do tipo <filename class="devicefile" +>midi0</filename +>, <filename class="devicefile" +>midi1</filename +>, ..., então só a versão 0 está aqui indicada): </para> + +<itemizedlist> +<listitem> +<para> +<filename class="devicefile" +>/dev/admmidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/adsp0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/amidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/amixer0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/audio</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/audio0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/cdrom</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/dmfm0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/dmmidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/dsp</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/dsp0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/midi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/midi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/midi00</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/midi00</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/mixer</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/mixer0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/mpu401data</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/mpu401stat</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/music</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/rmidi0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/rtc</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/sequencer</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/smpte0</filename> +</para> +</listitem> +<listitem> +<para> +<filename class="devicefile" +>/dev/sndstat</filename> +</para> +</listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>O que é que eu faço se o 'artsd' não arrancar ou estoirar na sua execução?</para> +</question> + +<answer> +<para +>Primeiro que tudo: tente usar as opções por omissão do &kcontrol; (ou se você estiver a iniciá-lo manualmente, não passe mais nenhumas opções adicionais para além de, provavelmente, a <userinput +><option +>-F</option +><parameter +>10</parameter +> <option +>-S</option +><parameter +>4096</parameter +></userinput +> por causa da latência). Especialmente o <emphasis +>'full duplex' é provável que estoire</emphasis +> com vários controladores, por isso tente desactivá-lo. </para> + +<para +>Uma boa forma de perceber porque é que o &artsd; não arranca (ou se estoira em plena execução) é arrancá-lo manualmente. Abra uma janela do &konsole; e faça: </para> + +<screen width="40" +><prompt +>%</prompt +> <userinput +><command +>artsd</command +> <option +>-F</option +><parameter +>10</parameter +> <option +>-S</option +><parameter +>4096</parameter +></userinput +></screen> + +<para +>Você poderá também adicionar a opção <option +>-l0</option +>, a qual irá imprimir mais informações sobre o que se está a passar, como por exemplo: </para> +<screen width="40" +><prompt +>%</prompt +> <userinput +><command +>artsd</command +> <option +>-l0</option +> <option +>-F</option +><parameter +>10</parameter +> <option +>-S</option +><parameter +>4096</parameter +></userinput +></screen> + +<para +>Ao fazê-lo, você irá obter algumas informações úteis sobre o facto de não ter iniciado. Ou, se ele estoirar a fazer isto-ou-aquilo, você poderá fazer tal-e-tal, vendo depois <quote +>como</quote +> é que ele estoira. Se você quiser comunicar um erro, produza um traceamento ('backtrace') com o <command +>gdb</command +> e/ou <command +>strace</command +> para ajudar a encontrar o problema. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>É possível posicionar de novo o &artsd; (mover os ficheiros compilados para outra pasta)?</para> +</question> + +<answer> +<para +>Você não poderá posicionar de novo perfeitamente o &arts;. O problema é que o &artswrapper; tem a localização do &artsd; compilada por motivos de segurança. Você poderá, no entanto, usar o ficheiro <filename +>.mcoprc</filename +> (itens TraderPath/ExtensionPath) para fazer com que o &artsd; posicionado de novo encontre os seus componentes. Veja o <link linkend="the-mcoprc-file" +>capítulo sobre o ficheiro <filename +>.mcoprc</filename +></link +> para saber mais detalhes sobre como fazer isto. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Como é que posso compilar o &arts; com o gcc-3.0?</para> +</question> + +<answer> +<para +>Resposta curta: não, o &arts; não irá funcionar se você compilar com o gcc-3.0. </para> + +<para +>Resposta longa: Na versão oficial existem dois erros do gcc-3.0 que afectam o &arts;. O primeiro, que é o c++/2733 do gcc-3.0 é relativamente inofensivo (e tem a ver com problemas na instrução 'asm'). Ele quebra a compilação do 'convert.cc'. Foi corrigido na versão de CVS do gcc-3.0, e não será mais um problema no gcc-3.0.1 e superiores. Foi também adicionado uma solução de recurso à versão de CVS do KDE/aRts. </para> +<para +>O segundo erro do gcc-3.0, o c++/3145 (que consiste na geração de código errado no caso de herança múltipla virtual) é crítico. As aplicações como o &artsd; irão simplesmente estoirar no arranque quando forem compiladas com o gcc-3.0. Mesmo que tenha sido feito algo na versão do gcc-3.0 na altura em que isto foi escrito, o &artsd; continua ainda a estoirar com frequência e imprevisivelmente. </para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para +>Que aplicações correm usando o &arts;?</para> +</question> +<answer> + +<para +>Obviamente, todas as aplicações que vêm incluídas no &kde; sabem do &arts;. Isto inclui: </para> + +<itemizedlist> +<listitem +><para +>&noatun;</para +></listitem> +<listitem +><para +>&arts-builder;</para +></listitem> +<listitem +><para +>&aktion;</para +></listitem> +<listitem +><para +>&kmid;</para +></listitem> +<listitem +><para +>&kmidi;</para +></listitem> +<listitem +><para +>&kmix;</para +></listitem> +<listitem +><para +>&kscd;</para +></listitem> +<listitem +><para +>Os jogos do &kde;, como o &kpoker; e o &ktuberling;</para +></listitem> +</itemizedlist> + +<para +>Algumas aplicações do &kde; que não estão ainda incluídas na distribuição do &kde; (⪚, no 'kdenonbeta') também suportam o &arts;, incluindo: </para> + +<itemizedlist> +<listitem +><para +>&brahms;</para +></listitem> +<listitem +><para +><application +>Kaboodle</application +></para +></listitem> +<listitem +><para +><application +>Kdao</application +></para +></listitem> +</itemizedlist> + +<para +>As seguintes aplicações não-&kde; também são conhecidas por funcionar com o &arts;: </para> + +<itemizedlist> +<listitem +><para +><application +>xmms</application +> (com o 'plugin' do &arts;)</para +></listitem> +<listitem +><para +><application +>RealPlayer</application +> 8.0 da Real Networks (funciona com o &artsdsp;; o suporte nativo do &arts; está a ser considerado)</para +></listitem> +</itemizedlist> + +<para +>Sabe-se que as seguintes aplicações <emphasis +>não</emphasis +> funcionam com o &arts;: </para> + +<itemizedlist> +<listitem +><para +>nenhuma</para +></listitem> +</itemizedlist> + +<para +>Veja também as respostas às perguntas na secção sobre <link linkend="faq-non-arts" +>as aplicações não-&arts;</link +>. </para> + +<para +>Esta secção está incompleta -- se você tiver mais informações sobre as aplicações suportadas e não suportadas, por favor envie as suas referências para o autor, para que possam ser incluídas aqui. </para> +</answer> +</qandaentry> + +</qandaset> + +<qandaset id="faq-non-arts"> +<title +>Aplicações não-&arts;</title> + +<qandaentry> +<question> +<para +>Assim que o &kde; começa a correr, mais nenhuma aplicação consegue aceder ao meu dispositivo de som! </para> +</question> +<answer> +<para +>Desde que o servidor de som &arts; que é usado pelo &kde; começa a correr, irá começar a usar o dispositivo de som. Se o servidor estiver inactivo durante 60 segundos, ele suspender-se-á e libertar o dispositivo automaticamente. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Você diz que ele se suspende ao fim de 60 segundos, mas não o faz para mim! </para> +</question> +<answer> +<para +>Se você iniciar o 'artsd' a partir do painel de controlo do KDE, a situação por omissão é ele suspender-se ao fim de 60 segundos. Se você iniciar o 'artsd' a partir da linha de comandos, você precisa de usar a opção '-s' para indicar o tempo de suspensão automática, caso contrário ele irá desactivar a função de suspensão automática. </para> +<para +>De momento, ele não se suspende se você estiver a usar o 'full-duplex'. Desactive-o no &kcontrol; e ele suspender-se-á. A desactivação do 'full-duplex' é normalmente uma boa ideia se você só usar o &arts; para tocar áudio e não para gravar. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Como é que posso correr as aplicações antigas e que não conhecem o &arts;? </para> +</question> + +<answer> +<para +>Corra-as, utilizando o &artsdsp;. Por exemplo, se você normalmente iria executar: </para> + +<screen +><prompt +>%</prompt +> <userinput +><command +>mpg123</command +> <option +>xpto.mp3</option +></userinput +></screen> + +<para +>use em alternativa:</para> + +<screen +><prompt +>%</prompt +> <userinput +><command +>artsdsp</command +> <option +>mpg123 xpto.mp3</option +></userinput +></screen> + +<para +>Isto irá redireccionar a saída de som para o &arts;. Este método não obriga a alterações nas aplicações. É uma espécie de 'truque sujo' e ainda não suporta por completo todas as funcionalidades do dispositivo da placa de som, como tal algumas aplicações não funcionam. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Não consigo executar o &artsdsp; com nenhuma aplicação; ela estoira sempre! </para> +</question> +<answer> +<para +>Você precisa de uma versão recente da biblioteca 'glibc'; o &artsdsp; não irá funcionar convenientemente em algumas distribuições mais antigas do &Linux;. Por exemplo no Debian 2.1 (que é baseado na 'glibc' 2.0) não funciona, enquanto que no Debian 2.2 (que se baseia na 'glibc' 2.1.3), funciona. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Existem limitações teóricas com algumas aplicações que farão com que elas não corram de todo com o &artsdsp;? </para> +</question> +<answer> +<para +>Não. A utilização do &artsdsp; poderá dar origem a uma maior latência e utilização do <acronym +>CPU</acronym +> do que usando directamente as <acronym +>API</acronym +>s do &arts;. Para além disso, qualquer aplicação que não funcione deverá ser considerada como manifestando algum erro no &artsdsp;. A técnica usada pelo &artsdsp; deverá, se for implementada correctamente, permitir a <emphasis +>todas</emphasis +> as aplicações correrem com ela (incluindo aplicações grandes como o <application +>Quake</application +> 3). </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>O que é que posso fazer se uma aplicação não funcionar com o &artsdsp;? </para> +</question> +<answer> +<para +>Você poderá esperar que o &artsd; se suspenda ou utilizar o comando <userinput +><command +>artsshell</command +> <option +>suspend</option +></userinput +> para pedir ao servidor para se suspender ele próprio. Você só poderá suspender o servidor se nenhuma das aplicações do &arts; esteja de momento a usá-lo; da mesma forma, nenhuma das aplicações do &arts; será capaz de correr quando o servidor estiver suspenso. </para> + +<para +>Se o servidor estiver ocupado, uma maneira crua mas efectiva de se ver livre dele é: </para> + + +<screen +><prompt +>%</prompt +> <userinput +><command +>killall</command +> <option +>artsd</option +> ; <command +>killall</command +> <option +>artswrapper</option +></userinput> +<lineannotation +>Agora inicie a sua própria aplicação.</lineannotation> +<prompt +>%</prompt +> <userinput +><command +>kcminit</command +> <option +>arts</option +></userinput +> +</screen> + +<para +>Qualquer uma das aplicações do &arts; em execução poderá estoirar, todavia, se você matar o servidor. </para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para +>Então e as aplicações feitas para o &kde; 1.x? </para> +</question> +<answer> +<para +>Se você estiver a correr aplicações do &kde; 1.x, cuja saída de som é feita através do servidor de som do &kde; 1, você terá de correr o <application +>kaudioserver</application +> para que ele funcione. Você poderá iniciar o <application +>kaudioserver</application +> da mesma forma que as outras aplicações que não usam o &arts;: </para> + +<screen +><prompt +>%</prompt +> <userinput +><command +>artsdsp</command +> <option +>kaudioserver</option +></userinput +> +</screen> + +<para +>Você terá de ter instalado o 'kaudioserver' (a partir do mesmo local onde arranjou as suas aplicações do &kde; 1.x) - isso pertence ao &kde; 1.x, não ao &kde; 2. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>E as aplicações que usam o servidor de som <acronym +>ESD</acronym +> (Enlightened Sound Daemon)? </para> +</question> +<answer> +<para +>A questão é semelhante à do <application +>kaudioserver</application +>. Essas aplicações irão necessitar de um servidor 'esd' em execução. Você poderá iniciar o <command +>esd</command +> através do &artsdsp;, e todas as aplicações que usam o <acronym +>ESD</acronym +> deverão funcionar bem, como o seguinte: </para> +<screen +><prompt +>%</prompt +> <userinput +><command +>artsdsp</command +> <option +>esd</option +></userinput +> +</screen> +<para +>As versões mais novas do aRts ( +>= 1.2.0) também poderão usar o <acronym +>ESD</acronym +> em vez de aceder directamente à placa de som. Na linha de comandos, você poderá usar a opção '-a', tal como se segue </para> +<screen +><prompt +>%</prompt +> <userinput +><command +>artsd</command +> <option +>-a esd</option +></userinput +> +</screen> +<para +>para ter o suporte do EsounD; no caso do KDE, você poderá usar o &kcontrol; para configurar o 'artsd' para usar o 'esd' em Som -> Servidor de Som -> E/S de Som. </para> +</answer> +</qandaentry> + +</qandaset> + +<qandaset id="faq-latency"> +<title +>Latência</title> + +<qandaentry> +<question> +<para +>De vez em quando oiço pausas curtas ao ouvir música, isso é um erro? </para> +</question> +<answer> +<para +>Isto é provável que não seja um erro, mas seja causado pelo facto de que o 'kernel do &Linux; não é muito bom no escalonamento em tempo-real. Existem situações em que o &arts; não será capaz de se manter a tocar o som. Você poderá, contudo, activar as permissões de tempo-real (no &kcontrol;), e usar um valor de latência elevado (como por exemplo <guilabel +>250ms</guilabel +> ou <guilabel +>não interessa</guilabel +>), o que poderá sempre melhorar a situação. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Qual é o efeito da opção do tempo de resposta? </para> +</question> +<answer> +<para +>O texto de ajuda para esta opção no &kcontrol; poderá ser enganador. Um valor mais baixo significa que o &arts; irá levar menos tempo a responder aos eventos externos (&ie;. o tempo que leva entre fechar uma janela e ouvir um som tocado pelo &artsd;). Irá também usar mais recursos do <acronym +>CPU</acronym +> e estará mais sujeito a provocar perdas.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>Existe mais alguma coisa que eu possa fazer para evitar as pausas? </para> +</question> +<answer> +<para +>Para os utilizadores de unidades <acronym +>IDE</acronym +>, você poderá usar o comando <command +>hdparm</command +> para colocar as suas unidades <acronym +>IDE</acronym +> no modo <acronym +>DMA</acronym +>. Uma palavra de aviso: isto não funciona em todo o 'hardware', e poderá dar origem a uma reinicialização forte ou, em casos raros, à perda de dados. Leia a documentação sobre o comando <command +>hdparm</command +> para obter mais detalhes. Foi usado com sucesso o seguinte comando: </para> + +<screen +><prompt +>%</prompt +> <userinput +><command +>hdparm</command +> <option +>-c1</option +> <option +>-d1</option +> <option +>-k1</option +> <option +>-K1</option +> <parameter +>/dev/hda</parameter +></userinput +> +</screen> + +<para +>Você precisa de correr isto depois de cada arranque, por isso você poderá querer colocar isto num programa de arranque do sistema (como isso é feito depende da distribuição, mas no Debian &Linux; é normalmente colocado no <filename +>/etc/rc.boot</filename +>). </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>A prioridade de tempo-real não parece ter nenhum efeito em mim. Porquê? </para> +</question> +<answer> +<para +>Verifique se o 'artswrapper' está mesmo instalado 'suid' <systemitem class="username" +>root</systemitem +>, como é suposto que esteja. Muitas distribuições (como por exemplo o SuSE7.x) não fazem isto. Você poderá verificar isto se usar: ls -l $(which artswrapper). Bem: <screen> +<prompt +>%</prompt +> <userinput +><command +>ls</command +> <option +>-l</option +> <parameter +>$(which artswrapper)</parameter +></userinput> +-rwsr-xr-x 1 root root 4556 Sep 24 18:05 /opt/kde3/bin/artswrapper +</screen +> Mal: <screen> +<prompt +>%</prompt +> <userinput +><command +>ls</command +> <option +>-l</option +> <parameter +>$(which artswrapper)</parameter +></userinput> +-rwxr-xr-x 1 root root 4556 Sep 24 18:05 /opt/kde3/bin/artswrapper +</screen +> Se você não tiver um 's', poderá obtê-lo se fizer: <screen +><prompt +>%</prompt +> <userinput +><command +>chown</command +> <option +>root</option +> <parameter +>$(which artswrapper)</parameter +></userinput> +<prompt +>%</prompt +> <userinput +><command +>chmod</command +> <option +>4755</option +> <parameter +>$(which artswrapper)</parameter +></userinput +> +</screen> +</para> + +<para +>Se você tornar o &artswrapper; SUID <systemitem class="username" +>root</systemitem +>, ele irá provavelmente melhorar a qualidade da sua reprodução áudio, reduzindo os cortes na música. Contudo, aumenta também o risco de que um erro no código ou um utilizador malicioso façam estoirar ou prejudicar o seu sistema. Para além disso, nas máquinas multi-utilizador, a definição de prioridades de áudio de alta-fidelidade poderá resultar numa 'performance' mais reduzida para os utilizadores que estão a tentar tirar partido <quote +>produtivo</quote +> da máquina.</para> + +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para +>Porque é que o &artsd; está a ocupar tanto tempo de <acronym +>CPU</acronym +>? </para> +</question> +<answer> +<para +>Verifique a configuração do seu tempo de resposta. Contudo, a versão actual não está ainda realmente optimizada. Isto irá melhorar, e até lá, não há uma previsão real de quão rápido poderá o &artsd; ser ou não. </para> +</answer> +</qandaentry> +</qandaset> + +<qandaset id="faq-network"> +<title +>Transparência na Rede</title> + +<qandaentry> +<question> +<para +>O que é que preciso para a transparência na rede? </para> +</question> +<answer> +<para +>Active-a na configuração do <guilabel +>Servidor de Som</guilabel +> no &kcontrol; (<guilabel +>activar o servidor de X11 para a informação de segurança</guilabel +> e a <guilabel +>transparência na rede</guilabel +>). Depois copie o seu ficheiro <filename +>.mcoprc</filename +> para todas as máquinas onde você pensa usar a transparência na rede. Ligue-se de novo. Certifique-se que as máquinas que interagem conhecem as outras pelo seu nome (&ie; se elas têm nomes que possam ser resolvidos ou que se encontrem no <filename +>/etc/hosts</filename +>). </para> + +<para +>Isto deverá ser tudo o que precisa de fazer. Contudo, se continuar a não funcionar, existem ainda uns detalhes adicionais. O processo do servidor de som &arts;, o &artsd;, deverá só correr numa máquina, a que tem a placa de som onde o áudio deverá ser reproduzido. Poderá ser iniciado automaticamente no arranque pelo &kde; (se configurar isso no &kcontrol;) ou manualmente, se usar algo do género: </para> + +<screen +><prompt +>%</prompt +> <userinput +><command +>artsd</command +> <option +>-n</option +> <option +>-F</option +> <parameter +>5</parameter +> <option +>-S</option +> <parameter +>8192</parameter +></userinput +> +</screen> + +<para +>A opção <option +>-n</option +> é para a transparência na rede, enquanto que as outras configuram a latência. </para> + +<para +>O seu ficheiro <filename +>.mcoprc</filename +> deverá ter este item: </para> + +<screen +><userinput +>GlobalComm=Arts::X11GlobalComm</userinput +> +</screen> + +<para +>em todas as máquinas envolvidas, para que a transparência na rede funcione. Isto é o que fica activo pela opção do painel de controlo <guilabel +>servidor de X11 para a informação de segurança</guilabel +>. </para> + +<para +>Finalmente, em qualquer versão do &kde; da série 2.0.x, existe um erro que se aplica se você não tiver um nome de domínio definido. Os clientes do &artsd; tentam descobrir onde se ligam através da combinação <systemitem class="systemname" +><replaceable +>maquina</replaceable +>.<replaceable +>dominio</replaceable +></systemitem +>. Se o seu nome de domínio estiver em branco, ele irá tentar ligar-se à <systemitem class="systemname" +><replaceable +>maquina</replaceable +></systemitem +>. (repare no ponto extra). Se adicionar uma linha deste tipo ao <filename +>/etc/hosts</filename +> (&ie; <userinput +>orion.</userinput +>, se a sua máquina se chamar <systemitem class="systemname" +>orion</systemitem +>), dará a volta ao problema. </para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para +>Como é que eu faço depuração da transparência da rede se não funcionar? </para> +</question> +<answer> +<para +>Assumindo que você tem o código-fonte do &kde;, vá a <filename class="directory" +>tdelibs/arts/examples</filename +> e execute o comando <userinput +><command +>make</command +> <option +>check</option +></userinput +> para compilar alguns programas, incluindo o <application +>referenceinfo</application +>. Depois execute </para> + +<screen +><prompt +>%</prompt +> <userinput +><command +>./referenceinfo</command +> <option +>global:Arts_SimpleSoundServer</option +></userinput +> +</screen> + +<para +>O resultado irá indicar o nome da máquina e do porto que está a ser usado pelo &arts;. Por exemplo, <computeroutput +>tcp:orion:1698</computeroutput +> significa que qualquer cliente que tente usar a transparência de rede deverá saber como aceder à máquina <systemitem class="systemname" +>orion</systemitem +>. </para> +</answer> +</qandaentry> + +</qandaset> + +<qandaset id="faq-hardware-specific"> +<title +>Perguntas específicas do 'hardware'</title> + +<qandaentry> +<question> +<para +>Com que 'hardware' o 'artsd' não funciona bem? </para> +</question> +<answer> +<para +>Parece que existem alguns controladores de &Linux; que não funcionam bem com o &arts; em algumas versões do 'kernel'. Por favor, veja esta lista antes de relatar algum erro. Se você achar que alguma da informação desta lista está incompleta, por favor não hesite em dar-nos a conhecer. <informaltable +> <tgroup cols="4"> +<thead> +<row> +<entry +>Controlador do Linux / Placa de Som</entry> +<entry +>Não funciona em</entry> +<entry +>Funciona em</entry> +<entry +>Comentários</entry> +</row> +</thead> + +<tbody> +<row> +<entry +>controlador i810 (Intel 810 + Áudio AC97)</entry> +<entry +>2.4.9</entry> +<entry +>2.4.18, 2.2.20, controlador comercial do oss, alsa-0.5.12a com emulação de OSS</entry> +<entry +>o controlador provoca sobrecarga do CPU (ver em baixo)</entry> +</row> + +<row> +<entry +>'chipset' Maestro 3/4</entry> +<entry +>2.4.9</entry> +<entry +>?</entry> +<entry +>o controlador provoca algumas vezes sobrecarga do CPU (ver em baixo)</entry> +</row> + +<row> +<entry +>controladores do aureal8820, aureal8830 do Sourceforge</entry> +<entry +>2.4.17</entry> +<entry +>?</entry> +<entry +>o controlador lança excepções / causa sobrecarga do CPU (ver em baixo)</entry> +</row> + +<row> +<entry +>OSS Comercial 3.9.4g com Vértice Aural</entry> +<entry +>?</entry> +<entry +>?</entry> +<entry +>bloqueio do sistema</entry> +</row> + +<row> +<entry +>ymfpci</entry> +<entry +>2.4.0, 2.4.12</entry> +<entry +>2.4.17</entry> +<entry +>o controlador lança uma excepção (ver em baixo)</entry> +</row> + + + +</tbody> +</tgroup> +</informaltable> +</para> +</answer> +</qandaentry> + + + +<qandaentry> +<question> +<para +>Porque é que existem problemas específicos do 'hardware' e como é que os vejo? </para> +</question> +<answer> +<para +>O problema normal é que o controlador não fornece ao aRts a informação suficiente ou a correcta sobre quando deve escrever os dados do som. A maioria dos controladores do OSS fornecem a informação correcta, mas nem todos. </para> +<para +>Você poderá reparar que algumas das outras aplicações (como o 'xmms') poderão não necessitar desses dados, e poderão deste modo até funcionar correctamente com o seu 'hardware'. Contudo, o &arts; precisa destes dados, por isso o 'artsd' poderá falhar. Isto é à mesma um erro no controlador e não do &arts;. </para> +<para +>Existem dois tipos de comportamento que o 'artsd' expõe ao ser executado num controlador incorrecto. Ou ele tenta continuamente fornecer dados novos, mas nunca consegue de facto ser bem-sucedido, o que poderá levar eventualmente a que consuma todo o poder de processamento do CPU e acuse <emphasis +>sobrecarga do CPU</emphasis +> e saia. Ou então, o outro problema é que o 'artsd' poderá ser notificado com informações erradas sobre quanto deverá escrever. O 'artsd' irá então tentar <emphasis +>parar com uma excepção</emphasis +> do género: <screen +>artsd: audiosubsys.cc:458: void Arts::AudioSubSystem::handleIO(int): +Assertion `len == can_write' failed (A excepção 'len == can_write' falhou) +Aborted (Interrompido) +</screen> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>O que é que se passa no controlador se eu tiver o problema da sobrecarga do CPU?? </para> +</question> +<answer> +<para +>Normalmente, o 'artsd' usa o select() para tentar descobrir quando é que deverá escrever dados novos. Depois usa um ioctl(...GETOSPACE...) para saber quantos mais dados deverá escrever. Finalmente, ele irá escrever esses dados. </para> +<para +>Ocorre um problema se o 'artsd' é acordado sempre ou se existem quantidades pequenas de dados para escrever. A documentação do OSS diz que o select() só acorda um processo se existir pelo menos um fragmento para escrever. Contudo, se o 'artsd' é acordado e não existem dados para escrever ou são muito poucos, como por exemplo uma amostra, então ele irá continuar a escrever pedaços pequenos de dados de áudio, o que se poderá tornar muito dispendioso e, eventualmente, sobrecarregará o CPU. </para> +<para +>Para resolver isto, o controlador deverá acordar o 'artsd' apenas se existir um fragmento completo para escrever. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para +>O que se passa de errado no controlador se eu obtiver a excepção? </para> +</question> +<answer> +<para +>Normalmente, o 'artsd' usa o select() para tentar descobrir quando é que deverá escrever dados novos. Depois usa um ioctl(...GETOSPACE...) para saber quantos mais dados deverá escrever. Finalmente, ele irá escrever esses dados. </para> +<para +>Se o 'artsd' não consegue escrever tantos dados quantos são indicados pelo 'ioctl', ele irá falhar com a excepção. Para resolver isto, o controlador deverá indicar a quantidade de espaço livre correcta. </para> +</answer> +</qandaentry> +</qandaset> + +<qandaset id="faq-other"> +<title +>Outros Problemas</title> + +<qandaentry> +<question> +<para +>Não consigo usar o &arts-builder;. Ele estoira ao executar um módulo! </para> +</question> +<answer> +<para +>A causa mais provável será porque você está a usar estruturas ou módulos antigos que não são suportados na versão do &kde; 2. Infelizmente, a documentação que se encontra na Web refere-se ao &arts;-0.3.4.1, o qual está bastante desactualizado. O estoiro mais frequentemente relatado é: ao executar uma estrutura no &arts-builder; resulta na mensagem de erro <errorname +>[artsd] Synth_PLAY: audio subsystem is already used (o sub-sistema de áudio já está em uso).</errorname +> </para> + +<para +>Você deverá usar um módulo Synth_AMAN_PLAY em vez de um Synth_PLAY, para que o problema se vá embora. Veja também o ficheiro de ajuda do &arts-builder; (carregue em <keycap +>F1</keycap +> no &arts-builder;). </para> + +<para +>As versões mais recentes do &arts-builder; (do &kde; 2.1 beta 1 e posteriores) vêm com um conjunto de exemplos que você poderá usar. </para> +</answer> +</qandaentry> + +</qandaset> + +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/future.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/future.docbook new file mode 100644 index 00000000000..96886e88f2c --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/future.docbook @@ -0,0 +1,401 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant +V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="future-work"> +<title +>Trabalho Futuro</title> + +<para +>Esta secção descreve algum do trabalho do &arts; que se encontra em progresso. O desenvolvimento progride rapidamente, por isso esta informação poderá estar desactualizada. Você deverá ver o ficheiro da lista TODO e os arquivos das <link linkend="mailing-lists" +>listas de correio</link +> para ver quais as novas funcionalidades que estão planeadas. Sinta-se à vontade para se envolver no novo desenho e implementação. </para> + +<para +>Este é um rascunho do documento que lhe tenta dar uma ideia geral de como as novas tecnologias serão integradas no &arts;. Nomeadamente, cobre o seguinte: </para> + +<itemizedlist> +<listitem +><para +>Como é que as interfaces funcionam.</para +></listitem> +<listitem +><para +>Codificadores - a descodificação de sequências de MP3 ou WAV num formato em que possam ser usados como dados.</para +></listitem> +<listitem +><para +>Vídeo.</para +></listitem> +<listitem +><para +>Multi-tarefa.</para +></listitem> +<listitem +><para +>Sincronização.</para +></listitem> +<listitem +><para +>Expansão/máscara dinâmicas.</para +></listitem> +<listitem +><para +>Composição dinâmica.</para +></listitem> +<listitem +><para +>&GUI;</para +></listitem> +<listitem +><para +>&MIDI;</para +></listitem> +</itemizedlist> + +<para +>Isto ainda é trabalho em progresso. Contudo, deverá ser a base se você quiser ver tecnologias novas no &arts;. Ele dever-lhe-á dar uma ideia geral de como esses problemas serão tratados. Contudo, sinta-se à vontade para corrigir tudo o que verá aqui. </para> + +<para +>As coisas que serão utilizadas pela tecnologia do &arts; (por isso, coordenem os vossos esforços): </para> + +<itemizedlist> +<listitem> +<para +><application +>KPhone</application +> (voz sobre <acronym +>IP</acronym +>) </para> +</listitem> + +<listitem> +<para +>&noatun; (leitor de áudio / vídeo) </para> +</listitem> + +<listitem> +<para +>&artscontrol; (programa de controlo do servidor de som, para os âmbitos) </para> +</listitem> + +<listitem> +<para +><application +>Brahms</application +> (sequenciador de música) </para> +</listitem> + +<listitem> +<para +><application +>Kaiman</application +> (leitor multimédia do &kde;2 - compatível com o kmedia2) </para> +</listitem> + +<listitem> +<para +><application +>mpglib</application +>/<application +>kmpg</application +> (tecnologia de reprodução de áudio e vídeo <acronym +>mpg</acronym +>) </para> +</listitem> + +<listitem> +<para +><application +>SDL</application +> (camada multimédia directa para jogos que ainda não começou, mas que se tornará óptima) </para> +</listitem> + +<listitem> +<para +><application +>electric ears</application +> (o autor contactou-me - o estado é desconhecido) </para> +</listitem> +</itemizedlist> + +<sect1 id="interfaces-how"> +<title +>Como Funcionam as Interfaces</title> + +<!-- I think this is now obsolete and documented elsewhere ? --> + +<para +>As interfaces do &MCOP; são a base do conceito do &arts;. Elas são o equivalente transparente na rede das classes de C++. Sempre que possível, você deverá orientar o seu desenho para as interfaces. Estas consistem em quatro partes: </para> + +<itemizedlist> +<listitem +><para +>Sequências síncronas</para +></listitem> +<listitem +><para +>Sequências assíncronas</para +></listitem> +<listitem +><para +>Métodos</para +></listitem> +<listitem +><para +>Atributos</para +></listitem> +</itemizedlist> + +<para +>Estes poderão ser misturados da forma que você desejar. As novas tecnologias deverão ser definidas em termos de interfaces. Leia as secções sobre as sequências assíncronas e síncronas, assim como as interfaces do KMedia2, os quais são um bom exemplo sobre como as coisas funcionam </para> + +<para +>As interfaces são especificadas no código <literal role="extension" +>.idl</literal +> e executadas através do compilador <command +>mcopidl</command +>. Você deriva da classe <classname +><replaceable +>NomeInterface</replaceable +>_impl</classname +> para as implementar e usa a função <function +>REGISTER_IMPLEMENTATION(NomeInterface_impl)</function +> para inserir as implementações do seu objecto no sistema de objectos do &MCOP;. </para> + +</sect1> + +<sect1 id="codecs"> +<title +>Codificadores - Descodificação de Dados</title> + +<para +>As interfaces do 'kmedia2' permitem-lhe ignorar que os ficheiros WAV, MP3 entre outros consistem em sequências de dados. Em alternativa, você só implementa os métodos para os tocar. </para> + +<para +>Deste modo, você poderá criar uma rotina de carregamento de WAVE's de forma a que você possa tocar ficheiros WAVE (como PlayObject), mas mais ninguém pode usar o seu código. </para> + +<para +>As sequências assíncronas seriam a alternativa. Você define uma interface que lhe permite passar os blocos de dados para dentro extrair blocos de dados para fora. Isto parece ser mesmo assim no &MCOP;: </para> + +<programlisting +>interface Codificador { + entrada async byte stream indata; + saida async byte stream outdata; +}; +</programlisting> + + +<para +>Claro que os codificadores também poderão fornecer parâmetros para emitir dados adicionais, tais como a informação do formato. </para> + +<programlisting +>interface CodificadorAudioByte { + entrada async byte stream indata; + saida async byte stream outdata; + readonly attribute amostragem, bits, canais; +}; +</programlisting> + +<para +>Este <interfacename +>CodificadorAudioByte</interfacename +>, por exemplo, poder-se-ia ligar a um objecto <interfacename +>ByteStreamToAudio</interfacename +> para suportar áudio de vírgula flutuante. </para> + +<para +>Claro, outros tipos de codificadores poderiam envolver directamente a emissão de dados de vídeo, como por exemplo </para> + +<programlisting +>interface CodecVideo { + entrada async byte stream indata; + saida video stream outdata; /* nota: as sequências de vídeo ainda não existem */ +}; +</programlisting> + +<para +>Muito provavelmente, o conceito de um codificador deveria se aplicado em vez da forma <quote +>você sabe como tocar e eu não</quote +> como, por exemplo, o <interfacename +>WavPlayObject</interfacename +> usa no momento. Contudo, alguém precisa de parar e fazer algumas experiências antes de API <acronym +>API</acronym +> ser finalizada. </para> + +</sect1> + +<sect1 id="video"> +<title +>Vídeo</title> + +<para +>A ideia é fornecer o vídeo como sequências assíncronas de algum tipo de dados nativo do &MCOP; que contenha imagens. Este tipo de dados ainda está por ser criado. Ao fazê-lo, os 'plugins' que lidem com as imagens de vídeo poderão ser ligados da mesma forma que os 'plugins' de áudio. </para> + +<para +>Existem algumas coisas que são importantes não deixar de fora, nomeadamente: </para> + +<itemizedlist> +<listitem> +<para +>Existem os espaços de cores <acronym +>RGB</acronym +> e <acronym +>YUV</acronym +>. </para> +</listitem> +<listitem> +<para +>O formato deverá ser associado de qualquer forma à sequência. </para> +</listitem> +<listitem> +<para +>A sincronização é importante. </para> +</listitem> +</itemizedlist> + +<para +>A ideia é deixar possível a reimplementação da classe <classname +>VideoFrame</classname +> (ImagemVideo) para que possa armazenar a informação num segmento de memória partilhada. Ao fazê-lo, até a difusão de vídeo entre os diferentes processos seria possível sem muito trabalho. </para> + +<para +>Contudo, a situação normal para o vídeo é que as coisas estão todas no mesmo processo, desde a descodificação até ao desenho. </para> + +<para +>Foi feita uma implementação em protótipo de emissão de vídeo, a qual poderá obter <ulink url="http://space.twc.de/~stefan/kde/download/video-quickdraw.tar.gz" +>aqui</ulink +>. Isto teria de ser integrado no &MCOP; ao fim de algumas experiências. </para> + +<para +>Uma componente de desenho deveria ser fornecida que suportasse o XMITSHM (com o <acronym +>RGB</acronym +> e o <acronym +>YUV</acronym +>); o Martin Vogt comunicou que estava a fazer algo do género. </para> + +</sect1> + +<sect1 id="threading"> +<title +>Multitarefa</title> + +<para +>De momento, o &MCOP; é todo ele monotarefa. Talvez para o vídeo não seja mais possível dar a volta a essa questão. Ok. Existem algumas coisas que têm de ser tratadas com cuidado: </para> + + +<itemizedlist> +<listitem +><para +>SmartWrappers - estes não são seguros em multitarefa devido à contagem de referências insegura, entre outras questões similares. </para> +</listitem> +<listitem> +<para +>'Dispatcher' / E/S - Também inseguros em multitarefa. </para> +</listitem> +</itemizedlist> + +<para +>Contudo, o que é possível imaginar é tornar os módulos seguros em multitarefa para ambos os casos de sequências, síncronas e assíncronas. Desta forma - com um sistema de fluxo que suporte multitarefa, você poderá escalonar o fluxo do sinal por dois ou mais processadores. Isto iria ajudar bastante no áudio em sistemas multi-processador. </para> + +<para +>Como iria funcionar: </para> + + +<itemizedlist> +<listitem> +<para +>O Sistema de Fluxo decide que módulos deverão calcular o quê - isto é: </para> + <itemizedlist> + <listitem +><para +>imagens de vídeo (com o método 'process_indata')</para +></listitem> + <listitem +><para +>sequências de áudio síncronas ('calculateBlock')</para +></listitem> + <listitem +><para +>outras sequências assíncronas, nomeadamente sequências de 'bytes'</para +></listitem> + </itemizedlist> +</listitem> +<listitem> +<para +>Os módulos poderão calcular estas coisas em tarefas próprias. Para o áudio, faz sentido reutilizar as tarefas (⪚ aplicar em quatro tarefas por quatro processadores, independentemente de estarem a correr 100 módulos). Para a descompressão de vídeo e de 'bytes', poderá ser mais confortável ter uma implementação bloqueante numa tarefa própria, a qual está sincronizada com o resto do &MCOP; pelo sistema de fluxo. </para> +</listitem> + +<listitem> +<para +>Os módulos não poderão usar a funcionalidade do &MCOP; (como as invocações remotas) durante a operação multitarefa. </para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="synchronization"> +<title +>Sincronização</title> + +<para +>O vídeo e o &MIDI; (e o áudio) poderão necessitar de sincronização. Basicamente, baseia-se em marcas temporais. A ideia que existe é anexar as marcas temporais às sequências síncronas, adicionando esse campo a cada pacote. Se você enviar duas imagens de vídeo, simplesmente crie dois pacotes (eles são grandes, de qualquer forma), por isso poderá ter duas marcas temporais diferentes. </para> + +<para +>O áudio deverá ter implicitamente marcas temporais, dado que é síncrono. </para> + +</sect1> + +<sect1 id="dynamic-composition"> +<title +>Composição Dinâmica</title> + +<para +>Deveria ser possível dizer: um FX de efeito é composto a partir destes módulos mais simples. O FX deverá funcionar como um módulo de &MCOP; normal (veja a máscara), mas de facto consiste noutros módulos. </para> + +<para +>Isto é necessário para o &arts-builder;. </para> + +</sect1> + +<sect1 id="gui"> +<title +>&GUI;</title> + +<para +>Todos os componentes &GUI; serão módulos do &MCOP;. Eles deverão ter atributos do tipo 'size' (tamanho), 'label' (texto), 'color' (cor), ... . Um construtor <acronym +>RAD</acronym +> (como o &arts-builder;) deverá ser capaz de os compor visualmente. </para> + +<para +>A &GUI; deverá ser gravável, ao registar os atributos. </para> + +</sect1> + +<sect1 id="midi-stuff"> +<title +>&MIDI;</title> + +<para +>A funcionalidade do &MIDI; será implementada como sequências assíncronas. Existem duas opções, em que uma usa estruturas normais de &MCOP; para definir os tipos e o outro para introduzir ainda outros tipos personalizados. </para> + +<para +>Pensa-se que as estruturas normais serão suficientes, isto é, algo do tipo: </para> + +<programlisting +>struct EventoMidi { + byte b1,b2,b3; + sequence<byte> existe; +} +</programlisting> + +<para +>As sequências assíncronas deverão suportar os tipos de sequências personalizados. </para> + +</sect1> + +</chapter> + + diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/glossary.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/glossary.docbook new file mode 100644 index 00000000000..97fe21f5473 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/glossary.docbook @@ -0,0 +1,177 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE glossary PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<glossary id="glossary"> + +<glossentry id="gloss-alsa"> +<glossterm +><acronym +>ALSA</acronym +></glossterm> +<glossdef> +<para +>Advanced &Linux; Sound Architecture (Arquitectura de Som Avançada do &Linux;); um controlador de placas de som do &Linux;, e que não vem incluída de momento no código-fonte normal do 'kernel'. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-arts"> +<glossterm +>&arts;</glossterm> +<glossdef> +<para +>Analog Real-Time Synthesizer (Sintetizador em Tempo-Real Analógico); o nome da arquitectura/biblioteca/ferramenta multimédia que é usada pelo projecto do &kde; (repare na capitalização) </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-bsd"> +<glossterm +><acronym +>BSD</acronym +></glossterm> +<glossdef> +<para +>Berkeley Software Distribution (Distribuição de 'Software' da Berkeley); aqui refere-se a qualquer um dos sistemas operativos livres e compatíveis com o &UNIX;, que derivam do &UNIX; da <acronym +>BSD</acronym +>. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-corba"> +<glossterm +><acronym +>CORBA</acronym +></glossterm> +<glossdef> +<para +>Common Object Request Broker Architecture (Arquitectura de Mediação de Pedidos de Objectos Comuns); uma norma para implementar a execução remota orientada por objectos. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-cvs"> +<glossterm +><acronym +>CVS</acronym +></glossterm> +<glossdef> +<para +>Concurrent Versions System (Sistema Concorrente de Versões); um sistema de gestão de configurações de 'software' que é usado por muitos projectos de sistemas, e que inclui o &kde; e o &arts;. </para> +</glossdef> +</glossentry> + +<glossentry id="glos-fft"> +<glossterm +><acronym +>FFT</acronym +></glossterm> +<glossdef> +<para +>Fast Fourier Transform (Transformada de Fourier Rápida); um algoritmo para converter dados do domínio do tempo para o da frequência; é usado frequentemente no processamento de sinais. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-full-duplex"> +<glossterm +>Full Duplex</glossterm> +<glossdef> +<para +>A capacidade de uma placa de som gravar e reproduzir áudio em simultâneo. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-gpl"> +<glossterm +><acronym +>GPL</acronym +></glossterm> +<glossdef> +<para +><acronym +>GNU</acronym +> General Public License (Licença Pública Geral da <acronym +>GNU</acronym +>); uma licença de 'software' criada pela Free Software Foundation para definir os termos para lançar 'software' livre. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-gui"> +<glossterm +>&GUI;</glossterm> +<glossdef> +<para +>Interface Gráfica com o Utilizador </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-idl"> +<glossterm +><acronym +>IDL</acronym +></glossterm> +<glossdef> +<para +>Interface Definition Language (Linguagem de Definição de Interfaces); uma linguagem de programação que é independente do formato para especificar as interfaces (os métodos e os dados). </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-kde"> +<glossterm +>&kde;</glossterm> +<glossdef> +<para +>K Desktop Environment (Ambiente de Trabalho K); um projecto para desenvolver um ambiente de trabalho gráfico livre para os sistemas compatíveis com o &UNIX;. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-lgpl"> +<glossterm +><acronym +>LGPL</acronym +></glossterm> +<glossdef> +<para +><acronym +>GNU</acronym +> Lesser General Public License (Licença Pública Geral Lata da <acronym +>GNU</acronym +>; uma licença de 'software' criada pela Free Software Foundation e que define os termos para lançar 'software' livre; é menos restrita que a <acronym +>GPL</acronym +> e é usada com frequência pelas bibliotecas de 'software'. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-mcop"> +<glossterm +>&MCOP;</glossterm> +<glossdef> +<para +>Multimedia COmmunication Protocol (Protocolo de Comunicação Multimédia); o protocolo usado para a comunicação entre os módulos de 'software' do &arts;; é semelhante ao <acronym +>CORBA</acronym +> mas é mais simples e é optimizado para o multimédia. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-midi"> +<glossterm +>&MIDI;</glossterm> +<glossdef> +<para +>Musical Instrument Digital Interface (Interface Digital de Instrumentos Musicais); um protocolo-padrão para comunicar entre os instrumentos musicais electrónicos; é usado também normalmente para se referir a um formato de ficheiros que armazena os comandos &MIDI;. </para> +</glossdef> +</glossentry> + +<glossentry id="gloss-oss"> +<glossterm +><acronym +>OSS</acronym +></glossterm> +<glossdef> +<para +>Open Sound System (Sistema de Som Aberto); os controladores de som que vêm incluídos no 'kernel' do &Linux; (normalmente chamado de <acronym +>OSS</acronym +>/Free) ou uma versão comercial que é vendida pela 4Front Technologies. </para> +</glossdef> +</glossentry> + +</glossary> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/gui.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/gui.docbook new file mode 100644 index 00000000000..b769c161b6b --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/gui.docbook @@ -0,0 +1,29 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<!-- +<chapter id="gui-elements"> +<title +>&GUI; Elements</title> + +<sect1 id="gui-introduction"> +<title +>Introduction</title> + +</sect1> + +<sect1 id="parents"> +<title +>Parents</title> + +</sect1> + +<sect1 id="mixers"> +<title +>Mixers</title> + +</sect1> +</chapter> +--> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/helping.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/helping.docbook new file mode 100644 index 00000000000..1a50cb5fadd --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/helping.docbook @@ -0,0 +1,237 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="contributing"> +<title +>Contribuir para o &arts;</title> + +<sect1 id="how-to-help"> +<title +>Como Pode Ajudar</title> + +<para +>O projecto do &arts; poderá usar a ajuda dos programadores para tornar as aplicações multimédia cientes do &arts;, criar aplicações multimédia novas e melhorar as capacidades do &arts;. Contudo, você não terá de ser um programador para contribuir. A ajuda também poderá ser usada para as pessoas dos testes para enviarem relatórios de erros, traduções do texto e da documentação das aplicações para outras línguas, artistas para desenharem imagens (especialmente para os módulos do <application +>artsbuilder</application +>), músicos para criarem módulos de amostras do &arts; e escritores para criarem ou validarem a correcção da documentação. </para> +</sect1> + +<sect1 id="mailing-lists"> +<title +>Listas de Correio</title> + +<para +>A maioria das discussões de programação do &arts; tomam lugar em duas listas de correio. Este é o lugar para discutir as novas ideias de funcionalidades e de implementação, ou para pedir ajuda para alguns problemas. </para> + +<para +>A lista de correio de Multimédia do &kde; é para os assuntos gerais de multimédia do &kde;, e que inclui o &arts;, assim como as aplicações multimédia, como o &noatun; e o &aktion;. Você poder-se-á subscrever na página Web em <ulink url="http://www.kde.org/mailinglists.html" +> http://www.kde.org/mailinglists.html</ulink +> ou enviar uma mensagem de e-mail com o assunto igual a <userinput +>subscribe <replaceable +>o-seu-endereço-de-e-mail</replaceable +></userinput +> para <email +>kde-multimedia-request@kde.org</email +>. A lista está também arquivada em <ulink url="http://lists.kde.org" +> http://lists.kde.org</ulink +>. </para> + +<para +>A lista de correio do &arts; é para os assuntos específicos do &arts;, incluindo a utilização fora do &kde; do &arts;. Para se subscrever, envie uma mensagem de e-mail que contenha o corpo da mensagem <userinput +>subscribe <replaceable +>o-seu-endereço-de-e-mail</replaceable +></userinput +> para <email +>arts-request@space.twc.de</email +>. A lista é arquivada em <ulink url="http://space.twc.de/~stefan/arts-archive" +> http://space.twc.de/~stefan/arts-archive</ulink +>. </para> + +</sect1> + +<sect1 id="coding-standards"> +<title +>Normas de Código</title> + +<para +>Para obter uma leitura consistente de todo o código, é importante manter o estilo de código igual entre si em todo o código do &arts;. Por favor, mesmo que você só crie um módulo, tente escrever/formatar o seu código de acordo com as recomendações, para que facilite para as várias pessoas manterem a estrutura de código e para ser mais fácil de copiar pedaços de código de um bloco para outro. </para> + +<variablelist> +<varlistentry> +<term +>Nome das funções-membro</term> +<listitem> +<para +>Estilo do &Qt;/&Java;. Isso equivale à capitalização nas quebras de palavras, tendo a primeira letra em minúsculas; sem sublinhados. </para> +<para +>Isto significa, por exemplo:</para> + +<programlisting +>criarDescrEstrutura() + actualizarItem(); + iniciar(); </programlisting> + +</listitem> +</varlistentry> + +<varlistentry> +<term +>Membros da classe</term> +<listitem> +<para +>Os membros da classe não são capitalizados, como por exemplo 'barramenu' ou 'botao'. </para> + +<para +>Quando existirem funções de acesso, a norma deverá ser a do &MCOP;, isto é, ao ter um membro 'long' <function +>xpto</function +>, o qual não será visível directamente, você cria funções: </para> + +<programlisting +>xpto(long novo_valor); + long xpto(); </programlisting> + +<para +>para obter e alterar o valor. Nesse caso, o valor real de <function +>xpto</function +> serão armazenadas em <returnvalue +>_xpto</returnvalue +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>Nomes das classes</term> +<listitem> +<para +>Todas as classes deverão ser capitalizadas nas palavras, o que significa <classname +>JanelaModulo</classname +>, <classname +>ModuloSintese</classname +>. Todas as classes que pertencem às bibliotecas deverão usar o espaço de nomes do &arts;, como o <classname +>Arts::Soundserver</classname +>. </para> +<para +>As implementações das classes do &MCOP; dever-se-ão chamar <classname +>Classe_impl</classname +>, como por exemplo <classname +>ServidorSom_impl</classname +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>Parâmetros</term> +<listitem> +<para +>Os parâmetros nunca estão capitalizados. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>Variáveis locais</term> +<listitem> +<para +>As variáveis locais nunca são capitalizadas, e poderão ter nomes do tipo <varname +>i</varname +>, <varname +>p</varname +>, <varname +>x</varname +>, &etc;, sempre que apropriado. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>Tamanho da tabulação</term> +<listitem> +<para +>Uma tabulação equivale neste caso a 4 espaços. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>Espaços nas expressões</term> +<listitem> +<para +>Você não precisa normalmente de usar espaços nas expressões. Você poderá, no entanto, usá-los entre os operadores e os seus operandos. Todavia, se você puser um espaço antes de um operador (p.ex., o +), você também precisa de pôr um a seguir ao mesmo. A única excepção a isto são as expressões do tipo lista (com o ,), onde você deverá pôr um espaço a seguir ao ",", mas não antes. Também é aceitável omitir aqui o espaço. </para> +<para +>Os exemplos seguintes demonstram uma boa utilização dos espaços: </para> +<programlisting +>{ + int a,b; + int c, d, e; + int f = 4; + + a=b=c=d+e+f; + a = b = c = d + e + f; + + if(a == 4) { + a = b = c = (d+e)/2; + } + + while(b<3) + c--; + + arts_debug("%d\n", c); +} +</programlisting> +<para +>Os exemplos seguintes demonstram como <emphasis +>não</emphasis +> usar os espaços. Para as chamadas as funções, a seguir ao 'if', 'while', 'for', 'switch', entre outros, não é adicionado nenhum espaço. </para> +<programlisting +>{ + // MAL: se você indicar uma lista, ponha espaços apenas após o "," + int a , b , c , d , e , f; + + // MAL: utilização não-simétrica dos espaços no operador '=' + a= 5; + + // MAL: se for considerada uma função, e se não for seguida de um espaço + if (a == 5) { + } + + // MAL: não colocar um espaço a seguir ao 'while' + while (a--) + b++; + + // MAL: os nomes das funções não são seguidos de um espaço + arts_debug ("%d\n", c); + + // MAL: nada aqui é o nome de um membro + Arts::Object o = Arts::Object::null (); +} +</programlisting> +</listitem> +</varlistentry> + + +<varlistentry> +<term +>Nomenclatura dos ficheiros de código</term> +<listitem> +<para +>Os ficheiros de código aqui não deverão ter capitalizações no nome. Deverão ter o nome da classe quando implementam uma única classe. A sua extensão é a <literal role="extension" +>.cc</literal +> se se referirem ao código independente do &Qt;/&GUI;, e <literal role="extension" +>.cpp</literal +> se se referirem ao código dependente do &Qt;/&GUI;. Os ficheiros de implementação das interfaces dever-se-á chamar <filename +><replaceable +>xpto</replaceable +>_impl</filename +>, se o Xpto for o nome da interface. </para> + +<para +>Os ficheiros &IDL; deverão ser chamados de uma forma descritiva para a colecção de interfaces que eles contêm, estando tudo também em minúsculas. Especialmente, não é bom chamar a um ficheiro &IDL; o nome da classe, dado que o mediador .mcopclass e os itens do tipo de informação irão colidir, nesse caso. </para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/index.cache.bz2 b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/index.cache.bz2 Binary files differnew file mode 100644 index 00000000000..480eb157ffe --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/index.cache.bz2 diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/index.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/index.docbook new file mode 100644 index 00000000000..694c9f22279 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/index.docbook @@ -0,0 +1,417 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&arts;"> + <!ENTITY tools SYSTEM "tools.docbook"> + <!ENTITY artsbuilder-doc SYSTEM "artsbuilder.docbook" +> + <!ENTITY detail SYSTEM "detail.docbook"> + <!ENTITY arts-midi SYSTEM "midi.docbook"> + <!ENTITY gui SYSTEM "gui.docbook"> + <!ENTITY mcop-ref SYSTEM "mcop.docbook"> + <!ENTITY arts-mcop SYSTEM "mcop.docbook"> + <!ENTITY apis SYSTEM "apis.docbook"> + <!ENTITY modules SYSTEM "modules.docbook"> + <!ENTITY porting SYSTEM "porting.docbook"> + <!ENTITY helping SYSTEM "helping.docbook"> + <!ENTITY future SYSTEM "future.docbook"> + <!ENTITY references SYSTEM "references.docbook"> + <!ENTITY arts-faq SYSTEM "faq.docbook"> + <!ENTITY arts-glossary SYSTEM "glossary.docbook"> + <!ENTITY digitalaudio SYSTEM "digitalaudio.docbook"> + <!ENTITY midiintro SYSTEM "midiintro.docbook"> + <!ENTITY MCOP "<acronym +>MCOP</acronym +>"> + <!ENTITY DCOP "<acronym +>DCOP</acronym +>"> + <!ENTITY MIDI "<acronym +>MIDI</acronym +>"> + <!ENTITY mcopidl "<application +>mcopidl</application +>"> + <!ENTITY IDL "<acronym +>IDL</acronym +>"> + <!ENTITY % Portuguese "INCLUDE" +> <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> +<bookinfo> +<title +>O Manual do &arts;</title> +<authorgroup> + +<author +><firstname +>Stefan</firstname +> <surname +>Westerfeld</surname +> <affiliation +> <address +><email +>stefan@space.twc.de</email +></address> +</affiliation> +</author> + +<author +><firstname +>Jeff</firstname +> <surname +>Tranter</surname +> <affiliation +> <address +><email +>tranter@kde.org</email +></address> +</affiliation> +</author> + +<othercredit role="translator" +><firstname +>José</firstname +><surname +>Pires</surname +><affiliation +><address +><email +>jncp@netcabo.pt</email +></address +></affiliation +><contrib +>Tradução</contrib +></othercredit +> +</authorgroup> + +<copyright> +<year +>1999-2001</year> +<holder +>Stefan Westerfeld & Jeff Tranter</holder> +</copyright> +<legalnotice +>&FDLNotice;</legalnotice> + +<date +>2001-06-10</date> +<releaseinfo +>1.00.09</releaseinfo> + +<abstract +><para +>Este manual descreve o &arts;, o Sintetizador de Tempo-Real Analógico.</para> + +</abstract> + +<keywordset> +<keyword +>aRts</keyword> +<keyword +>artsbuilder</keyword> +<keyword +>sintetizador</keyword> +<keyword +>multimédia</keyword> +<keyword +>estrutura</keyword> +<keyword +>música</keyword> +<keyword +>som</keyword> +<keyword +>KDE</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title +>Introdução</title> + +<sect1 id="what-is-arts"> +<title +>O que é o &arts;?</title> + +<para +>O Sintetizador de Tempo-Real Analógico, ou &arts;, é um sistema modular para sintetizar o som e a música num computador digital. Usando blocos de construção pequenos chamados módulos, o utilizador poderá criar facilmente ferramentas de processamento de áudio complexas. Os módulos oferecem tipicamente funções como geradores de formas de onda, filtros, efeitos de áudio, mistura de som, reprodução de áudio digital em vários formatos de ficheiros diferentes.</para> + +<para +>O servidor de som &artsd; mistura o áudio de várias fontes em tempo-real, permitindo a várias aplicações de som partilharem de forma transparente o acesso ao 'hardware' de som.</para> + +<para +>Usando o &MCOP; (Multimedia Communication Protocol), as aplicações multimédia poderão ser transparentes na rede, autenticadas do ponto de vista da segurança, e multiplataforma, recorrendo à utilização de interfaces definidas de forma independente da linguagem com o &IDL;. O suporte também é fornecido para as aplicações legadas que não saibam do &arts;. Como componente de base para o ambiente de trabalho do &kde; 2, o &arts; fornece a base da arquitectura multimédia do &kde; e irá no futuro suportar outros tipos multimédia, incluindo o vídeo. Tal como o &kde;, o &arts; corre numa variedade de sistemas operativos, incluindo o &Linux; e as variantes do BSD. Pode ser usado independentemente do &kde;.</para> + +</sect1> + +<sect1 id="using-this-manual"> +<title +>Usar Este Manual</title> + +<para +>Este manual pretende oferecer uma documentação compreensiva sobre o &arts; aos utilizadores com diferentes níveis de aptidões. Dependendo se você é um utilizador normal de aplicações multimédia que tiram partido do &arts; ou um programador de aplicações multimédia, você poderá querer seguir caminhos diferentes ao longo do manual.</para> + +<para +>Sugere-se que você leia primeiro o capítulo de <link linkend="installation" +>Transferir e Compilar o &arts;</link +> se precisar de ter o &arts; instalado inicialmente e em funcionamento. Se você já tiver um sistema funcional, provavelmente incluído na distribuição do seu sistema operativo, você poderá optar por ignorar esta secção.</para> + +<para +>Você deverá então ler as secções no capítulo das <link linkend="arts-tools" +>Ferramentas do &arts;</link +>, especialmente o do &artsd;, do 'artscontrol';, do '&artsshell;', e do '&artsdsp;'. Isto ajudá-lo-á a tirar o partido mais efectivo do &arts;.</para> + +<para +>Se você estiver interessado em ir mais além com o &arts;, leia o capítulo sobre o <link linkend="artsbuilder" +>&arts-builder;</link +> e siga ao longo do tutorial. Isto deverá dar-lhe uma apreciação global das capacidades poderosas do &arts; e dos módulos fornecidos que poderão ser usados sem haver necessidade de ser um programador.</para> + +<para +>Se você quiser saber mais sobre os detalhes do &arts;, quer para desenvolver aplicações multimédia quer para extender o próprio &arts;, leia uma parte ou todo o capítulo <link linkend="arts-in-detail" +>O &arts; em Detalhe</link +>. Isto deverá permitir-lhe compreender todos os conceitos considerados como pré-requisitos da programação de 'software' com o &arts;.</para> + +<para +>Se você estiver interessado especificamente nas capacidades de <acronym +>MIDI</acronym +> do &arts;, deverá ler o capítulo sobre o <link linkend="midi" +>&MIDI;</link +>.</para> + +<!-- TODO +<para +>To learn more about the &arts; graphical elements, either as an advanced +user of artsbuilder or to create new elements, read the section on <link +linkend="gui-elements" +><acronym +>GUI</acronym +> Elements</link +>.</para> +--> + +<para +>Se quiser desenvolver aplicações multimédia que suportem o &arts;, o capítulo das <link linkend="arts-apis" +>Interfaces de Programação de Aplicações do &arts;</link +> cobrem as diferentes <acronym +>API</acronym +>s em detalhe.</para> + +<para +>Se você quiser extender o &arts;, criando para tal novos módulos, leia o capítulo dos <link linkend="arts-modules" +>Módulos do &arts;</link +>.</para> + +<para +>Se estiver a modificar uma aplicação existente para correr sob o &arts;, leia o capítulo sobre <link linkend="porting" +>Transformar Aplicações para o &arts;</link +>.</para> + +<para +>Você poderá saber como ajudar a contribuir para o projecto do &arts; no capítulo <link linkend="contributing" +>Contribuir para o &arts;</link +>, ler sobre os próximos desenvolvimentos no capítulo sobre o <link linkend="future-work" +>Trabalho Futuro</link +>, e obter referências para mais informações na secção de <link linkend="references" +>Referências</link +>.</para> + +<para +>Foi dada uma volta ao manual com algum material adicional, incluindo as <link linkend="faq" +>respostas às perguntas mais frequentes</link +>, uma <link linkend="contributors" +>lista das contribuições</link +>, os detalhes sobre o &arts; o <link linkend="copyright-and-licenses" +>'copyright' e as licenças</link +>, bem como algum material de fundo sobre o <link linkend="intro-digital-audio" +>áudio digital</link +> e o <link linkend="midi-introduction" +>&MIDI;</link +>. Está também incluído um <link linkend="glossary" +>glossário</link +> de termos.</para> + +<note> +<para +>Este manual ainda tem muito trabalho por fazer. Você é bem-vindo para contribuir na escrita de partes dele, mas se o quiser fazer, contacte o Jeff Tranter <email +>tranter@kde.org</email +> ou o Stefan Westerfeld <email +>stefan@space.twc.de</email +> para evitar a duplicação de esforço. </para> +</note> + +</sect1> + +<sect1 id="history"> +<title +>Histórico</title> + +<para +>No fim de 1997, o Stefan Westerfeld começou a trabalhar num sistema modular em tempo-real para a síntese de som. O código corria inicialmente num sistema PowerPC que funcionava em &AIX;. Essa implementação era muito simples, mas suportava um sistema de fluxo completo que era capaz de fazer coisas como tocar ficheiros MP3 e encaminhar os canais de áudio por módulos de efeitos. </para> + + +<para +>O próximo passo foi implementar uma &GUI; de modo a que os módulos pudessem ser manipulados graficamente. O Stefan tem tido algumas experiências boas com o &kde;, de modo que foi escolhido como a plataforma &GUI;, (sabendo que poderá ser necessário fazer também uma versão para GNOME/Gtk+) e isto levou posteriormente a usar o &Linux; como plataforma principal de desenvolvimento. Chamado anteriormente de <application +>ksynth</application +>, o projecto mudou de nome para &arts; e a rapidez de desenvolvimento acelerou. O projecto nesta fase estava muito completo, com um protocolo baseado em <acronym +>CORBA</acronym +>, com dezenas de módulos, uma ferramenta gráfica de edição de módulos, <acronym +>API</acronym +>s em C e C++, documentação, utilitários, páginas Web e listas de correio com um pequeno grupo de programadores. O projecto avançou bastante com pouco mais do que um ano de desenvolvimento.</para> + +<para +>Assim que a equipa do &kde; começou a planear o &kde; 2.0, tornou-se óbvio que o &kde; necessitava de uma infra-estrutura mais poderosa para o som e para os conteúdos multimédia. Optou-se por adaptar o &arts;, dado que era um bom passo nesta direcção com uma arquitectura estável. Muito do esforço de desenvolvimento foi aplicado nesta nova versão do &arts;, sendo o mais notável a substituição do código em <acronym +>CORBA</acronym +> por um sub-sistema completamente novo, o &MCOP;, optimizado para o multimédia. A versão 0.4 do &arts; foi incluída na versão 2.0 do &kde;.</para> + +<para +>O trabalho continua no &arts;, melhorando a performance e adicionando novas funcionalidades. Deverá ser visto que até mesmo o &arts; é agora um componente de base do &kde;, embora possa ser usado sem o &kde;, e também é usado por aplicações que vão mais além do multimédia tradicional. O projecto atraiu algum interessa da equipa do GNOME, abrindo a possibilidade a que alguma vez se torne a arquitectura-padrão do multimédia nos ambientes de trabalho do &UNIX;.</para> + +</sect1> + +</chapter> + +&tools; +&artsbuilder-doc; +&detail; +&arts-midi; +&gui; +&mcop-ref; +&apis; +&modules; +&porting; +&helping; +&future; +&references; +&arts-faq; + +<chapter id="copyright-and-licenses"> + +<title +>'Copyright' e Licenças do &arts;</title> + +<para +>'Software' do &arts; copyright 1998-2001 Stefan Westerfeld <email +>stefan@space.twc.de</email +></para> + +<para +><anchor id="contributors"/> Documentação copyright 1999-2001 Stefan Westerfeld <email +>stefan@space.twc.de</email +> e Jeff Tranter <email +>tranter@kde.org</email +>. </para> +<para +>Tradução de José Nuno Pires <email +>jncp@netcabo.pt</email +></para +> +&underFDL; <para +>Todas as bibliotecas que existem no &arts; estão licenciadas segundo os termos da licença <acronym +>GNU</acronym +> Lesser General Public. A grande maioria do código do &arts; está nas bibliotecas, incluindo todo o <acronym +>MCOP</acronym +> e o ArtsFlow. Isto permite às bibliotecas serem usadas para aplicações não-livres e não-gratuitas, se o desejar. </para> + +<para +>Existem alguns programas (como o <application +>artsd</application +>), que são lançados segundo os termos da General Public License da <acronym +>GNU</acronym +>. Dado que têm havido algumas opiniões diferentes sobre se é legal compilar programas <acronym +>GPL</acronym +> com o &Qt;, foi adicionada também uma nota explícita que o permite, para além da <acronym +>GPL</acronym +>: a permissão está também concedida para poder compilar este programa com a biblioteca do &Qt;, tratando o &Qt; como uma biblioteca que acompanha normalmente o 'kernel' do sistema operativo, embora seja ou não esse o caso.</para> + +</chapter> + +<appendix id="installation"> +<title +>Instalar o &arts;</title> + +<para +>Para poder usar o &arts; você precisa obviamente de o ter instalado e a funcionar no seu sistema. Existem duas aproximações para o fazer, as quais estão descritas nas próximas secções. </para> + +<sect1 id="binary-install"> +<title +>Instalar uma Versão Binária Pré-Compilada</title> + +<para +>A forma mais rápida e simples de ter o &arts; a funcionar é instalando os pacotes binários pré-compilados para o seu sistema. A maioria das distribuições recentes do &Linux; incluem o &kde;, e se for o &kde; 2.0 ou posterior, irá incluir o &arts;. Se o &kde; não estiver incluído na sua instalação, poderá estar disponível para transferência a partir do fabricante do seu sistema operativo. Em alternativa, poderá está disponível a partir de terceiros. Certifique-se que você usa os pacotes que são compatíveis com a versão do seu sistema operativo. </para> + +<para +>Uma instalação básica do &kde; irá incluir o servidor de som, o que permitirá à maioria das aplicações tocarem som. Se quiser o conjunto completo de ferramentas e aplicações multimédia, você irá provavelmente necessitar de instalar os pacotes opcionais adicionais. </para> + +<para +>A desvantagem da utilização dos binários pré-compilados é que poderão não ser a versão mais recente do &arts;. Isto provavelmente será o caso se eles forem fornecidos num &CD-ROM;, dado que a rapidez do desenvolvimento do &arts; e do &kde; é tal que a disponibilização em &CD-ROM; não costuma acompanhar esse ritmo. Você poderá concluir também que, se tiver uma arquitectura ou uma distribuição menos comum, os pacotes binários pré-compilados poderão não estar disponíveis e, aí, você terá de usar o segundo método. </para> + +</sect1> + +<sect1 id="source-install"> +<title +>Compilar o Código</title> + +<para +>Embora ocupe algum tempo, a forma mais flexível de criar o &arts; é compilar você próprio o código-fonte. Isto garante-lhe que tem uma versão compilada de forma óptima para a sua configuração do sistema e permite-lhe ter a versão mais recente. </para> + +<para +>Você tem aqui duas opções -- tanto poderá instalar a versão estável mais recente que vem incluída com o &kde; ou poderá obter directamente a versão mais recente (mas possivelmente instável) a partir do repositório de <acronym +>CVS</acronym +> do &kde;. A maioria dos utilizadores que não estejam a programar para o &arts; deverão usar a versão estável. Você poderá obtê-la em <ulink url="ftp://ftp.kde.org" +>ftp://ftp.kde.org</ulink +> ou numa das suas réplicas. Se você estiver a programar activamente para o &arts; você irá querer usar provavelmente a versão no <acronym +>CVS</acronym +>. Se quiser usar o aRts sem o KDE, você poderá obter uma versão autónoma de desenvolvimento em <ulink url="http://space.twc.de/~stefan/kde/arts-snapshot-doc.html" +> http://space.twc.de/~stefan/kde/arts-snapshot-doc.html</ulink +>. </para> + +<para +>Tenha em atenção que, se tiver a compilar a partir do <acronym +>CVS</acronym +>, algumas das componentes do &arts; (&ie; as componentes de base que incluem o servidor de som) estão no módulo do <acronym +>CVS</acronym +> 'tdelibs', enquanto que os componentes adicionais (⪚ o <application +>artsbuilder</application +>) estão incluídos no 'tdemultimedia'. Isto poderá mudar no futuro. Você poderá também encontrar uma versão no módulo 'kmusic'; esta é a versão antiga (antes do &kde; 2.0) e que está agora obsoleta. </para> + +<para +>Os requisitos para compilar o &arts; são basicamente os mesmos que para compilar o &kde;. Os programas do 'configure' deverão detectar a configuração do seu sistema e indicar se estão a faltar alguns componentes obrigatórios. Certifique-se que tem um controlador de som a funcionar no seu sistema (seja ele o <acronym +>OSS</acronym +>/Free que vem com o 'kernel', o controlador <acronym +>OSS</acronym +> da 4Front Technologies, ou o <acronym +>ALSA</acronym +> com a emulação do <acronym +>OSS</acronym +>). </para> + +<para +>Poderá obter mais informações sobre como obter e instalar o &kde; (incluindo o &arts;) na <ulink url="http://www.kde.org/documentation/faq/index.html" +>&FAQ; do &kde;</ulink +>.</para> + +</sect1> + +</appendix> + +&digitalaudio; +&midiintro; +&arts-glossary; + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:nil +End: +--> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/mcop.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/mcop.docbook new file mode 100644 index 00000000000..58d1e3c2801 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/mcop.docbook @@ -0,0 +1,1974 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="mcop"> +<title +>&MCOP;: Modelo de Objectos e Transmissão</title> + +<sect1 id="mcop-overview"> + +<title +>Introdução</title> + +<para +>O &MCOP; é a norma que o &arts; usa para: </para> + +<itemizedlist> +<listitem> +<para +>A comunicação entre os objectos. </para> +</listitem> + +<listitem> +<para +>A transparência na rede. </para> +</listitem> + +<listitem> +<para +>A descrição das interfaces dos objectos. </para> +</listitem> + +<listitem> +<para +>A independência da linguagem. </para> +</listitem> +</itemizedlist> + +<para +>Um aspecto importante do &MCOP; é a <emphasis +>linguagem de descrição de interfaces</emphasis +>, ou &IDL;, na qual muitas das interfaces do &arts; e as <acronym +>API</acronym +>s estão definidas de forma independente da linguagem. </para> + +<para +>Para usar as interfaces de &IDL; a partir do C++, é compilada pelo compilador de &IDL; em código de C++. Quando você implementar uma interface, você irá derivar da classe de esqueleto que o compilador de &IDL; gerou. Quando usar uma interface, você irá fazer isso através de uma classe envolvente ('wrapper'). Desta forma, o &MCOP; pode usar um protocolo se o objecto com quem você está a falar não estiver local - você obtém assim a transparência de rede. </para> + +<para +>Este capítulo é suposto descrever as funcionalidades básicas do modelo de objectos que resulta da utilização do &MCOP;, o protocolo, como usar o &MCOP; no C++ (interface para a linguagem), e assim por diante. </para> + +</sect1> + +<sect1 id="interfaces"> + +<title +>As interfaces e a &IDL;</title> + +<para +>Muitos dos serviços fornecidos pelo &arts;, como os módulos e o servidor de som, são definidos com base em <acronym +>interfaces</acronym +>. As interfaces são especificadas num formato independente de linguagens: a &IDL;. </para> + +<para +>Isto permite que muitos dos detalhes de implementação, como o formato das sequências de dados multimédia, a transparência de rede e as dependências de linguagens de programação, sejam escondidos da especificação da interface. Uma ferramenta, o &mcopidl;, traduz a definição da interface para uma linguagem de programação específica (de momento, só o C++ é que é suportado). </para> + +<para +>A ferramenta gera uma classe-esqueleto com todo o código de 'cola' e a funcionalidade de base. Você pode derivar a partir dessa classe para implementar as funcionalidades que deseja. </para> + +<para +>A &IDL; usada pelo &arts; é semelhante à usada pelo <acronym +>CORBA</acronym +> e pelo <acronym +>DCOM</acronym +>. </para> + +<para +>Os ficheiros &IDL; podem conter: </para> + +<itemizedlist> +<listitem> +<para +>Directivas #include do estilo do C para outros ficheiros &IDL;. </para> +</listitem> + +<listitem> +<para +>Definições de tipos enumerados e estruturas, como no C/C++. </para> +</listitem> + +<listitem> +<para +>Definições de interfaces. </para> +</listitem> +</itemizedlist> + +<para +>Na &IDL;, as interfaces são definidas de forma muito semelhante à de uma classe de C++ ou de uma estrutura do C, ainda que com algumas restrições. Como no C++, as interfaces podem ser subclasses de outras interfaces através de herança. As definições de interfaces podem incluir três coisas: sequências, atributos e métodos. </para> + +<sect2 id="streams"> + +<title +>Sequências</title> + +<para +>As sequências ou canais definem os dados multimédia, um dos componentes mais importantes de um módulo. As sequências são definidas no seguinte formato: </para> + +<para +>[ async ] in|out [ multi ] <replaceable +>tipo</replaceable +> stream <replaceable +>nome</replaceable +> [ , <replaceable +>nome</replaceable +> ] ; </para> + +<para +>As sequências têm uma direcção definida na referência do módulo, tal como é indicado pelos qualificadores necessários 'in' ou 'out'. O argumento 'tipo' define o tipo dos dados, o qual poderá ser qualquer um dos tipos descritos posteriormente para os atributos (nem todos são suportados de momento). Muitos dos módulos usam o tipo de sequência 'audio', o qual é um nome alternativo para o 'float' (vírgula-flutuante) dado que é o formato interno dos dados usados para o áudio. Podem ser definidas várias sequências do mesmo tipo na mesma definição se usar nomes separados por vírgulas. </para> + +<para +>As sequências são síncronas por omissão, o que significa que elas são fluxos contínuos de dados a uma taxa constante, como o áudio <acronym +>PCM</acronym +>. O qualificador 'async' indica que é uma sequência assíncrona, a qual é usada para os fluxos de dados descontínuos. O exemplo mais comum de uma sequência assíncrona são as mensagens do &MIDI;. </para> + +<para +>A palavra-chave 'multi', que só é válida para as sequências de entrada, indica que a interface suporta um número variável de entradas. Isto é útil para implementar os dispositivos, como as mesas de mistura, que possam aceitar qualquer número de sequências de entrada. </para> + +</sect2> +<sect2 id="attributes"> + +<title +>Atributos</title> + +<para +>Os atributos são os dados associados com uma instância de uma interface. Estes são declarados como as variáveis-membro do C++, e podem usar qualquer um dos tipos primitivos 'boolean', 'byte', 'long', 'string', ou 'float'. Você também poderá usar os tipos 'struct' ou 'enum' definidos pelo utilizador, assim como as sequências de tamanho variável, usando a sintaxe sequence<tipo>. Os atributos podem ser marcados opcionalmente como 'readonly' (apenas para leitura). </para> + +</sect2> +<sect2 id="methods"> + +<title +>Métodos</title> + +<para +>Tal como no C++, os métodos podem ser definidos nas interfaces. Os parâmetros dos métodos estão restringidos aos mesmos tipos dos atributos. A palavra-chave 'oneway' indica um método que devolve valores imediatamente e é executado assincronamente. </para> + +</sect2> + +<sect2 id="standardinterfaces"> + +<title +>Interfaces-Padrão</title> + +<para +>Já estão definidas várias interfaces-padrão de módulos para você no &arts;, como o <interfacename +>StereoEffect</interfacename +> e o <interfacename +>SimpleSoundServer</interfacename +>. </para> + +</sect2> + +<sect2 id="example"> +<title +>Exemplo</title> + +<para +>Um exemplo simples de um módulo retirado do &arts; é o módulo de atraso constante, o qual se encontra no ficheiro <filename +>tdemultimedia/arts/modules/artsmodules.idl</filename +>. A definição da interface está indicada em baixo. </para> + +<programlisting +>interface Synth_CDELAY : SynthModule { + attribute float time; + in audio stream invalue; + out audio stream outvalue; +}; +</programlisting> + +<para +>Este módulo herda de <interfacename +>SynthModule</interfacename +>. Essa interface, definida no <filename +>artsflow.idl</filename +>, define os métodos-padrão que são implementados em todos os módulos de síntese de música. </para> + +<para +>O efeito CDELAY atrasa um canal estéreo pelo tempo indicado em 'time', o qual é um parâmetro de vírgula flutuante. A definição da interface tem um atributo do tipo 'float' para guardar o valor do atraso. Ele define duas sequências de áudio de entra e duas sequências de saída (o que é típico nos efeitos estéreo). Não são necessários mais métodos para além dos que ele já herdou. </para> + +</sect2> + +</sect1> + +<sect1 id="more-about-streams"> +<title +>Mais Acerca das Sequências</title> + +<para +>Esta secção cobre alguns tópicos adicionais relacionados com as sequências. </para> + +<sect2 id="stream-types"> +<title +>Tipos de Sequências</title> + +<para +>Existem vários requisitos para a forma como um módulo pode fazer a transmissão. Para ilustrar isto, considere estes exemplos: </para> + +<itemizedlist> +<listitem> +<para +>Aumentar o sinal por um factor de 2. </para> +</listitem> + +<listitem> +<para +>Efectuar uma conversão na frequência da amostra. </para> +</listitem> + +<listitem> +<para +>Descomprimir um sinal codificado em RLE. </para> +</listitem> + +<listitem> +<para +>Ler os eventos de &MIDI; do <filename class="devicefile" +>/dev/midi00</filename +> e introduzi-los numa sequência. </para> +</listitem +> +</itemizedlist> + +<para +>O primeiro caso é o mais simples: depois de receber 200 amostras da entrada, o módulo produz 200 amostras de resultado. Só produz resultados à saída quando obtiver algo à entrada. </para> + +<para +>O segundo caso produz números diferentes de amostras de resultado, quando são dadas 200 amostras de entrada. Isto depende de qual a conversão que é efectuada, mas o número é conhecido antecipadamente. </para> + +<para +>O terceiro caso é ainda pior. Para o resultado, você nem sequer consegue adivinhar quantos dados as 200 amostras de entrada irão gerar (provavelmente muito mais do que 200 amostras à saída, mas...). </para> + +<para +>O último caso é um módulo que se torna ele próprio activo e, de vez em quando, produz dados. </para> + +<para +>No &arts;s-0.3.4, só as sequências do primeiro tipo eram tratadas, e a maioria das coisas funcionavam. Isto é provavelmente o que você necessita para criar os módulos que processem áudio. O problema com os outros tipos mais complexos de transmissão é que eles são difíceis de programar e que você não precisa das suas funcionalidades na maior parte das vezes. É por isso que o processamento pode ser feito com dois tipos diferentes de sequências: síncronas e assíncronas. </para> + +<para +>As sequências síncronas têm estas características: </para> + +<itemizedlist> +<listitem> +<para +>Os módulos deverão ser capazes de calcular dados de qualquer dimensão, desde que sejam fornecidos em quantidade suficiente. </para> +</listitem> + +<listitem> +<para +>Todas as sequências têm a mesma taxa de amostragem. </para> +</listitem> + +<listitem> +<para +>A função <function +>calculateBlock()</function +> será chamada quando existirem dados suficientes disponíveis, e o módulo possa confiar nos ponteiros que referenciam os dados. </para> +</listitem +> + +<listitem> +<para +>Não existe nenhuma alocação e libertação de memória a ser feita. </para> +</listitem> +</itemizedlist> + +<para +>As sequências assíncronas, por outro lado, têm este comportamento: </para> + +<itemizedlist> +<listitem> +<para +>Os módulos poderão produzir dados algumas das vezes, ou com uma taxa de amostragem variável, ou apenas se eles tiverem dados de entrada de algum descritor de ficheiro. Eles não estão limitados pela regra <quote +>deve ser capaz de atender pedidos de qualquer tamanho</quote +>. </para> +</listitem> + +<listitem> +<para +>As sequências assíncronas de um módulo poderão ter taxas de amostragem totalmente diferentes. </para> +</listitem> + +<listitem> +<para +>Sequências de saída: existem funções explícitas para alocar pacotes, para enviá-los - e um mecanismo de pesquisa ('polling') opcional que lhe dirá quando deverá criar mais dados. </para> +</listitem> + +<listitem> +<para +>Sequências de entrada: você obtém uma chamada sempre que recebe um novo pacote - você terá de dizer quando estiver a processar todos os dados desse pacote, o que não deverá acontecer de uma vez (você poderá dizer isso mais tarde e, se toda a gente já processou o pacote, este será libertado/reutilizado). </para> +</listitem> +</itemizedlist> + +<para +>Quando você declara as sequências, você poderá usar a palavra-chave <quote +>async</quote +> para indicar que quer criar uma sequência assíncrona. Por isso, por exemplo, assuma que quer converter uma sequência assíncrona de 'bytes' para uma sequência síncrona de amostras. A sua interface poderia ser algo semelhante a isto: </para> + +<programlisting +>interface SequenciaBytesParaAudio : SynthModule { + async in byte stream entrada; // a sequência assíncrona de amostras de entrada + + out audio stream esquerda,direita; // a sequência síncrona de amostras de saída +}; +</programlisting> + +</sect2> + +<sect2 id="async-streams"> +<title +>Usar as Sequências Assíncronas</title> + +<para +>Imagine que decidiu criar um módulo para produzir som assincronamente. A sua interface seria algo parecido com o seguinte: </para> + +<programlisting +>interface UmModulo : SynthModule +{ + async out byte stream saida; +}; +</programlisting> + +<para +>Como é que você envia os dados? O primeiro método é chamado de <quote +>push delivery</quote +> (tradução livre: 'entrega por empurrão'). Com as sequências assíncronas, você envia os dados como pacotes. Isto significa que você envia pacotes individuais com 'bytes', como no exemplo acima. O processo actual é: alocar um pacote, preenchê-lo, enviá-lo. </para> + +<para +>Aqui está isso, em termos de código. Primeiro, é alocado um pacote: </para> + +<programlisting +>DataPacket<mcopbyte> *pacote = saida.allocPacket(100); +</programlisting> + +<para +>Aí, será preenchido: </para> + +<programlisting +>// converter de modo a que o 'fgets' fique contente com um ponteiro (char *) +char *dados = (char *)pacote->contents; + +// como pode ver, você pode encolher o tamanho do pacote depois da alocação, +// se quiser +if(fgets(dados,100,stdin)) + pacote->size = strlen(dados); +else + pacote->size = 0; +</programlisting> + +<para +>Agora, o mesmo é enviado: </para> + +<programlisting +>pacote->send(); +</programlisting> + +<para +>Isto é muito simples, mas se precisar de enviar os pacotes à mesma rapidez com que o destinatário os consegue processar, é necessária outra aproximação, a <quote +>pull delivery</quote +> ('entrega por puxão'). Você pede para enviar os pacotes tão rapidamente quanto o destinatário está pronto para processar. Você começa com uma determinada quantidade de pacotes que envia. À medida que o destinatário vai processando um pacote a seguir ao outro, você começa a preenchê-los de novo com dados novos, enviando-os mais uma vez. </para> + +<para +>Você inicia isso ao chamar o 'setPull'. Por exemplo: </para> + +<programlisting +>saida.setPull(8, 1024); +</programlisting> + +<para +>Isto significa que você deseja enviar os pacotes pela 'saida'. Você irá querer começar a enviar 8 pacotes de cada vez e, à medida que o destinatário processar alguns deles, você poderá querer preenchê-los de novo. </para> + +<para +>Aí, você precisa de implementar um método que preenche os pacotes, e que poderá se assemelhar ao seguinte: </para> + +<programlisting +>void request_saida(DataPacket<mcopbyte> *pacote) +{ + pacote->size = 1024; // não deverá ser maior que 1024 + for(int i = 0;i < 1024; i++) + pacote->contents[i] = (mcopbyte)'A'; + pacote->send(); +} +</programlisting> + +<para +>É tudo; quando não tiver mais dados, você poderá começar a enviar pacotes com tamanho nulo, o que irá parar a recepção. </para> + +<para +>Repare que é essencial dar ao método o nome exacto <methodname +>request_<replaceable +>nome-sequência</replaceable +></methodname +>. </para> + +<para +>Foi então discutido o envio dos dados. A recepção dos mesmos é muito mais simples. Suponha que você tem um filtro ParaMinusculas, que simplesmente converte todas as letras para minúsculas: </para> + +<programlisting +>interface ParaMinusculas { + async in byte stream entrada; + async out byte stream saida; +}; +</programlisting> + +<para +>Isto é mesmo simples de implementar; aqui está a implementação completa: </para> + +<programlisting +>class ParaMinusculas_impl : public ParaMinusculas_skel { +public: + void process_entrada(DataPacket<mcopbyte> *pacote_entrada) + { + DataPacket<mcopbyte> *pacote_saida = saida.allocPacket(pacote_entrada->size); + + // convert to lowercase letters + char *texto_entrada = (char *)pacote_entrada->contents; + char *texto_saida = (char *)pacote_entrada->contents; + + for(int i=0;i<pacote_entrada->size;i++) + texto_saida[i] = tolower(texto_entrada[i]); + + pacote_entrada->processed(); + pacote_saida->send(); + } +}; + +REGISTER_IMPLEMENTATION(ParaMinusculas_impl); +</programlisting> + +<para +>Mais uma vez, é importante dar o nome <methodname +>process_<replaceable +>nome-sequencia</replaceable +></methodname +> ao método. </para> + +<para +>Como pode ver, para cada pacote que chega, você obtém uma chamada a uma função ( a <function +>process_entrada</function +> no caso em questão). Você precisa de chamar o método <methodname +>processed()</methodname +> de um pacote para indicar que acabou de o processar. </para> + +<para +>Aqui está uma sugestão de implementação: se o processamento levar mais tempo (&ie; se precisar de esperar pelo resultado da placa de som ou algo do género), não invoque o 'processed' logo, mas armazene o pacote de dados em si e invoque o 'processed' apenas quando você processar de facto esse pacote. Desta forma, os emissores têm uma hipótese de saber quanto tempo leva mesmo a efectuar o seu trabalho. </para> + +<para +>Dado que a sincronização não é tão boa com as sequências assíncronas, você deverá usar as sequências síncronas sempre que possível e as assíncronas, só quando for necessário. </para> + +</sect2> + +<sect2 id="default-streams"> +<title +>Sequências por Omissão</title> + +<para +>Imagine que tem 2 objectos, como por exemplo um ProdutorAudio e um ConsumidorAudio. O ProdutorAudio tem uma sequência de saída e o ConsumidorAudio tem uma de entrada. De cada vez que os tentar ligar, você irá usar estas duas sequências. A primeira utilização da predefinição é permitir-lhe fazer a ligação sem indicar os portos nesse caso. </para> + +<para +>Agora imagine que os dois objectos poderão lidar com o estéreo, e cada um possa ter um porto <quote +>left</quote +> (esquerdo) e <quote +>right</quote +> (direito). Você gostaria à mesma de os ligar de forma tão simples como anteriormente. Mas como é que o sistema de ligações saberia que porto de saída deveria ligar a que porto de entrada? Não tem nenhuma forma de mapear correctamente as sequências. A utilização de portos predefinidos poderá então ser adoptada para indicar várias sequências, com uma dada ordem. Desta forma, quando você ligar um objecto com 2 portos predefinidos a outro objecto com 2 portos predefinidos de entrada, não terá de indicar os portos e, nesse caso, o mapeamento será feito correctamente. </para> + +<para +>Obviamente, isto não está limitado ao estéreo. Pode-se tornar qualquer número de sequências como predefinidas se necessário, e a função 'connect' irá verificar se o número de predefinições para os dois objectos correspondem (na direcção necessária), se você não indicar os portos a usar. </para> + +<para +>A sintaxe é a seguinte: na &IDL;, você poderá usar a palavra-chave 'default' na declaração da sequência ou numa única linha. Por exemplo: </para> + +<programlisting +>interface MisturaDoisEmUm { + default in audio stream entrada1, entrada2; + out audio stream saida; +}; +</programlisting> + +<para +>Neste exemplo, o objecto irá esperar que os seus dois portos de entrada estejam ligados por omissão. A ordem é a indicada na linha 'default', por isso, um objecto do tipo: </para> + +<programlisting +>interface GeradorRuidoDuplo { + out audio stream bzzt, cuic; + default cuic, bzzt; +}; +</programlisting> + +<para +>Fará as ligações do <quote +>cuic</quote +> à <quote +>entrada1</quote +> e do <quote +>bzzt</quote +> à <quote +>entrada2</quote +> automaticamente. Repare que, dado que só há uma saída para o misturador, será tornada predefinida nesse caso (ver em baixo). A sintaxe usada no gerador de ruído é útil para declarar uma ordem diferente da declaração, ou seleccionando apenas alguns portos como predefinidos. As direcções dos portos nesta linha serão pesquisados pelo &mcopidl;, por isso não os indique. Você até poderá misturar os portos de entrada e de saída numa linha destas, onde só a ordem é que é relevante. </para> + +<para +>Existem algumas regras que são seguidas ao usar a herança: </para> + +<itemizedlist> +<listitem> +<para +>Se for indicada uma lista 'default' na &IDL;, então use-a. Os portos-pai podem ser colocados também nesta lista, quer fossem predefinidos no 'pai' ou não. </para> +</listitem> + +<listitem> +<para +>Caso contrário, herde as predefinições do 'pai'. A ordem é do tipo 'pai1 predefinicao1, pai1 predefinicao2..., pai2 predefinicao1... Se existir um ascendente comum em dois ramos-pai, é feita uma junção do tipo <quote +>virtual public</quote +> na primeira ocorrência da predefinição na lista. </para> +</listitem> + +<listitem> +<para +>Se não existir à mesma nenhuma predefinição e existir uma sequência simples numa dada direcção, use-a como predefinida nessa direcção. </para> +</listitem> +</itemizedlist> + +</sect2> + +</sect1> +<sect1 id="attribute-change-notify"> +<title +>Notificações de mudança dos atributos</title> + +<!-- TODO: This should be embedded better into the context - I mean: the + context should be written ;-). --> + +<para +>As notificações de alteração de atributos são uma forma de saber quando é que um atributo foi alterado. Eles são ligeiramente compatíveis com os 'signals' e 'slots' do &Qt; e do Gtk. Por exemplo, se você tiver um elemento gráfico, como uma barra deslizante, que configura um número entre 0 e 100, você poderá ter normalmente um objecto que faça algo com esse número (por exemplo, poderá controlar o volume de um sinal de áudio). Por isso, você gostaria que, de cada vez que movesse a barra, o objecto que ajustasse o volume fosse notificado. Uma ligação entre um emissor e um receptor. </para> + +<para +>O &MCOP; lida com isso, sendo capaz de oferecer notificações de cada vez que os atributos são alterados. Tudo o que for declarado como <quote +>atributo</quote +> na &IDL;, pode emitir essas notificações de alterações, e devê-lo-á fazer, sempre que for modificado. Tudo o que for declarado como <quote +>atributo</quote +> poderá também receber essas notificações de alteração. Por isso, se por exemplo tiver duas interfaces de &IDL;, como as seguintes: </para> + +<programlisting +>interface BarraDeslizante { + attribute long min,max; + attribute long posicao; + }; + interface ControloVolume : Arts::StereoEffect { + attribute long volume; // 0..100 + }; +</programlisting> + +<para +>Você podê-las-á ligar com as notificações de alteração. Isto funciona usando a operação normal de 'connect' do sistema de fluxo. Neste caso, o código de C++ para ligar dois objectos deverá ser semelhante ao seguinte: </para> + +<programlisting +>#include <connect.h> +using namespace Arts; +[...] +connect(barra,"posicao_changed",controlo_Volume,"volume"); +</programlisting> + +<para +>Como pode ver, cada atributo oferece duas sequências diferentes, uma para enviar as notificações de alteração, chamada de <function +><replaceable +>nome-atributo</replaceable +>_changed</function +>, e outra para receber as notificações de alteração, chamada <function +>nome-atributo</function +>. </para> + +<para +>É importante saber que as notificações de alteração e as sequências assíncronas são compatíveis. São também transparentes na rede. Por isso, você consegue ligar uma notificação de alteração de um atributo 'float' de um elemento &GUI; a uma sequência assíncrona de um módulo de síntese a correr noutro computador. Isto, obviamente, implica que as notificações de alteração <emphasis +>não sejam síncronas</emphasis +>, o que significa que, depois de ter enviado a notificação de alteração, poderá levar algum tempo até que esta seja de facto recebida. </para> + +<sect2 id="sending-change-notifications"> + +<title +>Enviar as notificações de alterações</title> + +<para +>Ao implementar objectos que tenham atributos, você precisa de enviar as notificações de alteração sempre que um dado atributo muda. O código para o fazer é semelhante ao seguinte: </para> + +<programlisting +>void KPoti_impl::valor(float novoValor) + { + if(novoValor != _valor) + { + _valor = novoValor; + valor_changed(novoValor); // <- envia a notificação de alteração + } + } +</programlisting> + +<para +>É bastante recomendado que use código deste género para todos os objectos que implementar, de modo a que as notificações de alterações possam ser usadas pelas outras pessoas. Você deverá, contudo, evitar o envio das notificações com demasiada frequências, por isso, se estiver a fazer processamento de sinal, é provavelmente melhor que você mantenha um registo de quando enviou a sua última notificação, para que não envie uma com cada uma das amostras que processar. </para> + +</sect2> + +<sect2 id="change-notifications-apps"> +<title +>Aplicações para as notificações de alteração</title> + +<para +>Será especialmente útil usar as notificações de alteração em conjunto com os osciloscópios (as coisas que visualizam os dados de áudio, por exemplo), os elementos gráficos, elementos de controlo e na monitorização. O código que usa isto está em <filename class="directory" +>tdelibs/arts/tests</filename +> e na implementação experimental do 'artsgui', que poderá encontrar em <filename class="directory" +>tdemultimedia/arts/gui</filename +>. </para> + +<!-- TODO: can I markup links into the source code - if yes, how? --> + +<!-- LW: Linking into the source is problematic - we can't assume people are +reading this on a machine with the sources available, or that they aren't +reading it from a website. We're working on it! --> + +</sect2> +</sect1> + +<sect1 id="the-mcoprc-file"> + +<title +>O ficheiro <literal role="extension" +>.mcoprc</literal +></title> + +<para +>O ficheiro <literal role="extension" +>.mcoprc</literal +> (na pasta pessoal de cada utilizador) poderá ser usado para configurar o &MCOP; em alguns aspectos. De momento, é possível o seguinte: </para> + +<variablelist> + +<varlistentry> +<term +>GlobalComm</term> +<listitem> +<para +>O nome de uma interface a usar para a comunicação global. A comunicação global é usada para procurar os outros objectos e obter o 'cookie' secreto. Vários clientes/servidores de &MCOP; que deverão ser capazes de falar entre si precisam de ter um objecto 'GlobalComm' que seja capaz de partilhar informações entre eles. De momento, os valores possíveis são o <quote +>Arts::TmpGlobalComm</quote +> para comunicar através da pasta <filename class="directory" +>/tmp/mcop-<replaceable +>utilizador</replaceable +></filename +> (que irá funcionar apenas no computador local) ou o <quote +>Arts::X11GlobalComm</quote +> para comunicar através das propriedades da janela de topo do servidor X11. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>TraderPath</term> + +<listitem> +<para +>Indica onde procurar pela informação do mediador. Você poderá indicar aqui mais do que uma pasta, separando as pastas com vírgulas, como no exemplo </para> +</listitem> + +</varlistentry> + +<varlistentry> +<term +>ExtensionPath</term> + +<listitem> +<para +>Indica a partir de que pastas é que as extensões (na forma de bibliotecas dinâmicas) são carregadas. Podem ser indicados vários valores, separados por vírgulas. </para> +</listitem> + +</varlistentry> +</variablelist> + +<para +>Um exemplo que usa tudo isso é o seguinte: </para> + +<programlisting +># Ficheiro $HOME/.mcoprc +GlobalComm=Arts::X11GlobalComm + +# se você é um programador, será útil adicionar uma pasta na sua área +# para que a localização do(a) mediador/extensão sejam capazes de adicionar +# componentes sem os instalar +TraderPath="/opt/kde2/lib/mcop","/home/ze/mcop_desenvolvimento/mcop" +ExtensionPath="/opt/kde2/lib","/home/ze/mcop_desenvolvimento/lib" +</programlisting> + +</sect1> + +<sect1 id="mcop-for-corba-users"> +<title +>O &MCOP; para os Utilizadores de <acronym +>CORBA</acronym +></title> + +<para +>Se já usou o <acronym +>CORBA</acronym +> antes, irá concluir que o &MCOP; é muito parecido, de facto. De facto, o &arts;, antes da versão 0.4 usava o <acronym +>CORBA</acronym +>. </para> + +<para +>A ideia básica do <acronym +>CORBA</acronym +> é a mesma: você implementa os objectos (componentes). Se usar as funcionalidades do &MCOP;, os seus objectos não estão só disponíveis como classes normais do mesmo processo (através das técnicas normais do C++) - eles passam a estar disponíveis de forma transparente para os servidores remotos. Para isto funcionar, a primeira coisa que precisa de fazer é indicar a interface dos seus objectos num ficheiro &IDL; - tal como na &IDL; do <acronym +>CORBA</acronym +>. Existem apenas algumas diferenças. </para> + +<sect2 id="corba-missing"> +<title +>Funcionalidades do <acronym +>CORBA</acronym +> que Faltam no &MCOP;</title> + +<para +>No &MCOP; não existem parâmetros <quote +>in</quote +> e <quote +>out</quote +> nas invocações dos métodos. Os parâmetros são sempre de entrada e o código devolvido é sempre de saída, o que significa que a interface: </para> + +<programlisting +>// idl de CORBA +interface Conta { + void depositar( in long quantia ); + void levantar( in long quantia ); + long saldo(); +}; +</programlisting> + +<para +>é escrito como </para> + +<programlisting +>// idl de MCOP +interface Conta { + void depositar( long quantia ); + void levantar( long quantia ); + long saldo(); +}; +</programlisting> + +<para +>no &MCOP;. </para> + +<para +>Não existe o suporte de excepções. O &MCOP; não tem excepções - ele usa algo de diferente para o tratamento de erros. </para> + +<para +>Não existem tipos 'union' nem 'typedef's. Não se sabe se é uma falha de facto, algo que uma pessoa necessitasse desesperadamente para sobreviver. </para> + +<para +>Não existe suporte para passar referências a interfaces ou objectos </para> + +</sect2> + +<sect2 id="corba-different"> +<title +>Funcionalidades do <acronym +>CORBA</acronym +> que São Diferentes no &MCOP;</title> + +<para +>Você declara as sequências como <quote +>sequence<replaceable +>tipo</replaceable +></quote +> no &MCOP;. Não existe necessidade de um 'typedef'. Por exemplo, em vez de: </para> + +<programlisting +>// CORBA idl +struct Linha { + long x1,y1,x2,y2; +}; +typedef sequence<Linha> Linhas; +interface Desenhador { + void desenhar(in Linhas linhas); +}; +</programlisting> + +<para +>você iria descrever </para> + +<programlisting +>// IDL de MCOP +struct Linha { + long x1,y1,x2,y2; +}; +interface Desenhador { + void desenhar(sequence<Linha> linhas); +}; +</programlisting> + +</sect2> + +<sect2 id="no-in-corba"> +<title +>Funcionalidades do &MCOP; Que Não Estão no <acronym +>CORBA</acronym +></title> + +<para +>Você pode declarar as sequências que serão então avaliadas pela plataforma do &arts;. As sequências são declaradas de forma semelhante aos atributos. Por exemplo: </para> + +<programlisting +>// MCOP idl +interface Synth_ADICIONAR : SynthModule { + in audio stream sinal1,sinal2; + out audio stream saida; +}; +</programlisting> + +<para +>Isto diz que o seu objecto irá aceitar duas sequências síncronas de áudio chamadas 'sinal1' e 'sinal2'. Por síncronas significa que são sequências que distribuem 'x' amostras por segundo (ou por outro período), de modo a que o escalonador garanta que lhe fornecerá uma quantidade balanceada de dados de entrada (⪚ existem 200 amostras de 'sinal1' para 200 amostras de 'sinal2'). Você garante que, se o seu objectivo for chamado com essas 200 amostras de 'sinal1' e 'sinal2', será capaz de produzir exactamente 200 amostras de 'saida'. </para> + +</sect2> + +<sect2 id="mcop-binding"> +<title +>A Interface para a Linguagem C++ do &MCOP;</title> + +<para +>Isto difere do <acronym +>CORBA</acronym +> principalmente: </para> + +<itemizedlist> +<listitem> +<para +>As cadeias de caracteres usam a classe de C++ do <acronym +>STL</acronym +> <classname +>string</classname +>. Quando é armazenado nas sequências, elas são armazenadas <quote +>tal-e-qual</quote +>, o que significa que são consideradas como sendo um tipo primitivo. Deste modo, elas precisam de ser copiadas. </para> +</listitem> + +<listitem> +<para +>os 'long's são 'long's normais (contando que são de 32 bits). </para> +</listitem> + +<listitem> +<para +>As sequências usam a classe de C++ do <acronym +>STL</acronym +> <classname +>vector</classname +>. </para> +</listitem> + +<listitem> +<para +>As estruturas são todas derivadas da classe do &MCOP; <classname +>Type</classname +>, e são geradas no compilador de &IDL; do &MCOP;. Quando forem armazenadas em sequências, elas não serão guardadas <quote +>tal-e-qual</quote +> , mas sim como referências porque, caso contrário, iriam ocorrer várias cópias. </para> +</listitem> +</itemizedlist> +</sect2> + +<sect2 id="implementing-objects"> +<title +>Implementar os Objectos do &MCOP;</title> + +<para +>Depois de passar as interfaces pelo compilador de &IDL;, você precisa de derivar da classe <classname +>_skel</classname +>. Por exemplo, assuma que definiu a sua interface da seguinte forma: </para> + +<programlisting +>// IDL do MCOP: ola.idl +interface Ola { + void Ola(string s); + string concatenar(string s1, string s2); + long somar2(long a, long b); +}; +</programlisting> + +<para +>Você pode passar isso pelo compilador de &IDL;, invocando o comando <userinput +><command +>mcopidl</command +> <parameter +>ola.idl</parameter +></userinput +>, o que por sua vez irá gerar o <filename +>ola.cc</filename +> e o <filename +>ola.h</filename +>. Para o implementar, você precisa de definir uma classe de C++ que herde do esqueleto: </para> + +<programlisting +>// ficheiro de inclusão de C++ - inclua o ola.h algures +class Ola_impl : virtual public Ola_skel { +public: + void ola(const string& s); + string concatenar(const string& s1, const string& s2); + long somar2(long a, long b); +}; +</programlisting> + +<para +>Finalmente, você terá de implementar os métodos como C++ normal </para> + +<programlisting +>// ficheiro de implementação de C++ + +// como pode ver, as 'string's são passadas como referências de 'const string' +void Ola_impl::ola(const string& s) +{ + printf("Ola '%s'!\n",s.c_str()); +} + +// quando têm um valor a devolver são passadas como cadeias de caracteres normais +string Ola_impl::concatenar(const string& s1, const string& s2) +{ + return s1+s2; +} + +long Ola_impl::somar2(long a, long b) +{ + return a+b; +} +</programlisting> + +<para +>Logo que faça isso, você terá um objecto que poderá comunicar usando o &MCOP;. Basta criar um (usando as funcionalidades normais do C++ para criar um objecto): </para> + +<programlisting +>Servidor do Ola_impl; +</programlisting> + +<para +>E assim que dê a alguém a referência </para> + +<programlisting +>string referencia = servidor._toString(); + printf("%s\n",referencia.c_str()); +</programlisting> + +<para +>e ir à ciclo de inactividade do &MCOP; </para> + +<programlisting +>Dispatcher::the()->run(); +</programlisting> + +<para +>As pessoas podem aceder à coisa usando </para> + +<programlisting +>// este código poderá correr em qualquer lado - não necessariamente no mesmo +// processo (poderá também correr num computador/arquitectura diferentes) + + Ola *h = Ola::_fromString([a referência do objecto impressa acima]); +</programlisting> + +<para +>e invocar os métodos: </para> + +<programlisting +>if(h) + h->ola("teste"); + else + printf("O acesso falhou?\n"); +</programlisting> + +</sect2> +</sect1> + +<sect1 id="mcop-security"> +<title +>Considerações de Segurança do &MCOP;</title> + +<para +>Dado que os servidores de &MCOP; irão atender os pedidos num porto de <acronym +>TCP</acronym +>, potencialmente toda a gente (se você estiver na Internet) poderá tentar ligar-se aos serviços do &MCOP;. Por isso, é importante autenticar os clientes. O &MCOP; usa o protocolo 'md5-auth'. </para> + +<para +>O protocolo 'md5-auth' faz o seguinte para garantir que só os clientes seleccionados (de confiança) se poderão ligar a um servidor: </para> + +<itemizedlist> +<listitem> +<para +>Ele assume que você dá a todos os clientes um 'cookie' secreto. </para> +</listitem> + +<listitem> +<para +>De cada vez que um cliente se liga, ele verifica se o cliente conhece esse 'cookie' secreto, sem o transferir de facto (nem sequer de forma a que alguém que esteja a escutar o tráfego de rede o possa descobrir). </para> +</listitem> + +</itemizedlist> + +<para +>Para dar a cada cliente esse 'cookie' secreto, o &MCOP; irá (normalmente) colocá-lo na pasta <filename class="directory" +>mcop</filename +> (em <filename class="directory" +>/tmp/mcop-<envar +>USER</envar +>/secret-cookie</filename +>). Claro, você podê-lo-á copiar para outros computadores. Contudo, se o fizer, use um mecanismo de transferência seguro, como o <command +>scp</command +> (do <application +>ssh</application +>). </para> + +<para +>A autenticação dos clientes usa os seguintes passos: </para> + +<procedure> +<step> +<para +>[SERVIDOR] gera um 'cookie' novo (aleatório) R </para> +</step> + +<step> +<para +>[SERVIDOR] envia-o para o cliente </para> +</step> + +<step> +<para +>[CLIENTE] lê o "cookie secreto" S de um ficheiro </para> +</step> + +<step> +<para +>[CLIENTE] baralha os 'cookies' R e S para um 'cookie' baralhado M usando o algoritmo MD5 </para> +</step> + +<step> +<para +>[CLIENTE] envia o M para o servidor </para> +</step> + +<step> +<para +>[SERVIDOR] verifica que, ao baralhar o R e o S dará o mesmo resultado que o 'cookie' M recebido do cliente. Em caso afirmativo, a autenticação foi bem-sucedida. </para> +</step> + +</procedure> + +<para +>Este algoritmo deverá ser seguro, atendendo a que </para> + +<orderedlist> +<listitem> +<para +>Os 'cookies' secretos e os aleatórios são <quote +>aleatórios quanto baste</quote +> e </para> +</listitem> + +<listitem> +<para +>O algoritmo de dispersão do MD5 não permite descobrir o <quote +>texto original</quote +>, que é o 'cookie' secreto S e o 'cookie' aleatório R (o qual é conhecido, de qualquer forma), a partir do 'cookie' baralhado M. </para> +</listitem> +</orderedlist> + +<para +>O protocolo &MCOP; irá começar todas as ligações novas com um processo de autenticação. Basicamente, assemelha-se ao seguinte: </para> + +<procedure> + +<step> +<para +>O servidor envia uma mensagem ServerHello que descreve os protocolos de autenticação conhecidos. </para> +</step> + +<step> +<para +>O cliente envia uma mensagem ClientHello que inclui a informação de autenticação. </para> +</step> + +<step> +<para +>O servidor envia uma mensagem AuthAccept. </para> +</step> +</procedure> + +<para +>Para verificar se a segurança funciona de facto, deverá ver como é que as mensagens se processam nas ligações não-autenticadas: </para> + +<itemizedlist> +<listitem> +<para +>Antes de a autenticação ser bem sucedida, o servidor não irá receber outras mensagens da ligação. Em vez disso, se o servidor por exemplo estiver à espera de uma mensagem <quote +>ClientHello</quote +> e obtiver uma mensagem de 'mcopInvocation', irá quebrar a ligação. </para> +</listitem> + +<listitem> +<para +>Se o cliente não enviar uma mensagem de &MCOP; válida de todo (sem o código especial do &MCOP; no cabeçalho da mensagem) na fase de autenticação, mas sim outra coisa qualquer, a ligação é quebrada. </para> +</listitem> + +<listitem> +<para +>Se o cliente tentar enviar uma mensagem mesmo muito grande (> 4096 bytes na fase de autenticação, o tamanho da mensagem é truncado para 0 bytes, o que fará com que não seja aceite para a autenticação). Isto é para evitar que os clientes não-autenticados enviem mensagens de ⪚ 100 megabytes, o que faria com que fosse recebida e com que o servidor estoirasse com falta de memória. </para> +</listitem> + +<listitem> +<para +>Se o cliente enviar uma mensagem ClientHello corrompida (uma, onde a descodificação falhe), a ligação é mais uma vez quebrada. </para> +</listitem> + +<listitem> +<para +>Se o cliente não enviar nada de nada, então ocorrerá a expiração de um tempo-limite (ainda por implementar). </para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="mcop-protocol"> +<title +>Especificação do Protocolo &MCOP;</title> + +<sect2 id="mcop-protocol-intro"> +<title +>Introdução</title> + +<para +>Tem semelhanças conceptuais ao <acronym +>CORBA</acronym +>, mas pretende extendê-lo de todas as formas necessárias para as operações multimédia em tempo-real. </para> + +<para +>Oferece um modelo de objectos multimédia, o qual poderá ser usado para: a comunicação entre os componentes num espaço de endereçamento (um processo) e entre componentes que existam em tarefas, processos ou mesmo máquinas diferentes. </para> + +<para +>Tudo junto, será desenhado para uma performance extremamente alta (de modo a que tudo seja optimizado para ser extremamente rápido), o que é adequado para as aplicações multimédia bastante comunicativas. Por exemplo, a transmissão de vídeos é uma das aplicações do &MCOP;, onde a maioria das implementações de <acronym +>CORBA</acronym +> 'cairiam de joelhos'. </para> + +<para +>As definições das interfaces conseguem lidar com as seguintes coisas nativamente: </para> + +<itemizedlist> +<listitem> +<para +>Sequências contínuas de dados (como os dados de áudio). </para> +</listitem> + +<listitem> +<para +>Sequências de dados de eventos (como os eventos do &MIDI;). </para> +</listitem> + +<listitem> +<para +>Contagem de referências real. </para> +</listitem> +</itemizedlist> + +<para +>e os truques mais importantes do <acronym +>CORBA</acronym +>, como </para> + +<itemizedlist> +<listitem> +<para +>As invocações síncronas de métodos. </para> +</listitem> + +<listitem> +<para +>As invocações de métodos assíncronas. </para> +</listitem> + +<listitem> +<para +>A construção de tipos de dados definidos pelo utilizador. </para> +</listitem> + +<listitem> +<para +>Herança múltipla. </para> +</listitem> + +<listitem> +<para +>A passagem de referências de objectos. </para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="mcop-protocol-marshalling"> +<title +>A Codificação das Mensagens do &MCOP;</title> + +<para +>Objectivos/ideias de desenho: </para> + +<itemizedlist> + +<listitem> +<para +>A codificação deverá ser simples de implementar. </para> +</listitem> + +<listitem> +<para +>A descodificação necessita que o destinatário saiba qual é o tipo que ele deseja descodificar. </para> +</listitem> + +<listitem> +<para +>O destinatário está à espera de usar toda a informação - por isso, só são ignorados os dados no protocolo ao nível em que: </para> + +<itemizedlist> +<listitem> +<para +>Se você souber que vai receber um bloco de 'bytes', não precisa de olhar para cada 'byte', à procura de um marcador de fim. </para> +</listitem> + +<listitem> +<para +>Se você souber que vai receber uma cadeia de caracteres, não precisa de a ler até encontrar o 'byte' zero para descobrir o seu tamanho, contudo, </para> +</listitem> + +<listitem> +<para +>Se você souber que vai receber uma sequência de cadeias de caracteres, você precisa de saber o tamanho de cada uma delas para descobrir o fim da sequência, dado que as cadeias de caracteres têm tamanho variável. Mas se você usar as cadeias de caracteres para algo útil, você terá de o fazer à mesma, por isso não se perde nada. </para> +</listitem> +</itemizedlist> + +</listitem> + +<listitem> +<para +>O mínimo de sobrecarga possível. </para> +</listitem> +</itemizedlist> + +<!-- TODO: Make this a table --> + +<para +>A codificação dos diferentes tipos é mostrada na tabela em baixo: </para> + +<informaltable> +<tgroup cols="3"> +<thead> +<row> +<entry +>Tipo</entry> +<entry +>Processo de Codificação</entry> +<entry +>Resultado</entry> +</row> +</thead> + +<tbody> +<row> +<entry +><type +>void</type +></entry> +<entry +>Os tipos <type +>void</type +> são codificados, omitindo-os, de modo a que e não seja nada escrito no canal.</entry> +<entry +></entry> +</row> + +<row> +<entry +><type +>long</type +></entry> +<entry +>é codificado como 4 'bytes', em que o 'byte' mais significativo vem primeiro, de modo a que o número 10001025 (correspondente a 0x989a81) será codificado como:</entry> +<entry +><literal +>0x00 0x98 0x9a 0x81</literal +></entry> +</row> + +<row> +<entry +><type +>enums</type +></entry> +<entry +><para +>são codificados como <type +>long</type +>s</para +></entry> +<entry +></entry> +</row> + +<row> +<entry +><type +>byte</type +></entry> +<entry +><para +>é codificado como um único 'byte', de modo a que o 'byte' 0x42 será codificado como:</para +></entry> +<entry +><literal +>0x42</literal +></entry> +</row> + +<row> +<entry +><type +>string</type +></entry> +<entry +><para +>é codificado como um <type +>long</type +>, contendo o tamanho da cadeia de caracteres seguinte, e pela sequência de caracteres propriamente dita, terminando com um 'byte' a zeros (que está incluído na contagem do tamanho).</para> +<important> +<para +>inclui o 'byte' 0 final na contagem do tamanho!</para> +</important> +<para +>O <quote +>ola</quote +> seria codificado da seguinte forma:</para +></entry> +<entry +><literal +>0x00 0x00 0x00 0x04 0x6f 0x6c 0x60 0x00</literal +></entry> +</row> + +<row> +<entry +><type +>boolean</type +></entry> +<entry +><para +>é codificado como um 'byte', contendo 0 se for <returnvalue +>false</returnvalue +> (falso) ou 1 se for <returnvalue +>true</returnvalue +> (verdadeiro), de modo a que o valor booleano <returnvalue +>true</returnvalue +> é codificado como:</para +></entry> +<entry +><literal +>0x01</literal +></entry> +</row> + +<row> +<entry +><type +>float</type +></entry> +<entry +><para +>é codificado na representação de 4 'bytes' do IEEE754 - a documentação detalhada de como o IEEE funciona estão aqui: <ulink url="http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html" +>http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html</ulink +> e aqui: <ulink url="http://java.sun.com/docs/books/vmspec/2nd-edition/html/Overview.doc.html" +>http://java.sun.com/docs/books/vmspec/2nd-edition/html/Overview.doc.html</ulink +>. Deste modo, o valor 2,15 seria codificado como:</para +></entry> +<entry +><literal +>0x9a 0x99 0x09 0x40</literal +></entry> +</row> + +<row> +<entry +><type +>'struct'</type +></entry> +<entry +><para +>Uma estrutura é codificada com base no seu conteúdo. Não existem prefixos ou sufixos adicionais, por isso a estrutura </para> +<programlisting +>struct teste { + string nome; // que é igual a "ola" + long valor; // que é igual a 10001025 (0x989a81) +}; +</programlisting> +<para +>seria codificada como</para +></entry> +<entry> +<literallayout +>0x00 0x00 0x00 0x04 0x6f 0x6c 0x60 0x00 +0x00 0x98 0x9a 0x81 +</literallayout +></entry> +</row> + +<row> +<entry +><type +>sequência</type +></entry> +<entry +><para +>uma sequência é codificada através da listagem do número de elementos que se seguem e da descodificação dos elementos, um a um.</para> +<para +>Por isso uma sequência de 3 'longs' 'a', with a[0] = 0x12345678, a[1] = 0x01 e a[2] = 0x42 seria codificada como:</para +></entry> +<entry> +<literallayout +>0x00 0x00 0x00 0x03 0x12 0x34 0x56 0x78 +0x00 0x00 0x00 0x01 0x00 0x00 0x00 0x42 +</literallayout> +</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para +>Se você precisar de fazer referência a um tipo, todos os tipos primitivos são referidos pelos nomes indicados acima. As estruturas e os enumerados têm nomes próprios (como Header). As sequências são referidas como um *<replaceable +>tipo normal</replaceable +>, de modo que uma sequência de 'longs' é um <quote +>*long</quote +> e uma sequência de estruturas Header é um <quote +>*Header</quote +>. </para> + +</sect2> + +<sect2 id="mcop-protocol-messages"> +<title +>Mensagens</title> + +<para +>O formato do cabeçalho das mensagens do &MCOP; está definido pela estrutura seguinte: </para> + +<programlisting +>struct Header { + long magic; // o valor 0x4d434f50, que é codificado como MCOP + long messageLength; + long messageType; +}; +</programlisting> + +<para +>Os valores possíveis de messageTypes são, de momento </para> + +<programlisting +>mcopServerHello = 1 + mcopClientHello = 2 + mcopAuthAccept = 3 + mcopInvocation = 4 + mcopReturn = 5 + mcopOnewayInvocation = 6 +</programlisting> + +<para +>Algumas notas acerca das mensagens do &MCOP;: </para> + + +<itemizedlist> +<listitem> +<para +>Todas as mensagens começam com uma estrutura Header. </para> +</listitem> + +<listitem> +<para +>Alguns dos tipos de mensagens deverão ser ignorados pelo servidor, enquanto a autenticação não estiver completa. </para> +</listitem> + +<listitem> +<para +>Depois de receber o cabeçalho, o tratamento do protocolo (ligação) poderá receber a mensagem por completo, sem olhar para o seu conteúdo. </para> +</listitem> +</itemizedlist> + +<para +>O 'messageLength' no cabeçalho é, obviamente em alguns casos, redundante, o que significa que esta aproximação não é minimalista no que respeita ao número de 'bytes'. </para> + +<para +>Contudo, conduz a uma implementação simples (e rápida) do processamento não-bloqueante de mensagens. Com a ajuda do cabeçalho, as mensagens poderão ser recebidas pelas classes de tratamento do protocolo em segundo plano (não-bloqueante), se existirem demasiadas ligações ao servidor, todas elas poderão ser servidas em paralelo. Você não precisa de olhar para o conteúdo da mensagem para a receber (e para determinar que terminou), basta olhar para o cabeçalho, por isso o código para isso é relativamente simples. </para> + +<para +>Logo que esteja lá uma mensagem, esta poderá ser descodificada e processada num único passo, sem se preocupar com os casos em que nem todos os dados foram recebidos (porque o 'messageLength' garante que está lá tudo). </para> + +</sect2> + +<sect2 id="mcop-protocol-invocations"> +<title +>Invocações</title> + +<para +>Para invocar um método remoto, você precisa de enviar a seguinte estrutura no corpo de uma mensagem de &MCOP; com o messageType = 1 (mcopInvocation): </para> + +<programlisting +>struct Invocation { + long objectID; + long methodID; + long requestID; +}; +</programlisting> + +<para +>depois disso, você envia os parâmetros como uma estrutura, ⪚ se você invocar o método 'concatenar(string s1, string s2)', você envia uma estrutura do tipo </para> + +<programlisting +>struct InvocationBody { + string s1; + string s2; +}; +</programlisting> + + +<para +>se o método foi declarado como 'só de ida0 - o que significa que é assíncrono sem código devolvido - então é tudo. Caso contrário, você iria receber como resposta uma mensagem com o messageType = 2 (mcopReturn) </para> + +<programlisting +>struct ReturnCode { + long requestID; + <tipo-a-devolver> result; +}; +</programlisting> + + +<para +>em que o <tipo-a-devolver> é o tipo do resultado. Como os tipos 'void' são omitidos na codificação, você também poderá só escrever o 'requestID' se regressar de um método 'void'. </para> + +<para +>Por isso o nosso método 'string concatenar(string s1, string s2)' iria originar um código de resultado do tipo </para> + +<programlisting +>struct ReturnCode { + long requestID; + string result; +}; +</programlisting> + +</sect2> + +<sect2 id="mcop-protocol-inspecting"> +<title +>Inspeccionar as Interfaces</title> + +<para +>Para fazer as invocações, você teria de conhecer os métodos que um objecto suporta. Para o fazer, o 'methodID' 0, 1, 2 e 3 estão pré-destinados a certas funcionalidades. Isto é </para> + +<programlisting +>long _lookupMethod(MethodDef defMetodo); // methodID sempre a 0 +string _interfaceName(); // methodID sempre a 1 +InterfaceDef _queryInterface(string nome); // methodID sempre a 2 +TypeDef _queryType(string nome); // methodID sempre a 3 +</programlisting> + +<para +>para ler isso, você obviamente precisa de </para> + +<programlisting +>struct MethodDef { + string methodName; + string type; + long flags; // posto a 0 por agora (será necessário na transmissão) + sequence<ParamDef> signature; +}; + +struct ParamDef { + string name; + long typeCode; +}; +</programlisting> + +<para +>o campo 'parameters' contém os componentes do tipo que indicam os tipos dos parâmetros. O tipo do valor devolvido é indicado no campo 'type' do MethodDef. </para> + +<para +>De forma restrita, só os métodos <methodname +>_lookupMethod()</methodname +> e <methodname +>_interfaceName()</methodname +> são diferentes de objecto para objecto, enquanto que o <methodname +>_queryInterface()</methodname +> e o <methodname +>_queryType()</methodname +> são sempre os mesmos. </para> + +<para +>O que são esses methodIDs? Se você fizer uma invocação de &MCOP;, irá ficar à espera de passar um número para o método que você está a invocar. A razão para tal é que os números podem ser processados muito mais depressa do que as cadeias de caracteres ao executar um pedido de &MCOP;. </para> + +<para +>Por isso, como é que obtém esses números? Se você souber a assinatura do método, existe um MethodDef que descreve o método (e que contém o nome, o tipo, os nomes e os tipos de parâmetros, entre outras coisas) e você poderá passar isso ao '_lookupMethod' do objecto onde deseja invocar um método. Dado que o '_lookupMethod' está pré-associado ao 'methodID' 0, você não deverá ter problemas ao fazê-lo. </para> + +<para +>Por outro lado, se você não souber a assinatura do método, você poderá descobrir os métodos que são suportados, usando o '_interfaceName', o '_queryInterface' e o '_queryType'. </para> +</sect2> + +<sect2 id="mcop-protocol-typedefs"> +<title +>Definições dos Tipos</title> + +<para +>Os tipos de dados definidos pelo utilizador são descritos com a estrutura <structname +>TypeDef</structname +>: </para> + +<programlisting +>struct TypeComponent { + string type; + string name; +}; + +struct TypeDef { + string name; + + sequence<TypeComponent> contents; +}; +</programlisting> + +</sect2> +</sect1> + +<sect1 id="why-not-dcop"> +<title +>Porque é que o &arts; Não Usa o &DCOP;</title> + +<para +>Dado que o &kde; largou o <acronym +>CORBA</acronym +> por completo e está a usar o &DCOP; em todo o lado, naturalmente a questão levantar-se-á: 'porque é que o &arts; não o faz também?'. No fim de tudo, o suporte do &DCOP; está no <classname +>KApplication</classname +>, é bem-mantido, supostamente integra-se bem com a libICE, entre outras coisas. </para> + +<para +>Dado que existirá (potencialmente) uma grande quantidade de pessoas a perguntar se ter o &MCOP; para além do &DCOP; é realmente necessário, aqui está a resposta. Não levem o autor a mal, porque não está a dizer <quote +>o &DCOP; é mau</quote +>. Simplesmente quer dizer <quote +>o &DCOP; não é a solução adequada para o &arts;</quote +> (embora seja uma boa solução para outras coisas). </para> + +<para +>Primeiro, você precisa de compreender para que é que o &DCOP; foi criado. Desenvolvido em dois dias durante o encontro &kde;-TWO, pretendia ser o mais simples possível, um protocolo de comunicações realmente <quote +>leve</quote +>. Especialmente, a implementação descartou tudo o que pudesse envolver complexidade, como por exemplo um conceito completo de como os tipos de dados seriam codificados. </para> + +<para +>Ainda que o &DCOP; não se preocupe com certas coisas (por exemplo: como é que se envia uma cadeia de caracteres de forma transparente na rede?) - isso precisa de ser feito. Por isso, tudo o que o &DCOP; não faz, fica a cargo do &Qt; nas aplicações do &kde; que usam o &DCOP; hoje em dia. Isto é em grande parte gestão de tipos (usando o operador de serialização do &Qt;). </para> + +<para +>Por isso, o &DCOP; é um protocolo mínimo que permite perfeitamente às aplicações do &kde; enviarem mensagens simples do tipo <quote +>abrir uma janela a apontar para http://www.kde.org</quote +> ou <quote +>os seus dados de configuração mudaram</quote +>. Contudo, dentro do &arts; o foco situa-se noutras coisas. </para> + +<para +>A ideia é que alguns pequenos 'plugins' do &arts; irão comunicar, trocando algumas estruturas de dados como <quote +>eventos MIDI</quote +> e <quote +>ponteiros de posição na música</quote +> ou <quote +>grafos de fluxo</quote +>. </para> + +<para +>Estes são tipos de dados complexos, os quais deverão ser enviados entre objectos diferentes e passados como sequências ou parâmetros. O &MCOP; fornece um conceito de tipos para definir dados complexos a partir de dados mais simples (de forma semelhante às estruturas ou vectores no C++). O &DCOP; não se preocupa com os tipos de todo, por isso este problema seria deixado para o programador - como: criar classes de C++ para os tipos, certificando-se que eles pudessem serializar-se correctamente (por exemplo: suportar o operador de transmissão do &Qt;). </para> + +<para +>Mas desta forma, eles seriam inacessíveis a tudo o que não fosse codificação directa de C++. Especificamente, você não poderia desenhar uma linguagem de 'scripting' que conhecesse todos os 'plugins' de tipo que poderão estar expostos, dado que eles não se descrevem a si próprios. </para> + +<para +>O mesmo argumento se aplica também às interfaces. Os objectos do &DCOP; não expõem as suas relações, hierarquias de herança, etc. - se você fosse criar um navegador de objectos que lhe mostrasse <quote +>que atributos tem tido este objecto</quote +>, seria mal-sucedido. </para> + + +<para +>Embora o Matthias tenha dito que existe uma função especial <quote +>functions</quote +> em cada objecto que lhe indica os métodos que um dado objecto suporta, isto deixa de fora coisas como os atributos (propriedades), as sequências e as relações de herança. </para> + +<para +>Isto quebra seriamente as aplicações como o &arts-builder;. Mas lembre-se. o &DCOP; não pretendia ser um modelo de objectos (dado que o &Qt; já tem um com o <application +>moc</application +> e semelhantes), nem pretende ser algo semelhante ao <acronym +>CORBA</acronym +>, mas simplesmente uma forma de fornecer comunicação entre aplicações. </para> + +<para +>Porque ainda o &MCOP; existe é: deverá funcionar perfeitamente com canais entre objectos. O &arts; faz um uso intensivo de pequenos 'plugins', que se interligam entre si com as sequências. A versão em <acronym +>CORBA</acronym +> do &arts; tinha de introduzir uma divisão muito incómoda entre <quote +>os objectos SynthModule</quote +>, os quais eram os módulos de trabalho internos que faziam a transmissão e <quote +>a interface <acronym +>CORBA</acronym +></quote +>, que era algo externo. </para> + +<para +>Muito do código preocupava-se em fazer a interacção entre <quote +>os objectos SynthModule</quote +> e <quote +>a interface <acronym +>CORBA</acronym +></quote +> parecer natural, mas não o era, porque o <acronym +>CORBA</acronym +> não sabia nada de nada sobre as sequências. O &MCOP; sabe. Olhe para o código (algo como o <filename +>simplesoundserver_impl.cc</filename +>). Muito melhor! As sequências podem ser declaradas na interface dos módulos e implementadas de forma natural. </para> + +<para +>Ninguém o pode negar. Uma das razões pela qual o &MCOP; foi feito foi a velocidade. Aqui estão alguns argumentos porque é que o &MCOP; será definitivamente mais rápido que o &DCOP; (sem sequer mostrar imagens). </para> + + +<para +>Uma invocação do &MCOP; terá um cabeçalho com seis <quote +>long</quote +>s. Isto é: </para> + +<itemizedlist> +<listitem +><para +>o código do <quote +>MCOP</quote +></para +></listitem> +<listitem +><para +>o tipo da mensagem (invocação)</para +></listitem> +<listitem +><para +>o tamanho do pedido em 'bytes'</para +></listitem> +<listitem +><para +>ID do pedido</para +></listitem> +<listitem +><para +>ID do objecto de destino</para +></listitem> +<listitem +><para +>ID do método de destino</para +></listitem> +</itemizedlist> + +<para +>Depois disso, seguem-se os parâmetros. Repare que a descodificação destes é extremamente rápida. Você poderá usar pesquisas em tabelas para encontrar o objecto e a função de descodificação do método, o que significa que a complexidade é O(1) (levará a mesma quantidade de tempo, independentemente de quantos objectos estão vivos, ou de quantas funções existem). </para> + +<para +>Comparando isto com o &DCOP;, verá que existem, pelo menos </para> + +<itemizedlist> +<listitem +><para +>uma cadeia de caracteres para o objecto de destino - algo do tipo <quote +>aMinhaCalculadora</quote +></para +></listitem +> +<listitem +><para +>um texto do tipo <quote +>adicionarNumero(int,int)</quote +> para indicar qual o método</para +></listitem> +<listitem +><para +>muita mais informação do protocolo adicionada pela 'libICE', e outros detalhes do DCOP que o autor desconhece</para +></listitem> +</itemizedlist> + +<para +>Tudo isto é muito doloroso para descodificar, dado que você irá necessitar de processar o texto, procurar a função, &etc;. </para> + +<para +>No &DCOP;, todos os pedidos são passados através de um servidor (o <application +>DCOPServer</application +>). Isto significa que o processo de uma invocação síncrona se assemelha a: </para> + +<itemizedlist> +<listitem> +<para +>O processo do cliente envia o pedido. </para> +</listitem> + +<listitem> +<para +>O <application +>DCOPserver</application +> (o homem-no-meio) recebe a invocação e procurar onde precisa de ir, enviando para o servidor <quote +>real</quote +>. </para> +</listitem +> + +<listitem> +<para +>O processo do servidor recebe a invocação, efectua o pedido e envia o resultado. </para> +</listitem> + +<listitem> +<para +>O <application +>DCOPserver</application +> (o homem-no-meio) recebe o resultado e ... envia-o para o cliente. </para> +</listitem> + +<listitem> +<para +>O cliente descodifica a resposta. </para> +</listitem> +</itemizedlist> + +<para +>No &MCOP;, a mesma invocação assemelha-se ao seguinte: </para> + +<itemizedlist> +<listitem> +<para +>O processo do cliente envia o pedido. </para> +</listitem> + +<listitem> +<para +>O processo do servidor recebe a invocação, efectua o pedido e envia o resultado. </para> +</listitem> + +<listitem> +<para +>O cliente descodifica a resposta. </para> +</listitem> +</itemizedlist> + +<para +>Digamos que ambos foram implementados correctamente, a estratégia ponto-a-ponto do &MCOP; deverá ser mais rápida por um factor de 2, do que a estratégia do 'homem-no-meio' do &DCOP;. Repare contudo que existiam razões para escolher a estratégia do &DCOP;, nomeadamente: se você tiver 20 aplicações a correr, se cada uma estiver a falar com outra, você precisa de 20 ligações no &DCOP;, e de 200 com o &MCOP;. Contudo, no caso do multimédia, isto não suposto ser a configuração normal. </para> + +<para +>Tentou-se comparar o &MCOP; com o &DCOP;, fazendo uma invocação do tipo 'adicionar dois números'. Alterou-se o 'testdcop' para conseguir isto. Porém, o teste pode não ter sido fidedigno do lado do &DCOP;. Invocou-se o método no mesmo processo que fez a chamada para o &DCOP;, e não se soube como se ver livre de uma mensagem de depuração, pelo que foi feita redireccionamento do resultado. </para> + +<para +>O teste só usava um objecto e uma função, esperando que os resultados do &DCOP; começassem a descer com mais objectos e funções, enquanto os resultados do &MCOP; se deveriam manter iguais. Também, o processo do <application +>dcopserver</application +> não estava ligado a nenhumas outras aplicações, pelo que, se estivessem outras aplicações ligadas, a performance do encaminhamento iria decrescer. </para> + +<para +>O resultado obtido foi que, enquanto o &DCOP; obteve cerca de 2000 invocações por segundo, o &MCOP; obteve um pouco mais de 8000 invocações por segundo. Isto resulta num factor de 4. Sabe-se que o &MCOP; não está ajustado para o máximo possível, ainda. (Comparação: o <acronym +>CORBA</acronym +>, implementado no 'mico', faz algo entre 1000 e 1500 invocações por segundo). </para> + +<para +>Se você quiser dados <quote +>mais em bruto</quote +>, pense em fazer alguma aplicação de medida de performance para o &DCOP; e envie-a para o autor. </para> + +<para +>O <acronym +>CORBA</acronym +> tinha a funcionalidade interessante de que você poderia usar os objectos que você implementou uma vez, como <quote +>processos de servidor separados</quote +> ou como <quote +>bibliotecas</quote +>. Você poderia usar o mesmo código para tal, e o <acronym +>CORBA</acronym +> iria decidir de forma transparente o que fazer. Com o &DCOP;, não é realmente pretendido, e tanto quanto se sabe não é possível realmente. </para> + +<para +>O &MCOP;, por outro lado, deverá suportá-lo logo desde o início. Por isso, você poderá correr um efeito dentro do &artsd;. Mas se você for um editor de ondas, você poderá optar por correr o mesmo efeito dentro do espaço do processo. </para> + +<para +>Embora o &DCOP; sej, em grande medida, uma forma de comunicar entre as aplicações, o &MCOP; também o é. Especialmente para a transmissão multimédia, o que é importante (dado que você poderá correr vários objectos &MCOP; em paralelo, para resolver uma tarefa de multimédia na sua aplicação). </para> + +<para +>Ainda que o o &MCOP; não o faça de momento, as possibilidades estão em aberto para implementar as funcionalidades de qualidade de serviço. Algo do género <quote +>aquele evento &MIDI; é mesmo MUITO importante, em comparação com esta invocação</quote +>. Ou algo do tipo <quote +>necessita de estar ali a tempo</quote +>. </para> + +<para +>Por outro lado, a transferência de sequências poderá ser integrada no protocolo &MCOP; sem problemas e ser combinada com elementos de <acronym +>QoS</acronym +>. Dado que o protocolo poderá ser alterado, a transferência de sequências do &MCOP; não deverá ser mais lenta do que uma transmissão convencional de <acronym +>TCP</acronym +>, mas: é mais fácil e mais consistente de usar. </para> + +<para +>Não existe necessidade de basear uma plataforma de multimédia no &Qt;. Ao decidir isso, e usando toda aquela serialização e outras funcionalidades giras do &Qt;, iria conduzir facilmente a que a plataforma se tornasse apenas para o &Qt; ou (para apenas para o &kde;). Quer dizer: assim que se vir que os GNOMEs comecem a usar o &DCOP;, também, ou algo do género, provavelmente o autor ficará errado. </para> + +<para +>Enquanto se sabe que o &DCOP; basicamente não sabe nada sobre os tipos de dados que envia, de modo que você poderia usar o &DCOP; sem usar o &Qt;, veja como é que é usado na utilização do dia-a-dia do &kde;: as pessoas enviam tipos como o <classname +>QString</classname +>, o <classname +>QRect</classname +>, o <classname +>QPixmap</classname +>, o <classname +>QCString</classname +>, ..., de um lado para o outro. Estes usam a serialização do &Qt;. Por isso, se alguém optar por suportar o &DCOP; num programa do GNOME, ele teria de afirmar que usava os tipos <classname +>QString</classname +>,... (ainda que não o faça, de facto) e emular a forma como o &Qt; faz a transmissão, ou então teria de enviar outros tipos de cadeias de caracteres, imagens e rectângulos, o que deixaria de ter possibilidades de interoperabilidade. </para> + +<para +>Bem, seja o que for, o &arts; pretendeu sempre funcionar com ou sem o &kde;, com ou sem o &Qt;, com ou sem o X11, e talvez com ou sem o &Linux; (e não há problema nenhum com as pessoas que o transpõem para um sistema operativo proprietário conhecido). </para> + +<para +>É a posição do autor que os componentes não&GUI; deverão ser criados de forma independente da &GUI;, para possibilitar a partilha destes pelas quantidades maiores de programadores (e utilizadores) possível. </para> + +<para +>É óbvio que o uso de dois protocolos de <acronym +>IPC</acronym +> pode causar problemas. Ainda mais, se ambos não forem normas. Contudo, pelas razões indicadas acima, a mudança para o &DCOP; não é uma opção. Se existir um interesse significativo em encontrar uma forma de unir os dois, ok, poderemos tentar. Até poderemos tentar fazer com que o &MCOP; 'fale' <acronym +>IIOP</acronym +>, onde então poderemos passar a ter um <acronym +>ORB</acronym +> de <acronym +>CORBA</acronym +>. </para> + +<para +>Falou-se com o Matthias Ettrich um pouco sobre o futuro dos dois protocolos e encontraram-se montes de formas como as coisas poderão seguir daqui para a frente. Por exemplo, o &MCOP; poderia tratar da comunicação de mensagens no &DCOP;, colocando os protocolos um pouco mais juntos entre si. </para> + +<para +>Por isso, algumas soluções possíveis seriam: </para> + +<itemizedlist> +<listitem> +<para +>Criar uma 'gateway' de &MCOP; - &DCOP; (o qual deverá ser possível, e possibilitaria a interoperabilidade) - nota: existe um protótipo experimentar, se quiser ver algo sobre o assunto. </para> +</listitem> + +<listitem> +<para +>Integrar tudo o que os utilizadores do &DCOP; esperam no &MCOP;, e tentar apenas usar o &MCOP; - uma pessoa até poderia adicionar uma opção de <quote +>homem-no-meio</quote +> no &MCOP;, também ;) </para> +</listitem> + +<listitem> +<para +>Basear o &DCOP; no &MCOP; em vez da 'libICE', e começar a integrar lentamente as coisas em conjunto. </para> +</listitem> +</itemizedlist> + +<para +>Contudo, poderá não ser a pior possibilidade para usar cada protocolo em tudo em que se pensou usar (existem algumas grandes diferenças nos objectivos de desenho), e não vale a pena tentar juntá-los num só. </para> + +</sect1> +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/midi.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/midi.docbook new file mode 100644 index 00000000000..6ac91d58aa0 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/midi.docbook @@ -0,0 +1,524 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="midi"> +<title +>&MIDI;</title> + +<sect1 id="midi-overview"> +<title +>Introdução</title> + +<!-- what-to-say-here: aRts has three roles + * moving midi events around between applications + * abstracting the hardware + * synthesizer --> + +<para +>O suporte de &MIDI; no &arts; poderá fazer uma quantidade de coisas. Primeiro que tudo, permite a <emphasis +>comunicação</emphasis +> entre as diversas peças de 'software' que produzem ou consomem eventos &MIDI;. Se você, por exemplo, tiver uma sequenciador e um reprodutor que funcionem com o &arts;, o &arts; poderá enviar os eventos &MIDI; do sequenciador para o reprodutor. </para> + +<para +>Por outro lado, o &arts; pode também ajudar as aplicações a <emphasis +>interagir com o 'hardware'</emphasis +>. Se um dado bloco de 'software' (como, por exemplo, o suporte de amostragem) funcionar em conjunto com o &arts;, ele será capaz de receber os eventos &MIDI; de um teclado &MIDI; externo, da mesma forma. </para> + +<para +>Finalmente, o &arts; dá um excelente <emphasis +>sintetizador modular</emphasis +>. Está desenhado para fazer exactamente isso. Por isso, você poderá criar instrumentos a partir de pequenos módulos com o 'artsbuilder', e usar depois esses instrumentos para compor ou tocar música. A síntese poderá não ser pura, dado que existem módulos que você poderá usar para tocar amostras. Por isso, o &arts; poderá ser um reprodutor de amostras, um sintetizador, entre outras coisas e, sendo completamente modular, é muito fácil de extender, muito fácil de experimentar, poderoso e flexível. </para> +</sect1> + +<sect1 id="midi-manager"> +<title +>O Gestor de &MIDI;</title> +<!-- what-to-say-here: + * how to use artscontrol - view midimanager + * what does autorestore do? (not yet implemented - so not yet documented) --> + +<para +>A componente central no &arts; que mantém o registo das aplicações que estão ligadas e como é que os eventos deverão ser passados entre elas é o gestor MIDI. Para ver ou influenciar o que ela faz, inicie o 'artscontrol'. Depois, escolha <menuchoice +><guilabel +>Ver</guilabel +><guilabel +>Ver o Gestor de MIDI</guilabel +> </menuchoice +> no menu. </para> + +<para +>Do lado esquerdo, você verá as <guilabel +>Entradas MIDI</guilabel +>. Aí, todos os objectos que produzam eventos &MIDI;, como por exemplo um porto &MIDI; que envie dados vindos de um teclado &MIDI; ligado, um sequenciador que toque uma música, entre outras coisas, serão aqui listados. Do lado direito, você verá as <guilabel +>Saídas MIDI</guilabel +>. Aqui, todas as coisas que consumam eventos &MIDI;, como um reprodutor de amostras simulado (como 'software') ou o porto &MIDI; externo onde o seu reprodutor por 'hardware' estará ligado, serão listadas. As aplicações novas, como os sequenciadores registar-se-ão elas próprias, de modo a que la lista vai sendo actualizada ao longo do tempo. </para> + +<para +>Você poderá ligar as entradas às saídas se você marcar a entrada do lado esquerdo e a saída do lado direito, escolhendo em seguida <guilabel +>Ligar</guilabel +> com o botão em baixo. O <guilabel +>Desligar</guilabel +> funciona da mesma forma. Você irá ver o que está ligado como pequenas linhas entre as entradas e as saídas, no meio da janela. Tenha em atenção que você poderá ligar um emissor a mais do que um receptor (e vice-versa). </para> + +<para +>Os programas (como o sequenciador Brahms) adicionar-se-ão eles próprios quando são iniciados e serão removidos da lista quando terminarem. Mas você também poderá adicionar itens novos no menu <guilabel +>Adicionar</guilabel +>: </para> + +<variablelist> +<varlistentry> +<term +><guimenuitem +>Porto MIDI do Sistema (OSS)</guimenuitem +></term> +<listitem> +<para +>Isto irá criar um novo objecto do &arts; que fala com um porto MIDI externo. </para> + +<para +>Dado que os portos MIDI externos podem fazer ambas as coisas (enviar e receber dados), a escolha desta opção irá adicionar uma entrada e uma saída MIDI. No &Linux;, você deverá ter um controlador <acronym +>OSS</acronym +> (ou <acronym +>OSS</acronym +>/Free, o que vem com o 'kernel' do seu &Linux;) ou um <acronym +>ALSA</acronym +> instalado para a sua placa de som, para que isto funcione. Ele irá perguntar o nome do dispositivo. Normalmente, este é o <filename class="devicefile" +>/dev/midi</filename +> ou o <filename class="devicefile" +>/dev/midi00</filename +>. </para> + +<para +>Contudo, se você tiver mais do que um dispositivo &MIDI; ou &MIDI; local instalado, poderão existir mais opções. Para ver mais informações sobre os seus portos &MIDI;, inicie o &kcontrolcenter; e escolha <menuchoice +><guilabel +>Informação</guilabel +> <guilabel +>Som</guilabel +></menuchoice +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><guimenuitem +>Saída MIDI de Sintetização do aRts</guimenuitem +></term> +<listitem> +<para +>Isto irá adicionar uma nova saída &MIDI; com um instrumento sintetizado do &arts;. Se você escolher o item do menu, aparecerá uma janela que lhe permite escolher um instrumento. Você poderá criar instrumentos novos com o 'artsbuilder'. Todos os ficheiros <literal role="extension" +>.arts</literal +> com um nome que comece por <filename +>instrument_</filename +> irão aparecer aqui. </para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="brahms"> +<title +>Usar o &arts; & o Brahms</title> + +<para +>De facto, começar é bastante fácil. Você irá precisar de uma versão para o &kde; 2.1 ou superior do &brahms;, a qual poderá ser encontrada no módulo <literal +>kmusic</literal +> do <acronym +>CVS</acronym +>. Existe também algumas informações sobre como obter o &brahms; na <ulink url="http://www.arts-project.org/" +>Página Pessoal do aRts</ulink +> na secção 'Download' (Transferir). </para> + +<para +>Quando você o inicia, irá aparecer no gestor de &MIDI;. Se você quiser fazer síntese, basta adicionar um instrumento sintetizado &MIDI; através da opção <menuchoice +><guilabel +>Adicionar</guilabel +><guilabel +>Saída MIDI de Síntese do aRts</guilabel +></menuchoice +>. </para> + +<para +>Escolha um instrumento (por exemplo, o <guilabel +>organ2</guilabel +>). Ligue-os com o botão <guilabel +>Ligar</guilabel +>. Finalmente, poderá começar a compor no &brahms;, para que o resultado seja sintetizado com o &arts;. </para> + +<para +>Normalmente, é uma boa ideia ter a janela do &artscontrol; aberta e ver se o volume não está muito alto (a qualidade piora quando as barras tocam no limite superior). Agora, você poderá começar a trabalhar numa música de demonstração do &arts; e, se estiver pronto, podê-la-á publicar no aRts-project.org ;-). </para> + +<!-- TODO: how to do more than one instrument in Brahms (hm, not implemented + yet, not documented yet), how to use samples, mapping and so on. These + things need to be implemented, too. --> + +</sect1> + +<sect1 id="midisend"> +<title +>midisend</title> + +<para +>O <command +>midisend</command +> é uma pequena aplicação que lhe permitirá enviar eventos de &MIDI; a partir da linha de comandos. Ele registar-se-á como cliente, tal como acontece com as outras aplicações. A forma mais simples de o usar é <screen +><prompt +>%</prompt +> <userinput +><command +>midisend</command +> <option +>-f</option +> <parameter +><replaceable +>/dev/midi00</replaceable +></parameter +></userinput +> </screen +>, o qual irá fazer mais ou menos o mesmo que adicionar um porto &MIDI; do sistema no &artscontrol;. (Nem por isso, porque o <command +>midisend</command +> só envia eventos). A diferença é que é fácil, por exemplo, iniciar o <command +>midisend</command +> em vários computadores diferentes (e, por isso, usar a transparência na rede). </para> + +<para +>Também é possível fazer com que o <command +>midisend</command +> envie os dados a partir do <filename class="devicefile" +>stdin</filename +>, o qual poderá usar para encaminhar os dados das aplicações que não conhecem o &arts;, como a seguinte: <screen +><prompt +>%</prompt +> <userinput +><command +><replaceable +>aplicacao_que_produz_eventos_midi_no_stdout</replaceable +></command +> | <command +>midisend</command +> <option +>-f</option +> <option +><replaceable +>-</replaceable +></option +></userinput +></screen> +<!-- TODO: document all options --> +</para> + +</sect1> + +<sect1 id="midi-creating-instruments"> +<title +>Criar Instrumentos</title> + +<para +>A forma como o &arts; faz a síntese de &MIDI; é a seguinte: você tem uma estrutura com alguns portos de entrada, onde ele vai obter a frequência, a velocidade (volume) e um parâmetro que indica se a nota ainda continua carreada. A estrutura deverá agora sintetizar exactamente a nota com esse volume e reagir ao parâmetro 'pressed' (pressionado) (onde o 'pressed' = 1 significa que o utilizador ainda mantém essa tecla carregada e o 'pressed' = 0 significa que o utilizador soltou a tecla). </para> + +<para +>Quando os eventos &MIDI; chegam, o &arts; irá criar novas estruturas para as notas à medida das necessidades, passar-lhes os parâmetros, e limpá-las quando terminar. </para> + +<para +>Para criar e usar uma dessas estruturas, você deverá fazer o seguinte: </para> + +<itemizedlist> +<listitem> +<para +>Para começar, a forma mais conveniente é abrir o ficheiro <filename +>template_Instrument.arts</filename +> no &arts-builder;. </para> + +<para +>Isto poderá ser obtido se usar o <menuchoice +><guimenu +>Ficheiro</guimenu +><guimenuitem +>Abrir um Exemplo...</guimenuitem +></menuchoice +> e escolher o <guimenuitem +>template_Instrument</guimenuitem +> no selector de ficheiros. Isto dar-lhe-á uma estrutura vazia com os parâmetros necessários, os quais você só terá de <quote +>preencher</quote +>. </para> +</listitem> + +<listitem> +<para +>Para processar o parâmetro 'pressed', é conveniente usar o Synth_ENVELOPE_ADSR, ou, no caso de tocar apenas um WAV de uma bateria, simplesmente tocá-lo, ignorando deste modo o parâmetro 'pressed'. </para> +</listitem> + +<listitem> +<para +>A estrutura deverá indicar quando já não é necessária na saída <quote +>done</quote +> (pronto). Se o 'done' for igual a <returnvalue +>1</returnvalue +>, o &arts; irá assumir que pode remover a estrutura. Convenientemente, o envelope de ADSR fornece um parâmetro quando tiver terminado, por isso só precisa de ligar isto à saída 'done' da estrutura. </para> +</listitem> + +<listitem> +<para +>Você deverá mudar o nome da sua estrutura para algum nome que comece por <filename +>instrument_</filename +>, como por exemplo <filename +>instrument_piano.arts</filename +> - você deverá gravar o ficheiro com o mesmo nome na sua pasta <filename class="directory" +>$<envar +>HOME</envar +>/arts/structures</filename +> (a qual é onde o 'artsbuilder' normalmente deseja gravar os ficheiros). </para> +</listitem> + +<listitem> +<para +>Finalmente, logo que o tenha gravado, você será capaz de o usar com o &artscontrol; no gestor de &MIDI;.</para> +</listitem> + +<listitem> +<para +>Ah, e claro que a sua estrutura deverá tocar os dados de áudio que gera nas saídas esquerda e direita da estrutura, as quais serão por sua vez tocadas no gestor de áudio (você poderá ver isso no &artscontrol;), para que o consiga ouvir finalmente (ou processá-lo posteriormente com efeitos). </para> +</listitem> +</itemizedlist> + +<para +>Uma boa forma de aprender como criar instrumentos é abrir um instrumento existente através da opção <menuchoice +><guilabel +>Ficheiro</guilabel +><guilabel +>Abrir um Exemplo</guilabel +> </menuchoice +> e ver como funciona ;) </para> +</sect1> + +<sect1 id="mapped-instruments"> +<title +>Instrumentos Mapeados</title> + +<para +>Os instrumentos mapeados são os que se comportam de forma diferente, dependo da frequência, do programa, do canal ou da velocidade. Você poderá ter por exemplo um piano de 5 oitavas, usando uma amostra por cada oitava (ajustando a frequência, de acordo com isso). Isto irá soar bastante melhor do que usar apenas uma amostra. </para> + +<para +>Você poderá criar também um mapa de bateria, o qual toca uma amostra específica da bateria por tecla. </para> + +<para +>Finalmente, é muito útil se você tocar vários sons diferentes num instrumento mapeado em programas diferentes. Desta forma, você poderá usar o seu sequenciador, teclado externo ou outra fonte &MIDI; para mudar de sons sem ter de ajustar o &arts; à medida que trabalha. </para> + +<para +>Um bom exemplo para isso é o instrumento <filename +>arts_all</filename +>, o qual apenas reúne todos os instrumentos que vêm com o &arts; num mapa. Desta forma, você apenas terá de configurar uma vez o &artscontrol; para usar este <quote +>instrumento</quote +>, e assim, poderá compor uma música inteira num sequenciador sem ter de se incomodar com o &arts;. Precisa de outro som? Basta escolher o programa no sequenciador, para que o &arts; lhe dê outro som. </para> + +<para +>Criar esses mapas é relativamente simples. Você apenas precisa de criar um ficheiro de texto e escrever regras que se assemelhem a isto: </para> + +<programlisting +>ON <replaceable +>[ condições ...]</replaceable +> DO structure=<replaceable +>uma_estrutura</replaceable +>.arts +</programlisting> + +<para +>As condições poderão ser uma ou mais das seguintes: </para> + +<variablelist> + +<varlistentry> +<term +><option +>pitch</option +></term> + +<listitem> +<para +>A frequência ou tom que é tocado. Você poderá usar isto se quiser dividir o seu instrumento com base no tom. No exemplo inicial, um piano que use amostras diferentes para as várias oitavas iria usar isto como condição. Você poderá indicar uma frequência única, como por exemplo <userinput +><option +>pitch</option +>=<parameter +>62</parameter +></userinput +> ou um intervalo de frequências, como por exemplo <userinput +><option +>pitch</option +>=<parameter +>60</parameter +>-<parameter +>72</parameter +></userinput +>. Os tons possíveis situam-se entre <parameter +>0</parameter +> e <parameter +>127</parameter +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>program</option +></term> +<listitem> +<para +>O programa que está activo no canal para onde a nota vai ser enviada. Normalmente, os sequenciadores permitem-lhe escolher o <quote +>instrumento</quote +> através da opção 'program'. São permitidos programas únicos ou intervalos de programas, isto é, por exemplo, <userinput +><option +>program</option +>=<parameter +>3</parameter +></userinput +> ou <userinput +><option +>program</option +>=<parameter +>3</parameter +>-<parameter +>6</parameter +></userinput +>. Os programas possíveis situam-se entre <parameter +>0</parameter +> e <parameter +>127</parameter +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>channel</option +></term> +<listitem> +<para +>O canal para onde a nota vai ser enviada. São permitidos canais únicos ou intervalos, isto é, por exemplo, <userinput +><option +>channel</option +>=<parameter +>0</parameter +></userinput +> ou <userinput +><option +>channel</option +>=<parameter +>0</parameter +>-<parameter +>8</parameter +></userinput +>. Os canais possíveis situam-se entre <parameter +>0</parameter +> e <parameter +>15</parameter +>. </para> +</listitem> + +</varlistentry> +<varlistentry> +<term +><option +>velocity</option +></term> +<listitem> +<para +>A velocidade (volume) que a nota tem. São permitidas velocidades únicas (quem irá usar isso?) ou intervalos, como por exemplo <userinput +><option +>velocity</option +>=<parameter +>127</parameter +></userinput +> ou <userinput +><option +>velocity</option +>=<parameter +>64</parameter +>-<parameter +>127</parameter +></userinput +>. As velocidades possíveis situam-se entre <parameter +>0</parameter +> e <parameter +>127</parameter +>. </para> +</listitem> +</varlistentry> +</variablelist> + +<para +>Um exemplo completo para um mapa seria (este é extraído do ficheiro <filename +>instrument_arts_all.arts-map</filename +> actual): </para> + +<programlisting +>ON program=0 DO structure=instrument_tri.arts +ON program=1 DO structure=instrument_organ2.arts +ON program=2 DO structure=instrument_slide1.arts +ON program=3 DO structure=instrument_square.arts +ON program=4 DO structure=instrument_neworgan.arts +ON program=5 DO structure=instrument_nokind.arts +ON program=6 DO structure=instrument_full_square.arts +ON program=7 DO structure=instrument_simple_sin.arts +ON program=8 DO structure=instrument_simple_square.arts +ON program=9 DO structure=instrument_simple_tri.arts +ON program=10 DO structure=instrument_slide.arts +ON program=11 pitch=60 DO structure=instrument_deepdrum.arts +ON program=11 pitch=61 DO structure=instrument_chirpdrum.arts +</programlisting> + +<para +>Como você poderá ver, a estrutura é seleccionada, dependendo do programa. No programa 11, você vê um <quote +>mapa de bateria</quote +> (com dois itens), o qual irá tocar um <quote +>bombo</quote +> com o C-5 (pitch=60), e um <quote +>prato de choque</quote +> com o C#5 (pitch=61). </para> + +<para +>Para fazer com que os ficheiros dos mapas apareçam automaticamente no &artscontrol; como opções dos instrumentos, terão de se chamar <filename +>instrument_<replaceable +>qualquercoisa</replaceable +>.arts-map</filename +> e estarem na sua Pasta Pessoal, em <filename class="directory" +>$<envar +>HOME</envar +>/arts/structures</filename +>, ou na pasta do &kde; em <filename class="directory" +>$<envar +>KDEDIR</envar +>/usr/local/kde/share/apps/artsbuilder/examples</filename +>. As estruturas que são usadas no mapa poderão ser indicadas com a sua localização absoluta ou então relativa à pasta onde o ficheiro de mapa se encontra. </para> + +<para +>Extender o mapa 'arts_all map' ou mesmo criar um mapa geral &MIDI; completo para o &arts; é uma boa ideia para tornar o &arts; mais simples de usar por-si-só. Pense por favor em contribuir com instrumentos interessantes que faça, de modo a que possam ser incluídos nas versões futuras do &arts;. </para> +</sect1> + +<!-- TODO: Maybe helpful + * using an external keyboard + * loopback midi device + +<sect1 id="quick-start"> +<title +>Quick Start</title> + +</sect1> +<sect1 id="internal-details"> +<title +>More Internal Details</title> + +</sect1> + +<sect1 id="other-considerations"> +<title +>Other Considerations</title> + +</sect1> +--> + +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/midiintro.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/midiintro.docbook new file mode 100644 index 00000000000..fc9b9712a68 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/midiintro.docbook @@ -0,0 +1,16 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE appendix PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<appendix id="midi-introduction"> + +<title +>Introdução ao <acronym +>MIDI</acronym +></title> + +<para +>Ainda não escrito </para> + +</appendix> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/modules.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/modules.docbook new file mode 100644 index 00000000000..d1fd309b052 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/modules.docbook @@ -0,0 +1,1329 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-modules"> +<title +>Módulos do &arts;</title> + + <sect1 id="modules-introduction"> +<title +>Introdução</title> + +<para +>Este capítulo descreve todos os módulos normais do &arts;. Sendo uma das funcionalidades mais poderosas do &arts;, os módulos podem ser ligados em conjunto através de estruturas para implementar novas funções como efeitos e instrumentos. </para> + +<para +>Os módulos são divididos em duas categorias. Os módulos de síntese são usados para implementar a <quote +>canalização</quote +> que manipula as sequências de dados multimédia para implementar novos efeitos, instrumentos, misturadores e aplicações. Os módulos visuais permitem-lhe oferecer uma interface gráfica para o utilizador poder controlar as estruturas de som que são criadas com os módulos de síntese. </para> + +</sect1> + +<sect1 id="synth-modules-reference"> +<title +>Referência dos Módulos de Síntese</title> + + +<sect2 id="mcat-synth-arithmetic-mixing"> +<title +>Aritmética + Mistura</title> + + + +<sect3 id="mref-synth-add-sect"> +<title +>Synth_ADD</title> +<anchor id="mref-synth-add"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_ADD.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_ADD</phrase +></textobject> +</mediaobject> + +<para +>Isto adiciona dois sinais. </para> + +</sect3> + +<sect3 id="mref-synth-mul-sect"> +<title +>Synth_MUL</title> +<anchor id="mref-synth-mul"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_MUL.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_MUL</phrase +></textobject> +</mediaobject> + +<para +>Isto multiplica um sinal por um determinado factor. Você poderá usar isto para reduzir a amplitude dos sinais (0 < factor < 1) ou ampliá-los (factor > 1) ou ainda invertê-los (factor < 0). Tenha em atenção que o factor pode ser um sinal e não tem de ser constante (⪚ um sinal de envelope ou um sinal real). </para> + +</sect3> + +<sect3 id="mref-synth-div-sect"> +<title +>Synth_DIV</title> +<anchor id="mref-synth-div"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_DIV.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_DIV</phrase +></textobject> +</mediaobject> + +<para +>Isto divide um sinal por um dado facto. Poderá usar isto para dividir um sinal por outro. Pode definir também o valor1 como sendo 1 e irá obter o simétrico do valor2 como resultado. Tenha em atenção que o valor2 nunca deverá ser igual a 0, caso contrário irá ter problemas com divisões por zero. </para> + +</sect3> + +<sect3 id="mref-synth-multi-add-sect"> +<title +>Synth_MULTI_ADD</title> +<anchor id="mref-synth-multi-add"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_MULTI_ADD.png" + format="PNG"/></imageobject> +<textobject +><phrase +>Synth_MULTI_ADD</phrase +></textobject> +</mediaobject> + +<para +>Isto adiciona uma quantidade arbitrária de sinais. Se você precisar de somar todas as formas de onda produzidas por quatro osciladores, você poderá ligar todas as saídas deles a um único módulo Synth_MULTI_ADD. Isto é mais eficiente do que usar três módulos Synth_ADD. </para> + +</sect3> + +<sect3 id="mref-synth-xfade-sect"> +<title +>Synth_XFADE</title> +<anchor id="mref-synth-xfade"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_XFADE.png" format="PNG"/> +</imageobject> +<textobject +><phrase +>Synth_XFADE</phrase +></textobject> +</mediaobject> + +<para +>Isto mistura dois sinais. Se o valor da percentagem for igual a -1, só o sinal esquerdo é ouvido; se for igual a 1, só o sinal direito é ouvido. Se for 0 (zero), ambos os sinais são ouvidos com o mesmo volume. </para> + +<para +>Isto permite-lhe garantir que o seu sinal permanece num intervalo bem definido. Se você tiver dois sinais que estejam entre -1 e 1 antes da mistura, eles irão permanecer dentro do mesmo intervalo após a dita mistura. </para> +</sect3> + +<sect3 id="mref-synth-autopanner-sect"> +<title +>Synth_AUTOPANNER</title> +<anchor id="mref-synth-autopanner"/> + +<para +>O oposto de um 'crossfader'. Este recebe um sinal mono e divide-o num sinal estéreo: É usado para deslocar automaticamente o sinal à entrada entre a saída esquerda e a direita. Isto torna as misturas mais vivias. Uma aplicação normal seria uma guitarra ou um som principal. </para> + +<para +>Ligue um <acronym +>LFO</acronym +>, uma onda sinusoidal ou dente-de-serra por exemplo ao 'inlfo'. e seleccione uma frequência entre 0,1 e 5Hz para um efeito tradicional ou mais ainda para efeitos especiais. </para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-busses"> +<title +>Barramentos</title> + +<sect3 id="mref-synth-bus-uplink-sect"> +<title +>Synth_BUS_UPLINK</title> +<anchor id="mref-synth-bus-uplink"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_BUS_UPLINK.png" + format="PNG"/> +</imageobject> +<textobject +><phrase +>Synth_BUS_UPLINK</phrase +></textobject> +</mediaobject> + +<para +>Um canal de envio para um barramento. Forneça os sinais ao 'left' (esquerdo) e ao 'right' (direito), bem como o nome do barramento onde os dados deverão ir no porto <quote +>bus</quote +>. O sinal combinado de todos os canais de envio ('uplinks') irão aparecer em todos os canais de recepção ('downlinks') desse <quote +>barramento</quote +>. </para> +</sect3> + +<sect3 id="mref-synth-bus-downlink-sect"> +<title +>Synth_BUS_DOWNLINK</title> +<anchor id="mref-synth-bus-downlink"/> + +<mediaobject> +<imageobject> +<imagedata fileref="images/Synth_BUS_DOWNLINK.png" + format="PNG"/></imageobject> +<textobject +><phrase +>Synth_BUS_DOWNLINK</phrase +></textobject> +</mediaobject> + +<para +>Obtém (a soma de) todos os dados que são colocados num determinado barramento (com o nome que você indicar no porto <quote +>bus</quote +> (barramento)). </para> +</sect3> + +</sect2> + +<!-- TODO AFTER KDE2.1: move freeverb into delays, and rename category to + Delays & reverbs --> + +<sect2 id="mcat-synth-delays"> +<title +>Atrasos</title> + + + +<sect3 id="mref-synth-delay-sect"> +<title +>Synth_DELAY</title> +<anchor id="mref-synth-delay"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_DELAY.png" + format="PNG"/></imageobject +></mediaobject> + +<para +>Isto atrasa o sinal de entrada por um período de tempo determinado. A especificação do tempo deverá ser entre 0 e 'maxdelay' (atraso máximo) para obter um atraso equivalente em segundos. </para> + +<para +>Este tipo de atrasos <emphasis +>não pode ser usado</emphasis +> nas estruturas de realimentação ('feedback'). Isto acontece por ser um atraso variável. Você poderá modificar o seu tamanho enquanto corre e até mesmo configurá-lo como sendo zero. Mas como numa estrutura de realimentação a própria saída é necessária para calcular as próximas amostras, uma atraso cujo valor possa cair para zero durante a síntese poderá conduzir a uma situação de paragem. </para> + +<para +>Use os CDELAYs nesse caso, e combinando talvez um atraso constante (de 0,001 segundos) com um atraso flexível. </para> + +<para +>Você poderá também combinar um CDELAY com um DELAY para obter um atraso de tamanho variável com um valor mínimo num ciclo de realimentação. Certifique-se apenas que tem um CDELAY. </para> + +</sect3> + +<sect3 id="mref-synth-cdelay-sect"> +<title +>Synth_CDELAY</title> +<anchor id="mref-synth-cdelay"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_CDELAY.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_CDELAY</phrase +></textobject> +</mediaobject> + +<para +>Isto atrasa o sinal de entrada por um período de tempo determinado. A especificação do tempo deverá ser maior que 0 para obter um atraso de 0 segundos ou mais. O atraso é constante durante o cálculo, o que significa que ele não poderá ser modificado. </para> + +<para +>Isto poupa no tempo de cálculo, atendendo a que não é feita nenhuma interpolação e é útil para estruturas recursivas. Veja a descrição acima (Synth_DELAY). </para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-envelopes"> +<title +>Envelopes</title> + + + +<sect3 id="mref-synth-envelope-adsr-sect"> +<title +>Synth_ENVELOPE_ADSR</title> +<anchor id="mref-synth-envelope-adsr"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_ENVELOPE_ADSR.png" + format="PNG"/></imageobject> +<textobject +><phrase +>Synth_ENVELOPE_ADSR</phrase +></textobject> +</mediaobject> + +<para +>Este é um envelope clássico de <acronym +>ADSR</acronym +>, o que significa que você indica: </para> + +<variablelist> +<varlistentry> +<term +>active</term> +<listitem> +<para +>Se a nota está a ser carregada de momento pelo utilizador. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>invalue</term> +<listitem> +<para +>O sinal de entrada. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>attack</term> +<listitem> +<para +>O tempo que deverá passar entre o utilizador carregar na nota e o sinal atingir a sua amplitude máxima (em segundos). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>decay</term> +<listitem> +<para +>O tempo que deverá passar entre o sinal atingir a sua amplitude máxima e o sinal a voltar para um nível constante (em segundos). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>sustain</term> +<listitem> +<para +>O nível constante em que o sinal é mantido até que o utilizador solte a nota. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>release</term> +<listitem> +<para +>O tempo que deverá passar depois de o utilizador soltar a nota até que o sinal seja reduzido até zero (em segundos). </para> +</listitem> +</varlistentry> +</variablelist> + +<para +>Você irá obter o sinal redimensionado em 'outvalue' (na saída). Se o envelope do <acronym +>ASDR</acronym +> tiver terminado, irá colocar o 'done' (terminado) a 1. Você poderá usar isto para fornecer a saída <quote +>done</quote +> de um instrumento (que fará com que a estrutura do instrumento seja removida pelo encaminhador de &MIDI; logo que a fase do 'release' tenha terminado). </para> + +</sect3> + +<sect3 id="mref-synth-pscale-sect"> +<title +>Synth_PSCALE</title> +<anchor id="mref-synth-pscale"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_PSCALE.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_PSCALE</phrase +></textobject> +</mediaobject> + +<para +>O módulo Synth_PSCALE irá aplicar um factor de escala ao canal de áudio que passa por ele, desde um volume 0 (silêncio) até o 1 (volume original), e de volta a 0 (silêncio). De acordo com a posição (pode obter a posição a partir de Synth_SEQUENCE). A altura em que o pico deverá ocorrer poder ser indicada em 'pos'. </para> + +<para +>Exemplo: Se definir o 'top' igual a 0,1 significa que, ao fim de 10% da nota ter sido tocada, o volume atingiu o seu máximo e começa a decair a partir daí. </para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-effects"> +<title +>Efeitos</title> + +<sect3 id="mref-synth-freeverb-sect"> +<title +>Synth_FREEVERB</title> +<anchor id="mref-synth-freeverb"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_FREEVERB.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_FREEVERB</phrase +></textobject> +</mediaobject> + +<para +>Este é um efeito de reverberação. Na implementação actual, passa um sinal estéreo através do efeito, adicionando a tal reverberação ao mesmo sinal. </para> + +<note> +<para +>Isto significa que ele também poderá ser usado numa StereoEffectStack. </para> +</note> + +<para +>O sinal de entrada deverá ser ligado a (inleft, inright) e o de saída a (outleft, outright). </para> + +<para +>Os parâmetros que você poderá configurar são: </para> + +<variablelist> +<varlistentry> +<term +>roomsize</term> +<listitem> +<para +>O tamanho da sala que a reverberação irá simular (intervalo: 0..1, em que o 1 é a maior sala possível). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>damp</term> +<listitem> +<para +>Isto indica um filtro que fará com que a sala simulada absorva as altas frequências (intervalo de 0..1, em que o 1 significa que as altas frequências são absorvidas de forma agressiva). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>wet</term> +<listitem> +<para +>A quantidade de sinal reverberado (isto é, a quantidade de sinal que deverá ser modificado pelos filtros, resultando num som <quote +>molhado</quote +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>dry</term> +<listitem> +<para +>A quantidade de sinal puro que é passado, resultando num eco (ou atraso combinado), em vez de ser afectado por reverberação (intervalo: 0..1). </para> +<!-- TODO: do some measurements to show that this documentation -is- correct, +I am not sure if it is echo, or really pure (non-delayed), or multiple delay +or whatever --> +</listitem> +</varlistentry> + +<varlistentry> +<term +>largura</term> +<listitem> +<para +>A quantidade de efeito de estéreo que o algoritmo de reverberação adiciona ao efeito, tornando o som reverberado mais amplo no panorama estéreo (intervalo: 0..1). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>modo</term> +<listitem> +<para +>[ TODO: Pensa-se que, se o 'mode' for igual a 1, a reverberação mantém a imagem actual do som, e onde o 0 é a operação normal ] </para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3 id="mref-synth-tremolo-sect"> +<title +>Synth_TREMOLO</title> +<anchor id="mref-synth-tremolo"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_TREMOLO.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_TREMOLO</phrase +></textobject> +</mediaobject> + +<para +>O módulo 'tremolo' modula a amplitude com base numa onda <acronym +>LFO</acronym +>. Tradicionalmente você iria usar uma onda sinusoidal, mas porquê limitar-se? O que irá obter é um efeito muito intenso que corta a maioria dos arranjos devido ao seu efeito altamente dinâmico. O efeito de 'tremolo' é ainda um dos efeitos favoritos dos guitarristas, ainda que não seja tão popular como era nos anos 60. </para> + +<para +>[ TODO: de momento, isto está implementado como 'invalue + abs(inlfo)' - provavelmente faria mais sentido se fosse implementado como 'invalue * (1+inlfo*depth)', onde o 'depth' (profundidade) seria um parâmetro entre 0..1 - isto poderá ter sido decidido após o &kde;2.1 ; se tiver um comentário, envie uma mensagem para a lista do &arts; ;). ] </para> + +</sect3> +<sect3 id="mref-synth-fx-cflanger-sect"> +<title +>Synth_FX_CFLANGER</title> +<anchor id="mref-synth-fx-cflanger"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_FX_CFLANGER.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_FX_CFLANGER</phrase +></textobject> +</mediaobject> + +<para +>Um 'flanger' é um efeito de atraso variável no tempo. Para tornar o desenvolvimento de efeitos complexos de 'flanger' mais simples, é fornecido este módulo que contém a base de um 'flanger' de um canal. </para> + +<para +>Ele contém os seguintes portos:</para> + +<variablelist> +<varlistentry> +<term +>invalue</term> +<listitem> +<para +>O sinal que você deseja processar. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>lfo</term> +<listitem> +<para +>De preferência, uma onda sinusoidal que modula o tempo de atraso no 'flanger' (-1 .. 1). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>mintime</term> +<listitem> +<para +>O valor mínimo para o atraso no 'flanger' em milisegundos. Valores sugeridos: tente algo do género 1 ms. Por favor use valores < 1000 ms. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>maxtime</term> +<listitem> +<para +>O valor máximo para o atraso no 'flanger' em milisegundos. Valores sugeridos: tente algo do género 5 ms. Por favor use valores < 1000 ms. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>outvalue</term> +<listitem> +<para +>O sinal de saída. É importante que você misture isso com o sinal original para obter o efeito desejado. </para> +</listitem> +</varlistentry> +</variablelist> + +<tip> +<para +>Você poderá usar isto com base para um efeito de coro. </para> +</tip> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-filters"> +<title +>Filtros</title> + +<sect3 id="mref-synth-pitch-shift-sect"> +<title +>Synth_PITCH_SHIFT</title> +<anchor id="mref-synth-pitch-shift"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_PITCH_SHIFT.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_PITCH_SHIFT</phrase +></textobject> +</mediaobject> + +<para +>Este efeito de mudança de frequência altera a frequência do sinal da entrada sem afectar a velocidade. Uma aplicação para isto é por exemplo a alteração do toma da sua voz enquanto você a grava (e reproduz) em tempo-real. </para> + +<para +>O parâmetro <emphasis +>speed</emphasis +> (velocidade) é a velocidade relativa com que o sinal será reproduzido. Deste modo, uma velocidade igual a dois fará com que o som fique duas vezes mas alto (&ie; uma frequência de entrada de 440 Hz iria resultar numa frequência de saída de 880 Hz). </para> + +<para +>O parâmetro <emphasis +>frequency</emphasis +> (frequência) é usado internamente para mudar entre as várias diferenças do sinal. É ajustável e, dependendo da sua escolha, o desvio de frequência parecerá mais ou menos realístico para o seu caso de uso. Um bom valor para começar será algo do tipo 5 ou 10. </para> + +</sect3> + +<sect3 id="mref-synth-shelve-cutoff-sect"> +<title +>Synth_SHELVE_CUTOFF</title> +<anchor id="mref-synth-shelve-cutoff"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_SHELVE_CUTOFF.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_SHELVE_CUTOFF</phrase +></textobject> +</mediaobject> + +<para +>Filtra todas as frequências superiores à frequência de corte. </para> + +</sect3> + +<sect3 id="mref-synth-brickwall-limiter-sect"> +<title +>Synth_BRICKWALL_LIMITER</title> +<anchor id="mref-synth-brickwall-limiter"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_BRICKWALL_LIMITER.png" + format="PNG"/></imageobject> +<textobject +><phrase +>Synth_BRICKWALL_LIMITER</phrase +></textobject> +</mediaobject> + +<para +>Este módulo corta um sinal, de modo a fazer com que ele caiba no intervalo [-1;1]. Ele não faz nada para evitar a distorção que acontece ao cortar os sinais altos. Você poderá usar isto como um efeito (por exemplo, para criar uma onda sinusoidal ligeiramente cortada). Contudo, é provavelmente uma boa ideia passar o sinal através de um filtro passa-baixo depois disso, para tornar o som menos agressivo. </para> +</sect3> + +<sect3 id="mref-synth-std-equalizer-sect"> +<title +>Synth_STD_EQUALIZER</title> +<anchor id="mref-synth-std-equalizer"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_STD_EQUALIZER.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_STD_EQUALIZER</phrase +></textobject> +</mediaobject> + +<para +>Este é um bloco de equalização parametrizado engraçado. Os seus parâmetros são: </para> + +<variablelist> +<varlistentry> +<term +>invalue, outvalue</term> +<listitem> +<para +>O sinal que é filtrado pelo equalizador. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>low</term> +<listitem> +<para +>Como é que as frequências baixas deverão ser alteradas. O valor está em dB, e onde 0 significa que as baixas frequências não são alteradas, o -6 significa que as reduzirá em 6dB, e o +6 significa que as aumenta em 6dB. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>mid</term> +<listitem> +<para +>Como é que as frequências intermédias deverão ser alteradas pelo equalizador (ver em 'low'). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>high</term> +<listitem> +<para +>Como é que as altas frequências deverão ser alteradas pelo equalizador (ver em 'low'). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>frequency</term> +<listitem> +<para +>Esta é a frequência central do equalizador em Hz, onde as frequências intermédias se situam à volta desse espectro, tendo as baixas frequências à sua esquerda e as altas à direita. Tenha em atenção que a frequência não poderá ser mais elevada que metade da taxa de amostragem; normalmente esta é igual a 22 050 Hz e não poderá ser menor que 1 Hz. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>q</term> +<listitem> +<para +>Isto influencia quão estreito é o espectro central. Deverá ser um número positivo > 0. Um valor igual a um é razoável, os valores mais elevados correspondem a um espectro mais estreito de frequências intermédios e os menores que um correspondem a um espectro largo. </para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3 id="mref-synth-rc-sect"> +<title +>Synth_RC</title> +<anchor id="mref-synth-rc"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_RC.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_RC</phrase +></textobject> +</mediaobject> + +<para +>Um filtro por ressonância filtra todas as frequências à volta de um determinado valor de pico. Não existe nenhuma forma útil de indicar a frequência intermédia (a que não será cortada), dado que as entradas são duas constantes estranhas 'f' e 'b'. O código é muito antigo, desde os primeiros dias do sintetizador, e provavelmente será substituído por um filtro novo que terá um frequência e um valor de ressonância como parâmetros). </para> + +<para +>Tente algo do género b=5, f=5 ou b=10, f=10 ou b=15, f=15, todavia. </para> + +</sect3> + +<sect3 id="mref-synth-moog-vcf-sect"> +<title +>Synth_MOOG_VCF</title> +<anchor id="mref-synth-moog-vcf"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_MOOG_VCF.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_MOOG_VCF</phrase +></textobject> +</mediaobject> + +<para +>Filtra todas as frequências acima da frequência de corte (é um filtro de 24dB com 4 pólos, o qual filtra -24db por oitava acima da frequência de corte), mas oferece um parâmetro adicional para ajustar a ressonância do filtro, em que o 0 significa ausência de ressonância e o 4 significa auto-oscilação. </para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-midi-sequencing"> +<title +>MIDI + Sequenciação</title> + +<sect3 id="mref-synth-midi-test-sect"> +<title +>Synth_MIDI_TEST</title> +<anchor id="mref-synth-midi-test"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_MIDI_TEST.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_MIDI_TEST</phrase +></textobject> +</mediaobject> + +<para +>Este módulo carrega uma estrutura de um instrumento a partir de um ficheiro e regista-se como uma saída de MIDI com o gestor de &MIDI; do &arts;. As notas que são enviadas para esta saída irão resultar na criação de vozes dos instrumentos. </para> + +<note> +<para +>Você poderá configurar algo mais conveniente no &artscontrol; do que fazê-lo manualmente no &arts-builder;. </para> +</note> + +</sect3> + +<sect3 id="mref-synth-sequence-sect"> +<title +>Synth_SEQUENCE</title> +<anchor id="mref-synth-sequence"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_SEQUENCE.png" +format="PNG"/></imageobject +></mediaobject> + +<para +>Irá tocar uma sequência de notas outra e outra vez. As notas são dadas na notação de teclado e são separadas por ponto-e-vírgula. Um exemplo será <literal +>A-3;C-4;E-4;C-4;</literal +>. A velocidade é dada em segundos por nota, por isso, se você quiser 120 batidas por minuto, você deverá indicar provavelmente 0,5 segundos por nota, dado que 60 segundos/0,5 segundos por nota=120 bpm. </para> + +<para +>Você poderá indicar em cada nota um tamanho relativo à velocidade adicionado dois pontos (:) a seguir à nota, seguido do tamanho. O <literal +>A-3:2;C-4:0.5;D-4:0.5;E-4;</literal +> demonstra isto. Como pode ver, os programas de composição de &MIDI; tendem a oferecer mais conforto ;) </para> + +<para +>O Synth_SEQUENCE dá-lhe informações adicionais sobre a posição da nota que está a tocar de momento, onde o 0 indica que iniciou agora e o 1 que terminou. Esta informação poderá ser usada no Synth_PSCALE (veja em baixo). </para> +</sect3> + +<sect3 id="mref-synth-sequence-freq-sect"> +<title +>Synth_SEQUENCE_FREQ</title> +<anchor id="mref-synth-sequence-freq"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_SEQUENCE_FREQ.png" +format="PNG"/></imageobject +></mediaobject> + +<para +>Este módulo funciona tal-e-qual o Synth_SEQUENCE com a única diferença que você não indica nomes de notas mas sim frequências. </para> + +</sect3> + +</sect2> + +<sect2 id="mcat-synth-samples"> +<title +>Amostras</title> + +<sect3 id="mref-synth-play-wav-sect"> +<title +>Synth_PLAY_WAV</title> +<anchor id="mref-synth-play-wav"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_PLAY_WAV.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_PLAY_WAV</phrase +></textobject> +</mediaobject> + +<para +>Isto irá tocar um ficheiro <literal role="extension" +>wav</literal +>. Isto só estará presente se você tiver a 'libaudiofile' instalada no seu computador. O ficheiro WAVE iniciar-se-á logo que o módulo for criado. </para> + +<para +>Irá parar logo que tenha terminado, situação em que o 'finished' (terminado) será posto a 1. O parâmetro 'speed' (velocidade) pode ser usado para reproduzir o ficheiro mais depressa ou mais devagar, e onde o 1,0 é a velocidade normal (com que foi gravado). </para> +<!-- TODO: KDE2.2: check that this really works together in instruments with +the done parameter things ;) --> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-soundio"> +<title +>E/S de Som</title> + +<sect3 id="mref-synth-play-sect"> +<title +>Synth_PLAY</title> +<anchor id="mref-synth-play"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_PLAY.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_PLAY</phrase +></textobject> +</mediaobject> + +<important> +<para +>Você normalmente não irá necessitar deste módulo, a menos que esteja a criar aplicações autónomas. Dentro do &artsd;, existe já um módulo Synth_PLAY e, se criar outro, este não irá funcionar. </para> +</important> + +<para +>O módulo Synth_PLAY irá enviar o seu sinal de áudio para a placa de som. Os canais 'left' (esquerdo) e 'right' (direito) deverão conter a entrada <emphasis +>normalizada</emphasis +> dos canais. Se a sua entrada não estiver entre -1 e 1, será cortado o sinal. </para> + +<para +>Como já foi referido, só pode existir um módulo Synth_PLAY em uso, dado que este acede directamente à sua placa de som. Utilize os barramentos se você quiser misturar mais do que um canal de áudio em conjunto antes de o reproduzir. Use o módulo Synth_AMAN_PLAY para obter algo semelhante a uma saída no &artsd;. </para> + +<para +>Tenha em atenção que o Synth_PLAY também faz a temporização da estrutura completa. Isto significa: sem Synth_PLAY = sem fonte de temporização = sem som. Por isso, você irá necessitar (exactamente) de um objecto Synth_PLAY. </para> + +</sect3> + +<sect3 id="mref-synth-record-sect"> +<title +>Synth_RECORD</title> +<anchor id="mref-synth-record"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_RECORD.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_RECORD</phrase +></textobject> +</mediaobject> + +<important> +<para +>Você normalmente não irá necessitar deste módulo, a menos que esteja a criar aplicações autónomas. Dentro do &artsd;, existe já um módulo Synth_RECORD e, se criar outro, este não irá funcionar. </para> +</important> + +<para +>O módulo Synth_RECORD irá gravar um sinal proveniente da placa de som. Os canais 'left' (esquerdo) e 'right' (direito) irão conter a entrada dos canais (entre -1 e 1). </para> + +<para +>Como já foi referido, só pode existir um módulo Synth_RECORD em uso, dado que este acede directamente à sua placa de som. Utilize os barramentos se você quiser usar os canais de áudio gravados em mais do que um sítio. Use o módulo Synth_AMAN_RECORD para obter algo semelhante a uma entrada no &artsd;. Para isto funcionar, o &artsd; terá de estar a correr <emphasis +>com o 'full duplex' activo</emphasis +>. </para> +</sect3> + +<sect3 id="mref-synth-aman-play-sect"> +<title +>Synth_AMAN_PLAY</title> +<anchor id="mref-synth-aman-play"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_AMAN_PLAY.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_AMAN_PLAY</phrase +></textobject> +</mediaobject> + +<para +>O módulo Synth_AMAN_PLAY irá enviar para a saída o seu sinal de áudio. É bom (mas não necessário) se você enviar para fora um sinal normalizado (entre -1 e 1). </para> + +<para +>Este módulo irá usar o gestor de áudio para atribuir onde o sinal será tocado. O gestor de áudio poderá ser controlado através do &artscontrol;. Para o tornar mais intuitivo no seu uso, é bom dar ao sinal que tocar um nome. Isto poderá ser obtido através da opção <emphasis +>title</emphasis +> (título). Outra funcionalidade do gestor de áudio é ser capaz de se recordar onde tocou um dado sinal da última vez. Para o fazer, ele precisa de ser capaz de distinguir os sinais. É por isso que você deverá atribuir algo único ao <emphasis +>autoRestoreID</emphasis +>, também. </para> +</sect3> + +<sect3 id="mref-synth-aman-record-sect"> +<title +>Synth_AMAN_RECORD</title> +<anchor id="mref-synth-aman-record"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_AMAN_RECORD.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_AMAN_RECORD</phrase +></textobject> +</mediaobject> + +<para +>O módulo Synth_AMAN_RECORD irá gravar um sinal de áudio de uma fonte externa (&ie;. 'line in'/'microfone') para dentro do &artsd;. O resultado será um sinal normalizado (entre -1 e 1). </para> + +<para +>Este módulo irá usar o gestor de áudio para atribuir onde o sinal será tocado. O gestor de áudio poderá ser controlado através do &artscontrol;. Para o tornar mais intuitivo no seu uso, é bom dar ao sinal que gravar um nome. Isto poderá ser obtido através da opção <emphasis +>title</emphasis +> (título). Outra funcionalidade do gestor de áudio é ser capaz de se recordar onde gravou um dado sinal da última vez. Para o fazer, ele precisa de ser capaz de distinguir os sinais. É por isso que você deverá atribuir algo único ao <emphasis +>autoRestoreID</emphasis +>, também. </para> +</sect3> + +<sect3 id="mref-synth-capture-sect"> +<title +>Synth_CAPTURE</title> +<anchor id="mref-synth-capture"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_CAPTURE.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_CAPTURE</phrase +></textobject> +</mediaobject> + +<para +>O módulo Synth_CAPTURE irá gravar um sinal de áudio num ficheiro WAVE no seu disco rígido. O ficheiro será sempre chamado de <filename +>/tmp/mcop-<replaceable +>utilizador</replaceable +>/capture.wav</filename +> </para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-tests"> +<title +>Testes</title> + +<sect3 id="mref-synth-nil-sect"> +<title +>Synth_NIL</title> +<anchor id="mref-synth-nil"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_NIL.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_NIL</phrase +></textobject> +</mediaobject> + +<para +>Isto simplesmente não faz nada. Só é útil para situações de teste. </para> + +</sect3> + +<sect3 id="mref-synth-debug-sect"> +<title +>Synth_DEBUG</title> +<anchor id="mref-synth-debug"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_DEBUG.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_DEBUG</phrase +></textobject> +</mediaobject> + +<para +>Você poderá usar isto para depuração. Ele irá imprimir o valor do sinal em 'invalue' em intervalos regulares (p.ex. a cada 1 segundo), combinado com o comentário que você indicou. Desta forma, você poderá descobrir se alguns dos sinais estão dentro de determinados intervalos ou se estão lá mesmo de todo. </para> +</sect3> + +<sect3 id="mref-synth-midi-debug-sect"> +<title +>Synth_MIDI_DEBUG</title> +<anchor id="mref-synth-midi-debug"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_MIDI_DEBUG.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_MIDI_DEBUG</phrase +></textobject> +</mediaobject> + +<para +>Você poderá usar isto para depurar como é que os seus eventos &MIDI; estão a chegar ao &arts;. </para> + +<para +>Quando um MIDI_DEBUG estiver a correr, o &artsserver; irá imprimir linhas do tipo: </para> + +<screen +><computeroutput +>201 100753.837585 on 0 42 127</computeroutput +></screen> + +<screen +><computeroutput +>202 101323.128355 off 0 42</computeroutput +></screen> + +<para +>Enquanto que a primeira linha lhe diz que 100753ms (isto é, 100 segundos) depois de o MIDI_DEBUG começar, chegou um evento 'on' de &MIDI; no canal 0. Este evento tinha a velocidade (volume) de 127, a mais elevada possível. A linha a seguir mostra o evento de libertação do MIDI. [ TODO: isto não funciona de momento, quando funcionar, deverá ser feito através do gestor de &MIDI; ]. </para> +</sect3> + +<sect3 id="mref-synth-data-sect"> +<title +>Synth_DATA</title> +<anchor id="mref-synth-data"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_DATA.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_DATA</phrase +></textobject> +</mediaobject> + +<para +>Isto cria um sinal com um número constante. </para> +<!-- TODO: this doesn't really belong in test, does it? --> +</sect3> +</sect2> + +<sect2 id="mcat-synth-osc-mod"> +<title +>Oscilação & Modulação</title> + +<sect3 id="mref-synth-frequency-sect"> +<title +>Synth_FREQUENCY</title> +<anchor id="mref-synth-frequency"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_FREQUENCY.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_FREQUENCY</phrase +></textobject> +</mediaobject> + +<para +>Todos os osciladores no &arts; não precisam de uma frequência à entrada, mas si de uma posição na onda. A posição deverá ser entre 0 e 1, o que se mapeia num objecto normal do Synth_WAVE_SIN no intervalo 0..2*pi. Para gerar os valores oscilantes para uma frequência, é usado um módulo Synth_FREQUENCY. </para> +</sect3> + +<sect3 id="mref-synth-fm-source-sect"> +<title +>Synth_FM_SOURCE</title> +<anchor id="mref-synth-fm-source"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_FM_SOURCE.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_FM_SOURCE</phrase +></textobject> +</mediaobject> + +<para +>Isto é usado na modulação de frequência. Coloque a sua frequência na entrada 'frequency' (frequência) e coloque outro sinal na entrada 'modulator'. Depois disso, defina o 'modlevel' (nível de modulação) para algo do género 0,3. A frequência será então modulada com o 'modulator'. Pode experimentar. Funciona bem mesmo quando você coloca uma realimentação nele, o que significa ter uma combinação do sinal de saída atrasado com o Synth_FM_SOURCE (você terá de o pôr com algum oscilador, dado que só tem o papel do Synth_FREQUENCY) e algum outro sinal para obter bons resultados. </para> + +<para +>Funciona optimamente em conjunto com os osciladores Synth_WAVE_SIN. </para> +</sect3> + +</sect2> + +<sect2 id="mcat-synth-waveforms"> +<title +>Formas de Onda</title> + +<sect3 id="mref-synth-wave-sin-sect"> +<title +>Synth_WAVE_SIN</title> +<anchor id="mref-synth-wave-sin"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_WAVE_SIN.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_WAVE_SIN</phrase +></textobject> +</mediaobject> + +<para +>Oscilador sinusoidal. Coloque um sinal 'pos' de um Synth_FREQUENCY ou de um Synth_FM_SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. </para> + +</sect3> + +<sect3 id="mref-synth-wave-tri-sect"> +<title +>Synth_WAVE_TRI</title> +<anchor id="mref-synth-wave-tri"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_WAVE_TRI.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_WAVE_TRI</phrase +></textobject> +</mediaobject> + +<para +>Oscilador de ondas triangulares. Coloque um sinal 'pos' de um Synth_FREQUENCY ou de um Synth_FM_SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis +>tem</emphasis +> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para> +</sect3> + +<sect3 id="mref-synth-noise-sect"> +<title +>Synth_NOISE</title> +<anchor id="mref-synth-noise"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_NOISE.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_NOISE</phrase +></textobject> +</mediaobject> + +<para +>Um gerador de ruído. Isto gera um sinal aleatório entre -1 e 1. </para> + +</sect3> + +<sect3 id="mref-synth-wave-square-sect"> +<title +>Synth_WAVE_SQUARE</title> +<anchor id="mref-synth-wave-square"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_WAVE_SQUARE.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_WAVE_SQUARE</phrase +></textobject> +</mediaobject> + +<para +>Oscilador de ondas quadradas. Coloque um sinal 'pos' de um Synth_FREQUENCY ou de um Synth_FM_SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis +>tem</emphasis +> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para> +</sect3> + +<sect3 id="mref-synth-wave-softsaw-sect"> +<title +>Synth_WAVE_SOFTSAW</title> +<anchor id="mref-synth-wave-softsaw"/> + +<mediaobject +><imageobject +><imagedata +fileref="images/Synth_WAVE_SOFTSAW.png" format="PNG"/></imageobject> +<textobject +><phrase +>Synth_WAVE_SOFTSAW</phrase +></textobject> +</mediaobject> + +<para +>Oscilador de ondas dente-de-serra. Coloque um sinal 'pos' de um Synth_FREQUENCY ou de um Synth_FM_SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis +>tem</emphasis +> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para> +</sect3> + +<sect3 id="mref-synth-wave-pulse-sect"> +<title +>Synth_WAVE_PULSE</title> +<anchor id="mref-synth-wave-pulse"/> + +<mediaobject +><imageobject +><imagedata fileref="images/Synth_WAVE_PULSE.png" +format="PNG"/></imageobject> +<textobject +><phrase +>Synth_WAVE_PULSE</phrase +></textobject> +</mediaobject> + +<para +>Oscilador de impulsos - este módulo é semelhante na ideia ao oscilador de ondas quadradas (Synth_WAVE_RECT), mas oferece uma relação configurável de nível alto/baixo, através do parâmetro <emphasis +>dutycycle</emphasis +>. Coloque um sinal 'pos' de um Synth_FREQUENCY ou de um Synth_FM_SOURCE à entrada. Deste modo, poderá obter uma onda sinusoidal à saída. O sinal 'pos' indica a posição de fase na onda, e pertence ao intervalo 0..1, que se mapeia internamente em 0..2*PI. Tenha cuidado, porque o sinal de entrada <emphasis +>tem</emphasis +> de estar no intervalo 0..1 para que o sinal de saída produza bons resultados. </para> +</sect3> +</sect2> +<sect2 id="mcat-synth-misc"> +<title +>Diversos</title> + +<sect3 id="mref-synth-compressor-sect"> +<title +>Synth_COMPRESSOR</title> +<anchor id="mref-synth-compressor"/> + +<mediaobject> +<imageobject +><imagedata fileref="images/Synth_COMPRESSOR.png" + format="PNG"/></imageobject +></mediaobject> + +<para +>Este módulo reduz o intervalo dinâmico do sinal. Por exemplo, os compressores são úteis na compensação das variações amplas de volume se alguém estiver a falar para um microfone. </para> + +<para +>Assim que o nível de entrada exceder um dado nível (o patamar), o sinal é comprimido. Ele simplesmente multiplica tudo o que estiver acima do limite pelo valor de proporção, o qual é um número entre 0 e 1. Finalmente, o sinal completo é multiplicado pelo factor de saída. </para> + +<para +>Os argumentos 'attack' e 'release' atrasam o início e o fim da compressão. Use isto se você, por exemplo, quiser à mesma ouvir o início forte de uma batida de bateria. O argumento está em milisegundos e um valor igual a 0ms é possível, se bem que poderá resultar apenas num ligeiro ruído. </para> + +</sect3> +</sect2> +</sect1> + +<sect1 id="visual-modules-reference"> +<title +>Referência dos Módulos Visuais</title> + +<para +>TODO quando os módulos visuais estiverem mais "completos". </para> +</sect1> + +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/porting.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/porting.docbook new file mode 100644 index 00000000000..03834e67b4c --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/porting.docbook @@ -0,0 +1,52 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="porting"> +<title +>Passar as Aplicações para o &arts;</title> + +<sect1 id="using-artsdsp"> +<title +>Usar o &artsdsp;</title> + +<para +>O utilitário &artsdsp;, <link linkend="artsdsp" +>descrito anteriormente</link +>, permite à maioria das aplicações de som legadas que falem directamente com os dispositivos de áudio, funcionarem convenientemente com o &arts;. As aplicações que foram criadas para usar o Enlightenment Sound Daemon (<application +>esd</application +>) irão também funcionar na maioria dos casos, se for executado o <application +>esd</application +> sobre o &artsdsp;. </para> + +<para +>Isto possibilita uma solução a curto prazo para passar as aplicações existentes para o &kde;. Todavia, não permite que a aplicação tire directamente partido de todas as potencialidades do &arts;, como a utilização dos módulos e das sequências multimédia que não sejam apenas áudio digital. Se a aplicação necessitar de algo mais do que a reprodução de ficheiros de som, normalmente fará sentido adicionar o suporte nativo para o &arts; na aplicação. </para> + +<para +>Ao usar o &arts; significa também que a aplicação não terá assim muito trabalho -- poderá remeter as funções para o &arts;, de modo a resolver alguns problemas, como por exemplo os codificadores para lidar com diferentes formatos multimédia e controlar o 'hardware' de som. </para> + +</sect1> + +<sect1 id="adding-native-arts-support"> +<title +>Adicionar o suporte nativo do &arts;</title> + +<para +>Ao usar o &arts;, você tem um conjunto de <link linkend="arts-apis" +><acronym +>API</acronym +>s</link +> diferentes por onde escolher. A decisão de qual usar depende de um conjunto de factores, como o tipo de conteúdos multimédia a usar (som, &MIDI;, &CD; áudio, &etc;), as funcionalidades necessárias da <acronym +>API</acronym +>, e se é escrito em C++. Na maioria dos casos, a escolha deverá ser relativamente óbvia com base nas funcionalidades pedidas. </para> + +<para +>Para uma portabilidade entre plataformas, as aplicações que precisem de correr noutros ambientes que não sejam o &kde;, não poderão confiar na presença do &arts;. Se usar o paradigma dos 'plugins' terá uma boa forma de suportar vários ambiente multimédia. Se tornar a <acronym +>API</acronym +> de 'plugins' aberta e documentada (especialmente para as aplicações com código fechado), terá também a vantagem de permitir que alguém que não o programador da aplicação implemente um 'plugin' do &arts;. </para> + +</sect1> + +</chapter> + diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/references.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/references.docbook new file mode 100644 index 00000000000..85eb7a70f53 --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/references.docbook @@ -0,0 +1,61 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="references"> +<title +>Referências</title> + +<variablelist> + +<varlistentry> +<term +><ulink +url="http://multimedia.kde.org" +>http://multimedia.kde.org</ulink +></term> +<listitem> +<para +>Esta é o 'site' Web principal para as informações relacionadas com multimédia do &kde;. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><ulink +url="http://www.arts-project.org" +>http://www.arts-project.org</ulink +></term> +<listitem> +<para +>Esta é a página principal do projecto do &arts;. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +>Programação no &kde; 2.0</term> +<listitem> +<para +>O Capítulo 14 deste livro publicado cobre o multimédia e inclui o &arts;. Está disponível impresso ou 'online' com anotações em <ulink url="http://www.andamooka.org/" +>http://www.andamooka.org</ulink +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<ulink +url="http://sound.condorow.net" +>http://sound.condorow.net</ulink +></term> +<listitem> +<para +>Este 'site' contém uma lista razoável de aplicações de som e de &MIDI; para o &Linux;. </para> +</listitem> +</varlistentry> + +</variablelist> + +</chapter> diff --git a/tde-i18n-pt/docs/tdemultimedia/artsbuilder/tools.docbook b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/tools.docbook new file mode 100644 index 00000000000..9cc6d2134fa --- /dev/null +++ b/tde-i18n-pt/docs/tdemultimedia/artsbuilder/tools.docbook @@ -0,0 +1,1007 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> + +To validate or process this file as a standalone document, uncomment +this prolog. Be sure to comment it out again when you are done --> + +<chapter id="arts-tools"> +<title +>Ferramentas do &arts;</title> + +<para +>Incluído com o &arts;, vem um conjunto de utilitários para controlar e configurar o seu comportamento. Você precisa de ter alguma familiaridade com a maioria dessas ferramentas para usar efectivamente o &arts;. Esta secção descreve cada um dos utilitários e as suas opções de comando. </para> + +<sect1 id="kde-control-center"> +<title +>&kcontrol;</title> + +<para +>Ao correr o &arts; no &kde;, o &kcontrolcenter; oferece um grupo de opções do painel de controlo na categoria <guilabel +>Som</guilabel +>. Algumas dessas opções são usadas pelo &arts;. Você também poderá associar sons com vários eventos do gestor de janelas e do &kde; com o painel <menuchoice +><guilabel +>Aparência & Comportamento</guilabel +><guilabel +>Notificações do Sistema</guilabel +></menuchoice +>. Veja o manual do &kcontrol; para saber como usar as opções do painel. </para> + +</sect1> + +<sect1 id="artsd"> +<title +>&artsd;</title> + +<para +>O acesso aos recursos de 'hardware' de som é controlado pelo &artsd;, o servidor do &arts;. Isto permite às várias aplicações enviarem pedidos simultâneos ao servidor, onde poderão ser misturados e tocados. Sem um servidor de som centralizado, uma única aplicação que usasse um dispositivo de som iria impedir que as outras aplicações o usassem também. </para> + +<para +>Para usar o &arts;, deverá existir uma e apenas uma cópia do &artsd; a correr. É tipicamente executada quando o &kde; se inicia, se estiver activo no painel do &kcontrol; <guilabel +>Servidor de Som</guilabel +> do &kcontrol;. </para> + +<para +>O programa aceita os seguintes argumentos:</para> + +<!-- LW: FIX THIS --> + +<cmdsynopsis +><command +>artsd</command +> <group choice="opt" +> <option +>-n</option +> <option +>-p</option +> <option +>-N</option +> <option +>-W <replaceable +>n</replaceable +></option +> </group +> <group choice="opt" +> <option +>-a <replaceable +>método de audio</replaceable +></option +> <option +>-r <replaceable +>taxa amostragem</replaceable +></option +> <option +>-b <replaceable +>bits</replaceable +></option +> <option +>-d</option +> <option +>-D <replaceable +>nome dispositivo</replaceable +></option +> <option +>-F <replaceable +>fragmentos</replaceable +></option +> <option +>-S <replaceable +>tamanho</replaceable +></option +> <option +>-s <replaceable +>segundos</replaceable +></option +> <option +>-m <replaceable +>nome da aplicação</replaceable +></option +> </group +> <group choice="opt" +> <option +>-h</option +> <option +>-A</option +> <option +>-v</option +> <option +>-l <replaceable +>nível</replaceable +></option +> </group +> </cmdsynopsis> + +<variablelist +><varlistentry> +<term +><option +>-r <replaceable +>taxa de amostragem</replaceable +></option +></term> +<listitem> +<para +>Indica a taxa de amostragem a usar.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-h</option +></term> +<listitem> +<para +>Mostra a utilização dos comandos.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-n</option +></term> +<listitem> +<para +>Activa a transparência na rede.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-p <replaceable +>porto</replaceable +></option> +</term> +<listitem> +<para +>Define o porto de <acronym +>TCP</acronym +> a usar (implica o <option +>-n</option +>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-u</option +></term> +<listitem> +<para +>Público e sem autenticação (perigoso).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-d</option +></term> +<listitem> +<para +>Activa a operação em 'full duplex'.</para> +</listitem> +</varlistentry> +<varlistentry> +<term +><option +>-D <replaceable +>nome do dispositivo</replaceable +></option +></term> +<listitem> +<para +>Indica o dispositivo de áudio a usar (normalmente é o <filename +>/dev/dsp</filename +>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-F <replaceable +>fragmentos</replaceable +></option +></term> +<listitem> +<para +>Define o número de fragmentos.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-S <replaceable +>tamanho</replaceable +></option +></term> +<listitem> +<para +>Define o tamanho de cada fragmento em 'bytes'.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-s <replaceable +>segundos</replaceable +></option +></term> +<listitem> +<para +>Define o tempo de suspensão automática do servidor, em segundos. Um valor igual a zero desactiva a suspensão automática.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-m <replaceable +>nome da aplicação</replaceable +></option +></term> +<listitem> +<para +>Indica o nome de uma aplicação para usar para mostrar as mensagem de erro, de aviso e informativas. Se você estiver a correr o KDE, poderá usar o utilitário <application +>artsmessage</application +> para isto.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-N</option +></term> +<listitem> +<para +>Aumenta o tamanho dos tampões de rede para um valor adequado para correr numa LAN de 10 Mbps. Isto é equivalente a usar a opção '-w 5' (ver em baixo). </para> +</listitem> +</varlistentry> +<varlistentry> +<term +><option +>-w <replaceable +>n</replaceable +></option +></term> +<listitem> +<para +>Ao correr o <application +>artsd</application +> sobre uma ligação de rede a outra máquina, você poderá querer usar um tamanho maior dos tampões ('buffers') para evitar cortes. O aRts fornece às aplicações um tamanho mínimo sugerido. Sem esta opção, o tamanho por omissão baseia-se no valor 'tamanho do fragmento' * 'número de fragmentos'. Se usar esta opção você poderá aumentar o tamanho predefinido por um factor de <replaceable +>n</replaceable +>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-l <replaceable +>nível</replaceable +></option +></term> +<listitem> +<para +>Indica o nível de informações - 3 (silencioso), 2 (avisos), 1 (informação), 0 (depuração).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-v</option +></term> +<listitem> +<para +>Mostra o número da versão.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para +>Na maioria dos casos, bastará correr o &artsd;. </para> +</sect1> + +<sect1 id="artswrapper"> +<title +>&artswrapper;</title> + +<para +>Para oferecer uma boa resposta em tempo-real, o &artsd; é normalmente executado como um processo em tempo-real (nas plataformas que suportem prioridades de tempo-real). Isto necessita de permissões do <systemitem class="username" +>root</systemitem +>, por isso, para minimizar as implicações de segurança, o &artsd; poderá ser iniciado com o pequeno programa de interface &artswrapper;, o qual simplesmente configura a prioridade de tempo-real (correndo como <systemitem class="username" +>root</systemitem +>) e executa depois o &artsd; como um utilizador que não o <systemitem class="username" +>root</systemitem +>. </para> + +<para +>Se você tornar o 'artswrapper' 'SUID' <systemitem class="username" +>root</systemitem +>, ele irá provavelmente melhorar a qualidade da sua reprodução de áudio, reduzindo os cortes na música. Contudo, aumenta também o risco de que um erro no código ou algum utilizador malicioso faça estoirar ou prejudicar o seu sistema. Para além disso, nas máquinas multi-utilizador, se prioritizar o áudio de alta-fidelidade poderá provocar uma perda de 'performance' para os utilizadores que estão a tirar partido <quote +>produtivo</quote +> da máquina.</para> + +</sect1> + +<sect1 id="artsshell"> +<title +>&artsshell;</title> + +<para +>O comando &artsshell; pretende ser um utilitário para efectuar diversas funções relacionadas com o servidor de som. Pretende-se que o utilitário seja extendido com comandos novos no futuro (veja os comentários no código-fonte para ter algumas ideias). </para> + +<para +>O comando aceita o seguinte formato: </para> + +<!-- LW: FIX THIS --> + +<cmdsynopsis +><command +>artsshell</command +> <group +> <arg +>suspend</arg +><arg +>status</arg +> <arg +>terminate</arg +> <arg +>autosuspend <replaceable +>segundos</replaceable +></arg +> <arg +>networkbuffers <replaceable +>n</replaceable +></arg +> <arg +>volume [<replaceable +>volume</replaceable +>]</arg +> <arg +>stereoeffect <replaceable +>opções</replaceable +></arg +> </group +> <group +> <option +>-h</option +> <option +>-q</option +> </group +> </cmdsynopsis> + +<para +>artsshell [options] <replaceable +>comando</replaceable +> [<replaceable +>opções do comando</replaceable +>] </para> + +<para +>São suportadas as seguintes opções: </para> + +<variablelist> + +<varlistentry> +<term +><option +>-q</option +></term> +<listitem> +<para +>Suprime todos os resultados.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-h</option +></term> +<listitem> +<para +>Mostra a utilização dos comandos.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para +>São suportados os seguintes comandos:</para> + +<variablelist> + +<varlistentry> +<term +><option +>suspend</option +></term> +<listitem> +<para +>Suspende o servidor de som. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>status</option +></term> +<listitem> +<para +>Mostra a informação de estado do servidor de som.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>terminate</option +></term> +<listitem> +<para +>Termina o servidor de som. Isto poderá confundir e/ou estoirar as aplicações que o estejam a usar no momento. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>autosuspend</option +> <parameter +>segundos</parameter +></term> +<listitem> +<para +>Configura o tempo de suspensão automática para o número de segundos indicado. O servidor de som suspender-se-á se estiver inactivo durante esse período de tempo. Um valor igual a zero desactiva a suspensão automática. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>networkbuffers</option +> <parameter +>n</parameter +></term> +<listitem> +<para +>Define o tamanho dos tampões de rede para ser um facto de <parameter +>n</parameter +> vezes o tamanho predefinido. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>volume</option +> [<replaceable +>volume</replaceable +>]</term> +<listitem> +<para +>Altera o factor de escala para as saídas de áudio do servidor de som. O argumento <replaceable +>volume</replaceable +> é um valor de vírgula flutuante. Sem argumentos, é mostrado o volume actual. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>stereoeffect lista</option +></term> +<listitem> +<para +>Mostra todos os módulos de efeitos estéreo disponíveis.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>stereoeffect insert [top|bottom]</option +> <replaceable +>nome</replaceable +></term> +<listitem> +<para +>Introduz um efeito estéreo na pilha de efeitos. Devolve um identificador que poderá ser usado para o remover posteriormente. Poderá ser instalado no topo ou no fundo (o valor por omissão).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>stereoeffect remove</option +> <replaceable +>identificador</replaceable +></term> +<listitem> +<para +>Remove o efeito estéreo com o identificador <replaceable +>identificador</replaceable +> da pilha de efeitos.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="artsplay"> +<title +><application +>artsplay</application +></title> + +<para +>O comando <application +>artsplay</application +> é um utilitário simples para tocar um ficheiro de som. Ele aceita um único argumento que corresponde ao nome de um ficheiro de som que é enviado para o servidor de som de modo a ser tocado. O ficheiro de som poderá ser qualquer tipo de ficheiro de som comum como o <literal role="extension" +>wav</literal +> ou o <literal role="extension" +>au</literal +>. Este utilitário é bom para testar se o servidor de som está a funcionar. Se correr dois comandos em paralelo ou em sucessão rápida, você poderá demonstrar como os servidores de som misturam mais do que uma fonte.</para> + +</sect1> + +<sect1 id="artsdsp"> +<title +><application +>artsdsp</application +></title> + +<para +>O servidor de som só suporta as aplicações que tirem partido do &arts;. Muitas das aplicações legadas querem aceder ao dispositivo de som directamente. O comando &artsdsp; oferece uma solução intermédia que permite à maioria dessas aplicações correrem sem alterações. </para> + +<para +>Quando uma aplicação é executada com o &artsdsp;, todos os acessos ao dispositivo de áudio <filename class="devicefile" +>/dev/dsp</filename +> são interceptadas e mapeadas em chamadas à <acronym +>API</acronym +> do &arts;. Embora a emulação do dispositivo não seja perfeita, a maioria das aplicações funciona desta forma, ainda que com alguma latência e degradação de performance. </para> + +<para +>O comando &artsdsp; segue o formato: </para> + +<!-- LW: FIX THIS --> +<para +>artsdsp [<replaceable +>opções</replaceable +>] <replaceable +>argumentos da aplicação</replaceable +> </para> + +<para +>São reconhecidas as seguintes opções: </para> + +<variablelist> + +<varlistentry> +<term +><option +>-h</option +>, <option +>--help</option +></term> +<listitem> +<para +>Mostra uma breve ajuda.</para> +</listitem> +</varlistentry> +<varlistentry> +<term +><option +>-n</option +> <option +>--name</option +> = <replaceable +>nome</replaceable +></term> +<listitem> +<para +>Usa o <replaceable +>nome</replaceable +> para identificar o leitor no <command +>artsd</command +>.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-m</option +> <option +>--mmap</option +></term> +<listitem> +<para +>Emula o mapeamento de memória (⪚ para o <application +>Quake</application +>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-v</option +> <option +>--verbose</option +></term> +<listitem> +<para +>Mostra os parâmetros.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para +>Uma invocação típica é a seguinte: </para> + +<para> +<userinput +><command +>artsdsp</command +> <option +>-v</option +> <option +>-m</option +> <parameter +>realplay <replaceable +>musica.mp3</replaceable +></parameter +></userinput> +</para> + +<para +>Algumas aplicações funcionam melhor com a opção <option +>--mmap</option +>. Nem todas as funcionalidades do dispositivo de som estão emuladas por completo, mas a maioria das aplicações deverá funcionar. Se encontrar alguma que não funcione, envie um relatório de erro detalhado para que os programadores o possam corrigir. Mais uma vez, lembre-se que isto é uma solução intermédia e uma espécie de 'truque sujo'; a melhor solução será adicionar o suporte nativo do &arts; às aplicações. Se a sua aplicação de som favorita não tem o suporte do &arts;, peça ao programador para o fornecer. </para> + +</sect1> + +<sect1 id="artscat"> +<title +><application +>artscat</application +></title> + +<para +>Este é um utilitário simples para enviar os dados em bruto para o servidor de som. Você precisa de indicar o formato dos dados (a taxa de amostragem, o tamanho da amostra e o número de canais). Este não é provavelmente um utilitário que use muito, mas poderá ser útil para fins de teste. A sintaxe do comando é a seguinte: </para> + +<!-- LW: FIX THIS --> + +<para +>artscat [ <replaceable +>opções</replaceable +> ] [ <replaceable +>nome do ficheiro</replaceable +> ] </para> + +<para +>Se não for indicado nenhum ficheiro, irá ler do 'standard input'. São suportadas as seguintes opções: </para> + +<variablelist> +<varlistentry> +<term +><option +>-r</option +> <parameter +>taxa de amostragem</parameter +></term> +<listitem> +<para +>Configura a taxa de amostragem a ser usada. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-b</option +> <parameter +>bits</parameter +></term> +<listitem> +<para +>Define o tamanho da amostra a usar (8 ou 16). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-c</option +> <parameter +>canais</parameter +></term> +<listitem> +<para +>Define o número de canais (1 ou 2). </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-h</option +></term> +<listitem> +<para +>Mostra a utilização do comando e sai. </para> +</listitem> +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="artscontrol"> +<title +>&artscontrol;</title> + +<para +>Este é um utilitário gráfico para efectuar um dado número de tarefas relacionadas com o servidor de som. A janela por omissão mostra dois indicadores do nível do volume e uma barra para controlar o volume global. No menu <guimenu +>Ver</guimenu +>, você poderá seleccionar outras funções: </para> + +<variablelist> + +<varlistentry> +<term +><guimenuitem +>Osciloscópio FFT</guimenuitem +></term> +<listitem> +<para +>Abre uma janela que mostra um visualização do tipo de analisador de espectro em tempo-real. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><guimenuitem +>Gestor de Áudio</guimenuitem +></term> +<listitem> +<para +>Mostra as fontes de áudio activas e permite-lhe ligá-las a qualquer um dos barramentos disponíveis. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><guimenuitem +>Estado do aRts</guimenuitem +></term> +<listitem> +<para +>Mostra se o servidor de som está a correr e se o escalonamento é feito em tempo-real. Indica quando o servidor se suspende automaticamente e permite-lhe suspendê-lo imediatamente. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><guimenuitem +>Gestor de MIDI</guimenuitem +></term> +<listitem> +<para +>Mostra as entradas e saídas activas de &MIDI; e permite-lhe criar ligações [TODO: Isto ainda funciona? São precisos mais detalhes]. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><guimenuitem +>FreeVerb</guimenuitem +></term> +<listitem> +<para +>Liga um efeito de reverberação FreeVerb à pilha dos efeitos de saída do &arts; e permite-lhe controlar graficamente os parâmetros do efeito. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><guimenuitem +>Mostrador de volume com Leds</guimenuitem +></term> +<listitem> +<para +>Muda os indicadores de volume da janela principal para usar um mostrador colorido com <acronym +>LED</acronym +>s em vez de usar barras de progresso. </para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="artsc-config"> +<title +><application +>artsc-config</application +></title> + +<para +>Este é um utilitário para ajudar os programadores a usar a <acronym +>API</acronym +> de C do &arts;. Ele mostra as opções apropriadas do compilador e do editor de ligações que são necessárias ao compilar e ao gerar um executável com o &arts;. Pretende-se que seja usado nas 'Makefile's para ajudar na portabilidade. O comando aceita três opções: </para> + +<variablelist> +<varlistentry> +<term +><option +>--cflags</option +></term> +<listitem> +<para +>Mostra as opções do compilador que são necessárias ao compilar com a <acronym +>API</acronym +> de C do &arts;. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>--libs</option +></term> +<listitem> +<para +>Mostra as opções do editor de ligações que são necessárias ao gerar o executável que usa as bibliotecas da <acronym +>API</acronym +> de C do &arts;. </para> +</listitem> +</varlistentry> +<varlistentry> +<term +><acronym +>--version</acronym +></term> +<listitem> +<para +>Mostra a versão do comando <command +>artsc-config</command +>. </para> +</listitem> +</varlistentry> +</variablelist> + +<para +>O resultado típico do comando é mostrado em baixo:</para> + +<screen width="40" +><prompt +>%</prompt +> <userinput +><command +>artsc-config</command +> <option +>--cflags</option +></userinput> +<computeroutput +>-I/usr/local/kde3/include/artsc</computeroutput> +<prompt +>%</prompt +> <userinput +><command +>artsc-config</command +> <option +>--libs</option +></userinput> +<computeroutput +>-L/usr/local/kde3/lib -ldl -lartsc -DPIC -fPIC -lpthread</computeroutput> +<prompt +>%</prompt +> <userinput +><command +>artsc-config</command +> <option +>--version</option +></userinput> +<computeroutput +>0.9.5</computeroutput +> +</screen> + +<para +>Você poderá usar este utilitário numa Makefile para uma regra do tipo: </para> + +<programlisting +>artsc: artsc.c + gcc `artsc-config --cflags` -o artsc artsc.c `artsc-config --libs` +</programlisting> + +</sect1> + +<sect1 id="mcopidl"> +<title +>&mcopidl;</title> + +<para +>O comando &mcopidl; é o compilador de ficheiros &IDL; para o &MCOP;, o 'Multimedia Communication Protocol' usado pelo &arts;. As interfaces no &arts; são definidas em &IDL;, uma 'Interface Definition Language' independente da linguagem. O utilitário &mcopidl; aceita um ficheiro &IDL; como entrada e gera ficheiros de inclusão e de código em C++ que implementam essa interface. O comando aceita a seguinte sintaxe: </para> + +<!-- LW: FIX THIS --> + +<para +>mcopidl [ <replaceable +>opções</replaceable +> ] <replaceable +>nome do ficheiro</replaceable +> </para> + +<para +>As opções válidas são:</para> +<variablelist> +<varlistentry> +<term +><option +>-I</option +> <parameter +>directoria</parameter +></term> +<listitem> +<para +>Procura na <parameter +>directoria</parameter +> pelos ficheiros de inclusão. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-e</option +> <parameter +>nome</parameter +></term> +<listitem> +<para +>Exclui a estrutura, interface ou tipo enumerado <parameter +>nome</parameter +> da geração de código. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term +><option +>-t</option +></term> +<listitem> +<para +>Cria também os ficheiros <literal role="extension" +>.mcoptype</literal +>/<literal role="extension" +>.mcopclass</literal +> que contêm a informação do tipo para o ficheiro &IDL;. </para> +</listitem> +</varlistentry> +</variablelist> + +<para +>Para mais informações sobre o &MCOP; e o &IDL;, poderá ver a secção <link linkend="interfaces" +>Interfaces e &IDL;</link +>. </para> + +</sect1> + +</chapter> |