这个 applet 的完整代码在 NormSample.java 中。

使用 JTextComponent 类处理双向文本

原文：docs.oracle.com/javase/tutorial/i18n/text/bidi.html

本节讨论如何使用JTextComponent类处理双向文本。双向文本是包含从左到右和从右到左两个方向运行的文本。双向文本的一个示例是包含从右到左运行的阿拉伯文本（包含从左到右运行的数字）。显示和管理双向文本更加困难；但是JTextComponent会为您处理这些问题。

下面涵盖了以下主题：

• 确定双向文本的方向性

• 显示和移动插入符

• 命中测试

• 高亮选择

• 设置组件方向

欲了解更多信息，或者如果您想更好地控制处理这些问题，请参阅处理双向文本在 2D 图形教程中。

确定双向文本的方向性

示例BidiTextComponentDemo.java，基于TextComponentDemo.java，在JTextPane对象中显示双向文本。在大多数情况下，Java 平台可以确定双向 Unicode 文本的方向性：

在 JTextComponent 对象中明确指定文本运行方向

您可以指定JTextComponent对象的Document对象的运行方向。例如，以下语句指定JTextPane对象textPane中的文本从右到左运行：

textPane.getDocument().putProperty(
    TextAttribute.RUN_DIRECTION,
    TextAttribute.RUN_DIRECTION_RTL);

或者，您可以根据语言环境指定特定 Swing 组件的组件方向。例如，以下语句指定对象textPane的组件方向基于 ar-SA 语言环境：

Locale arabicSaudiArabia = 
    new Locale.Builder().setLanguage("ar").setRegion("SA").build();

textPane.setComponentOrientation(
    ComponentOrientation.getOrientation(arabicSaudiArabia));

因为阿拉伯语的运行方向是从右到左，所以textPane对象中包含的文本的运行方向也是从右到左。

有关更多信息，请参阅设置组件方向。

显示和移动插入符

在可编辑文本中，插入符用于图形表示当前插入点，即文本中新字符将插入的位置。在BidiTextComponentDemo.java示例中，插入符包含一个小三角形，指向插入字符将显示的方向。

默认情况下，JTextComponent对象创建一个键映射（类型为Keymap），该键映射作为所有JTextComponent实例共享的默认键映射。键映射允许应用程序将按键绑定到操作。默认键映射（用于支持插入符移动的JTextComponent对象）包括将插入符向前和向后移动与左右箭头键绑定，从而支持通过双向文本移动插入符。

点击测试

通常，设备空间中的位置必须转换为文本偏移量。例如，当用户在可选择文本上单击鼠标时，鼠标的位置将被转换为文本偏移量，并用作选择范围的一端。从逻辑上讲，这是定位插入符的逆过程。

您可以将插入符监听器附加到JTextComponent的实例上。插入符监听器使您能够处理插入符事件，这些事件发生在插入符移动或文本组件中的选择更改时。您可以使用addCaretListener方法附加插入符监听器。有关更多信息，请参见如何编写插入符监听器。

高亮选择

一段选定的字符范围在图形上由一个高亮区域表示，该区域是以反色或不同背景颜色显示字形的区域。

JTextComponent对象实现了逻辑高亮。这意味着选定的字符在文本模型中始终是连续的，而高亮区域可以是不连续的。以下是逻辑高亮的示例：

设置组件方向

Swing 的布局管理器了解区域设置如何影响用户界面；不需要为每个区域设置创建新的布局。例如，在文本从右到左流动的区域，布局管理器将以相同的方向排列组件。

示例 InternationalizedMortgageCalculator.java 已本地化为英语，美国；英语，英国；法语，法国；法语，加拿大；以及阿拉伯语，沙特阿拉伯。

以下示例使用 en-US 区域设置：

以下示例使用 ar-SA 区域设置：

请注意，组件的布局与相应区域设置的方向相同：en-US 为从左到右，ar-SA 为从右到左。示例 InternationalizedMortgageCalculator.java 调用方法 applyComponentOrientation 和 getOrientation 来指定其组件的方向：

private static JFrame frame;

// ...

private static void createAndShowGUI(Locale currentLocale) {

    // Create and set up the window.
    // ...
    // Add contents to the window.
    // ...
    frame.applyComponentOrientation(
        ComponentOrientation.getOrientation(currentLocale));
    // ...
  }

示例 InternationalizedMortgageCalculator.java 需要以下资源文件：

• resources/Resources.properties

• resources/Resources_ar.properties

• resources/Resources_fr.properties

课程：网络资源的国际化

原文：docs.oracle.com/javase/tutorial/i18n/network/index.html

在现代互联网社区中，许多用户不再满足于仅使用 ASCII 符号来识别域名或网络资源。例如，他们希望能够注册一个新的域名，使用阿拉伯语或中文中的本地字符。这就是为什么网络资源的国际化是拓宽万维网视野的基石。

本课程描述了网络域名资源的国际化。

国际化域名

国际化域名

原文：docs.oracle.com/javase/tutorial/i18n/network/idn.html

从历史上看，互联网域名仅包含 ASCII 符号。随着互联网的普及和在全球范围内的采用，支持域名的国际化变得必要，特别是支持包含 Unicode 字符的域名。

应用程序中的国际化域名（IDNA）机制被采用为将 Unicode 字符转换为标准 ASCII 域名的标准，从而保持域名系统的稳定性。该系统执行查找服务，将用户友好的名称转换为网络地址。

国际化域名的示例：

• http://清华大学.cn

• http://www.транспорт.com

如果您点击这些链接，您会看到地址栏中表示的 Unicode 域名被替换为 ASCII 字符串。

要在应用程序中实现类似的功能，java.net.IDN类提供了方法，用于在 ASCII 和非 ASCII 格式之间转换域名。

可选的flag参数指定转换过程的行为。ALLOW_UNASSIGNED标志允许包含 Unicode 3.2 中未分配的代码点。USE_STD3_ASCII_RULES标志确保遵守 STD-3 ASCII 规则。您可以单独使用这些标志或逻辑上合并它们。如果不需要任何标志，请使用该方法的单参数版本。

教程：国际化的服务提供者

原文：docs.oracle.com/javase/tutorial/i18n/serviceproviders/index.html

国际化的服务提供者使得可以插入区域相关的数据和服务。由于可以插入区域相关的数据和服务，第三方能够提供java.text和java.util包中大多数区域敏感类的实现。

服务是一组提供对特定应用程序功能或特性访问的编程接口和类。服务提供者接口（SPI）是服务定义的一组公共接口和抽象类。服务提供者实现了 SPI。服务提供者使您能够创建可扩展的应用程序，可以在不修改其原始代码库的情况下进行扩展。您可以通过新的插件或模块增强其功能。有关服务提供者和可扩展应用程序的更多信息，请参阅创建可扩展应用程序。

您可以使用国际化的服务提供者来提供以下区域敏感类的自定义实现：

• BreakIterator 对象

• Collator 对象

• Locale 类的语言代码、国家代码和变体名称

• 时区名称

• 货币符号

• DateFormat 对象

• DateFormatSymbols 对象

• NumberFormat 对象

• DecimalFormatSymbols 对象

相应的 SPI 包含在java.text.spi和java.util.spi包中：

|

• CurrencyNameProvider

• LocaleServiceProvider

• TimeZoneNameProvider

|

• BreakIteratorProvider

• CollatorProvider

• DateFormatProvider

• DateFormatSymbolsProvider

• DecimalFormatSymbolsProvider

• NumberFormatProvider

|

例如，如果您想为新的区域设置提供一个NumberFormat对象，请实现java.text.spi.NumberFormatProvider类并实现以下方法：

• getCurrencyInstance(Locale locale)

• getIntegerInstance(Locale locale)

• getNumberInstance(Locale locale)

• getPercentInstance(Locale locale)

Locale loc = new Locale("da", "DK");
NumberFormat nf = NumberFormatProvider.getNumberInstance(loc);

这些方法首先检查 Java 运行时环境是否支持请求的区域设置；如果支持，则使用该支持。否则，方法会调用已安装提供者的适当接口的getAvailableLocales方法，以找到支持请求的区域设置的提供者。

要深入了解如何使用国际化服务提供者的示例，请参阅将自定义资源包作为扩展安装。本节展示了如何实现ResourceBundleControlProvider接口，使您能够在不对应用程序源代码进行任何其他更改的情况下使用任何自定义ResourceBundle.Control类。

安装自定义资源包作为扩展

原文：docs.oracle.com/javase/tutorial/i18n/serviceproviders/resourcebundlecontrolprovider.html

自定义资源包加载部分向您展示如何更改资源包的加载方式。这涉及从类ResourceBundle.Control派生一个新类，然后通过调用以下方法检索资源包：

ResourceBundle getBundle(
  String baseName,
  Locale targetLocale,
  ResourceBundle.Control control)

参数control是您对ResourceBundle.Control的实现。

java.util.spi.ResourceBundleControlProvider接口使您能够更改以下方法加载资源包的方式：

ResourceBundle getBundle(
  String baseName,
  Locale targetLocale)

请注意，此版本的ResourceBundle.getBundle方法不需要ResourceBundle.Control类的实例。ResourceBundleControlProvider是一个服务提供者接口（SPI）。SPI 使您能够创建可扩展的应用程序，即可以在不修改其原始代码库的情况下轻松扩展的应用程序。有关更多信息，请参阅创建可扩展应用程序。

要使用 SPI，首先通过实现类似ResourceBundleControlProvider的 SPI 来创建一个服务提供者。当您实现一个 SPI 时，您指定它将如何提供服务。ResourceBundleControlProvider SPI 提供的服务是在应用程序调用方法ResourceBundle.getBundle(String baseName, Locale targetLocale)时获取适当的ResourceBundle.Control实例。您将服务提供者与 Java 扩展机制一起打包为已安装的扩展。运行应用程序时，不需要在类路径中命名您的扩展；运行时环境会找到并加载这些扩展。

已安装的ResourceBundleControlProvider SPI 实现将替换默认的ResourceBundle.Control类（定义了默认的包加载过程）。因此，ResourceBundleControlProvider接口使您可以使用任何自定义的ResourceBundle.Control类，而无需对应用程序的源代码进行任何其他更改。此外，该接口使您能够编写应用程序，而无需引用任何自定义的ResourceBundle.Control类。

RBCPTest.java示例展示了如何实现ResourceBundleControlProvider接口以及如何将其打包为已安装的扩展。这个示例被打包在 zip 文件RBCPTest.zip中，包含以下文件：

• src

  • java.util.spi.ResourceBundleControlProvider

  • RBCPTest.java

  • rbcp

    • PropertiesResourceBundleControl.java

    • PropertiesResourceBundleControlProvider.java

    • XMLResourceBundleControl.java

    • XMLResourceBundleControlProvider.java

  • resources

    • RBControl.properties

    • RBControl_zh.properties

    • RBControl_zh_CN.properties

    • RBControl_zh_HK.properties

    • RBControl_zh_TW.properties

    • XmlRB.xml

    • XmlRB_ja.xml

• lib

  • rbcontrolprovider.jar

• build：包含所有打包在rbcontrolprovider.jar中的文件以及类文件RBCPTest.class

• build.xml

以下步骤展示了如何重新创建文件RBCPTest.zip的内容，RBCPTest示例的工作原理以及如何运行它：

1. 创建 ResourceBundle.Control 类的实现。

2. 实现 ResourceBundleControlProvider 接口。

3. 在应用程序中调用 ResourceBundle.getBundle 方法。

4. 通过创建配置文件注册服务提供者。

5. 将提供者、其所需的类以及配置文件打包到一个 JAR 文件中。

6. 运行 RBCPTest 程序。

1. 创建 ResourceBundle.Control 类的实现。

RBCPTest.java 示例使用了两种ResourseBundle.Control的实现：

• PropertiesResourceBundleControlProvider.java：这是在自定义资源包加载中定义的相同ResourceBundle.Control实现。

• XMLResourceBundleControl.java：这个ResourceBundle.Control实现使用Properties.loadFromXML方法加载基于 XML 的包。

XML 属性文件

如在 使用属性文件支持 ResourceBundle 部分所述，属性文件是简单的文本文件。它们每行包含一个键值对。XML 属性文件与属性文件类似：它们包含键值对，只是具有 XML 结构。以下是 XML 属性文件 XmlRB.xml：

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE properties [
<!ELEMENT properties ( comment?, entry* ) >
<!ATTLIST properties version CDATA #FIXED "1.0">
<!ELEMENT comment (#PCDATA) >
<!ELEMENT entry (#PCDATA) >
<!ATTLIST entry key CDATA #REQUIRED>
]>

<properties>
    <comment>Test data for RBCPTest.java</comment>
    <entry key="type">XML</entry>
</properties>

以下是等效的属性文本文件：

# Test data for RBCPTest.java
type = XML

所有 XML 属性文本文件具有相同的结构：

• 指定文档类型定义（DTD）的 DOCTYPE 声明：DTD 定义了 XML 文件的结构。注意：在 XML 属性文件中，你可以使用以下 DOCTYPE 声明：

  <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">  
  
  

  系统 URI (http://java.sun.com/dtd/properties.dtd) 在导出或导入属性时不会被访问；它是一个唯一标识 XML 属性文件的 DTD 的字符串。

• 根元素 <properties>：此元素包含所有其他元素。

• 任意数量的 <comment> 元素：用于注释。

• 任意数量的 <entry> 元素：使用属性 key 指定键；在 <entry> 标签之间指定键的值。

查看 Properties 类以获取有关 XML 属性文件的更多信息。

2. 实现 ResourceBundleControlProvider 接口。

这个接口包含一个方法，ResourceBundle.Control getControl(String baseName) 方法。参数 baseName 是资源包的名称。在 getBundle 方法的定义中，指定应返回的 ResourceBundle.Control 实例，给定资源包的名称。

RBCPTest 示例包含 ResourceBundleControlProvider 接口的两个实现，PropertiesResourceBundleControlProvider.java 和 XMLResourceBundleControlProvider.java。如果资源包的基本名称以 resources.RBControl 开头，则方法 PropertiesResourceBundleControlProvider.getBundle 返回 PropertiesResourceBundleControl 的实例（在此示例中，所有资源文件都包含在 resources 包中）：

package rbcp;

import java.util.ResourceBundle;
import java.util.spi.ResourceBundleControlProvider;

public class PropertiesResourceBundleControlProvider
    implements ResourceBundleControlProvider {
    static final ResourceBundle.Control PROPERTIESCONTROL =
        new PropertiesResourceBundleControl();

    public ResourceBundle.Control getControl(String baseName) {
        System.out.println("Class: " + getClass().getName() + ".getControl");
        System.out.println("    called for " + baseName);

        // Throws a NPE if baseName is null.
        if (baseName.startsWith("resources.RBControl")) {
            System.out.println("    returns " + PROPERTIESCONTROL);
            return PROPERTIESCONTROL;
        }
        System.out.println("    returns null");
        System.out.println();
        return null;
    }
}

类似地，如果资源包的基本名称以 resources.Xml 开头，则方法 XMLResourceBundleControlProvider.getControl 返回 XMLResourceBundleControl 的实例。

注意：你可以创建一个实现 ResourceBundleControlProvider 接口的实现，根据基本名称返回 PropertiesResourceBundleControl 或 XMLResourceBundleControl 的实例。

3. 在你的应用程序中，调用方法 ResourceBundle.getBundle。

类RBCPTest使用方法ResourceBundle.getBundle检索资源包：

import java.io.*;
import java.net.*;
import java.util.*;

public class RBCPTest {
    public static void main(String[] args) {
        ResourceBundle rb = ResourceBundle.getBundle(
            "resources.XmlRB", Locale.ROOT);
        String type = rb.getString("type");
        System.out.println("Root locale. Key, type: " + type);
        System.out.println();

        rb = ResourceBundle.getBundle("resources.XmlRB", Locale.JAPAN);
        type = rb.getString("type");
        System.out.println("Japan locale. Key, type: " + type);
        System.out.println();

        test(Locale.CHINA);
        test(new Locale("zh", "HK"));
        test(Locale.TAIWAN);
        test(Locale.CANADA);
    }

    private static void test(Locale locale) {
        ResourceBundle rb = ResourceBundle.getBundle(
            "resources.RBControl", locale);
        System.out.println("locale: " + locale);
        System.out.println("    region: " + rb.getString("region"));
        System.out.println("    language: " + rb.getString("language"));
        System.out.println();
    }
}

请注意，此类中没有ResourceBundle.Control或ResourceBundleControlProvider的实现。因为ResourceBundleControlProvider接口使用 Java 扩展机制，运行时环境会找到并加载这些实现。但是，使用 Java 扩展机制安装的ResourceBundleControlProvider实现和其他服务提供程序是使用ServiceLoader类加载的。使用此类意味着您必须使用配置文件注册服务提供程序，下一步将对此进行描述。

4. 通过创建配置文件注册服务提供程序。

配置文件的名称是提供程序实现的接口或类的完全限定名称。配置文件包含您的提供程序的完全限定类名。文件java.util.spi.ResourceBundleControlProvider包含PropertiesResourceBundleControlProvider和XMLResourceBundleControlProvider的完全限定名称，每行一个名称：

rbcp.XMLResourceBundleControlProvider
rbcp.PropertiesResourceBundleControlProvider

5. 将提供程序、其所需类和配置文件打包到 JAR 文件中。

编译源文件。从包含build.xml文件的目录中，运行以下命令：

javac -d build src/java.* src/rbcp/*.java

此命令将编译src目录中包含的源文件，并将类文件放在build目录中。在 Windows 上，请确保使用反斜杠（\）来分隔目录和文件名。

创建一个 JAR 文件，其中包含编译的类文件、资源文件和配置文件，目录结构如下：

• META-INF

  • services

    • java.util.spi.ResourceBundleControlProvider

• rbcp

  • PropertiesResourceBundleControl.class

  • PropertiesResourceBundleControlProvider.class

  • XMLResourceBundleControl.class

  • XMLResourceBundleControlProvider.class

• 资源

  • RBControl.properties

  • RBControl_zh.properties

  • RBControl_zh_CN.properties

  • RBControl_zh_HK.properties

  • RBControl_zh_TW.properties

  • XmlRB.xml

  • XmlRB_ja.xml

注意，配置文件java.util.spi.ResourceBundleControlProvider必须打包在目录/META-INF/services中。此示例将这些文件打包在lib目录中的 JAR 文件rbcontrolprovider.jar中。

查看在 JAR 文件中打包程序以获取有关创建 JAR 文件的更多信息。

或者，下载并安装Apache Ant，这是一个可以帮助您自动化构建过程的工具，例如编译 Java 文件和创建 JAR 文件。确保 Apache Ant 可执行文件在您的PATH环境变量中，以便您可以从任何目录运行它。安装 Apache Ant 后，请按照以下步骤操作：

1. 编辑文件build.xml，将${JAVAC}更改为您的 Java 编译器javac的完整路径名，并将${JAVA}更改为您的 Java 运行时可执行文件java的完整路径名。

2. 从包含文件build.xml的相同目录运行以下命令：

   ant jar
   

   这个命令编译 Java 源文件并将它们与所需的资源和配置文件打包到lib目录中的 JAR 文件rbcontrolprovider.jar中。

6. 运行 RBCPTest 程序。

在命令提示符下，从包含build.xml文件的目录运行以下命令：

java -Djava.ext.dirs=lib -cp build RBCPTest

此命令假定以下情况：

• 包含 RBCPTest 示例编译代码的 JAR 文件位于lib目录中。

• 编译后的类RBCPTest.class位于build目录中。

或者，使用 Apache Ant，并从包含build.xml文件的目录运行以下命令：

ant run

当您安装 Java 扩展时，通常将扩展的 JAR 文件放在 JRE 的lib/ext目录中。但是，此命令使用系统属性java.ext.dirs指定包含 Java 扩展的目录。

RBCPTest程序首先尝试使用基本名称为resources.XmlRB和区域设置为Locale.ROOT和Local.JAPAN的资源包。程序检索这些资源包的输出类似于以下内容：

Class: rbcp.XMLResourceBundleControlProvider.getControl
    called for resources.XmlRB
    returns rbcp.XMLResourceBundleControl@16c1857
Root locale. Key, type: XML

Class: rbcp.XMLResourceBundleControlProvider.getControl
    called for resources.XmlRB
    returns rbcp.XMLResourceBundleControl@16c1857
Japan locale. Key, type: Value from Japan locale

该程序成功获取XMLResourceBundleControl的实例并访问属性文件XmlRB.xml和XmlRB_ja.xml。

当RBCPTest程序尝试检索资源包时，它调用配置文件java.util.spi.ResourceBundleControlProvider中定义的所有类。例如，当程序检索基本名称为resources.RBControl和区域设置为Locale.CHINA的资源包时，它打印以下输出：

Class: rbcp.XMLResourceBundleControlProvider.getControl
    called for resources.RBControl
    returns null

Class: rbcp.PropertiesResourceBundleControlProvider.getControl
    called for resources.RBControl
    returns rbcp.PropertiesResourceBundleControl@1ad2911
locale: zh_CN
    region: China
    language: Simplified Chinese

教程：2D 图形

原文：docs.oracle.com/javase/tutorial/2d/index.html

本教程向你介绍了 Java 2D™ API，并展示了如何在 Java 程序中显示和打印 2D 图形。本教程适用于希望丰富其对 Java 2D API 知识的开发人员，以及计算机图形初学者。几乎每个部分都包含相关示例来说明特定功能。Java 2D API 可以轻松执行以下任务：

• 绘制线条、矩形和任何其他几何形状。

• 用纯色、渐变和纹理填充这些形状。

• 使用选项绘制文本，对字体和渲染过程进行精细控制。

• 绘制图像，可选择应用滤镜操作。

• 在上述任何渲染操作期间应用诸如合成和变换等操作。

本章还解释了较不熟悉的概念，如合成。

使用 2D 图形 API 显示复杂图表

使用图像滤镜操作

本章描述了在屏幕和离屏图像、表面和打印机设备上绘制的概念。本教程涵盖了 Java 2D API 的最常见用法，并简要描述了一些更高级功能。

介绍了关键的 Java 2D 概念，并描述了 Java 2D 渲染模型。这节课比本教程的其他课程更具概念性，它让你深入了解基本概念和类描述。

使用一个开发的示例向你展示如何获取 Graphics 对象并将其用于常见的图形渲染任务。

教你如何使用 API 绘制图形基元和任意形状，以及如何应用花哨的描边和填充样式。

展示了如何有效地使用文本 API，包括如何创建具有所需属性的Font对象，测量文本，并确定系统中可用字体的名称。

解释了如何创建 BufferedImage 对象，执行图像滤镜操作，并在图像上绘制。

教你如何将 2D 图形渲染到打印机，打印复杂文档，并使用打印服务。

解释了如何执行变换，裁剪绘图区域，合成重叠图形，指定渲染偏好，并控制渲染质量。

课程：Java 2D API 概念概述

原文：docs.oracle.com/javase/tutorial/2d/overview/index.html

Java 2D API 通过对抽象窗口工具包（AWT）的扩展，为 Java 程序提供了二维图形、文本和图像功能。这个全面的渲染包支持线条艺术、文本和图像，提供了一个灵活、功能齐全的框架，用于开发更丰富的用户界面、复杂的绘图程序和图像编辑器。Java 2D 对象存在于一个称为用户坐标空间或用户空间的平面上。当对象在屏幕或打印机上呈现时，用户空间坐标被转换为设备空间坐标。以下链接对开始学习 Java 2D API 很有帮助：

• Graphics类

• Graphics2D类

Java 2D API 提供以下功能：

• 用于显示设备和打印机的统一渲染模型

• 一系列几何基元，如曲线、矩形和椭圆，以及一种渲染几乎任何几何形状的机制

• 用于在形状、文本和图像上执行命中检测的机制

• 一个合成模型，提供对重叠对象如何呈现的控制

• 增强的颜色支持，有助于颜色管理

• 支持打印复杂文档

• 通过使用渲染提示控制渲染质量

这些主题在以下章节中讨论：

• Java 2D 渲染

• 几何基元

• 文本

• 图像

• 打印

坐标

原文：docs.oracle.com/javase/tutorial/2d/overview/coordinate.html

Java 2D API 维护两个坐标空间：

• 用户空间 – 指定图形基元的空间

• 设备空间 – 输出设备（如屏幕、窗口或打印机）的坐标系统

用户空间是一个设备无关的逻辑坐标系统，即您的程序使用的坐标空间。传递给 Java 2D 渲染例程的所有几何图形都是使用用户空间坐标指定的。

当使用从用户空间到设备空间的默认转换时，用户空间的原点是组件绘图区域的左上角。x坐标向右增加，y坐标向下增加，如下图所示。窗口的左上角是 0,0。所有坐标都使用整数指定，通常足够。但是，有些情况需要浮点数甚至双精度，这也是支持的。

设备空间是一个依赖设备的坐标系统，根据目标渲染设备而变化。虽然窗口或屏幕的坐标系统可能与打印机的坐标系统非常不同，但这些差异对 Java 程序是不可见的。在渲染过程中，用户空间和设备空间之间的必要转换是自动执行的。

Java 2D 渲染

原文：docs.oracle.com/javase/tutorial/2d/overview/rendering.html

Java 2D API 在不同类型设备上提供统一的渲染模型。在应用程序级别，无论目标渲染设备是屏幕还是打印机，渲染过程都是相同的。当需要显示组件时，其paint或update方法会自动使用适当的Graphics上下文调用。

Java 2D API 包括java.awt.Graphics2D类，该类扩展了Graphics类，以提供对 Java 2D API 增强图形和渲染功能的访问。这些功能包括：

• 渲染任何几何原语的轮廓，使用笔画和填充属性（draw 方法）。

• 通过使用颜色或图案指定的填充属性（fill 方法）来填充任何几何原语的内部。

• 渲染任何文本字符串（drawString 方法）。字体属性用于将字符串转换为字形，然后用颜色或图案指定的填充。

• 渲染指定的图像（drawImage 方法）。

此外，Graphics2D类支持特定形状的drawOval和fillRect等Graphics渲染方法。上面列出的所有方法可以分为两组：

1. 绘制形状的方法

2. 影响渲染的方法

第二组方法使用形成Graphics2D上下文的状态属性，用于以下目的：

• 变化笔画宽度

• 更改如何连接笔画

• 设置裁剪路径以限制渲染区域

• 在渲染对象时平移、旋转、缩放或倾斜对象

• 定义颜色和图案以填充形状

• 指定如何组合多个图形对象

在应用程序中使用 Java 2D API 功能，将传递给组件渲染方法的Graphics对象转换为Graphics2D对象。例如：

public void paint (Graphics g) {
    Graphics2D g2 = (Graphics2D) g;
    ...
}

如下图所示，Graphics2D类的渲染上下文包含几个属性。

	笔属性应用于形状的轮廓。此笔画属性使您能够用任何点大小和虚线模式绘制线条，并对线条应用端点和连接装饰。
	填充属性应用于形状的内部。此填充属性使您能够用纯色、渐变和图案填充形状。
	compositing attribute 在渲染对象重叠现有对象时使用。
	transform 属性在渲染过程中应用，将渲染对象从用户空间转换为设备空间坐标。通过该属性还可以应用可选的平移、旋转、缩放或剪切变换。
	clip 类型将渲染限制在用于定义剪切路径的 Shape 对象轮廓内的区域。任何用于定义剪切的 Shape 对象。
	font 属性用于将文本字符串转换为字形。
	Rendering hints 指定在速度和质量之间的权衡偏好。例如，您可以指定是否应使用抗锯齿，如果该功能可用的话。另请参阅 控制渲染质量。

要了解更多关于变换和合成的内容，请参阅 Java2D 中的高级主题。

当设置属性时，会传递适当的属性对象。如下例所示，要将绘画属性更改为蓝绿色渐变填充，您需要构造一个 GradientPaint 对象，然后调用 setPaint 方法。

gp = new GradientPaint(0f,0f,blue,0f,30f,green);
g2.setPaint(gp);

几何基元

原文：docs.oracle.com/javase/tutorial/2d/overview/primitives.html

Java 2D API 提供了一组有用的标准形状，如点、线、矩形、弧、椭圆和曲线。定义常见几何基元的最重要的包是java.awt.geom包。任意形状可以由直线几何基元的组合表示。

Shape接口表示具有轮廓和内部的几何形状。此接口提供了一组用于描述和检查二维几何对象的常见方法，并支持曲线线段和多个子形状。Graphics类仅支持直线段。Shape接口可以支持曲线段。

关于如何绘制和填充形状的更多详细信息，请参阅几何处理课程。

点

Point2D类定义了表示(x, y)坐标空间中位置的点。Java 2D API 中的术语“点”与像素不同。点没有面积，不包含颜色，也不能呈现。

点用于创建其他形状。Point2D类还包括一种计算两点之间距离的方法。

线

Line2D类是表示一条线的抽象类。线的坐标可以作为双精度数检索。Line2D类包括几种设置线端点的方法。

您还可以使用下面描述的GeneralPath类创建直线段。

矩形形状

Rectangle2D、RoundRectangle2D、Arc2D和Ellipse2D基元都是从RectangularShape类派生的。此类定义了可以由矩形边界框描述的Shape对象的方法。RectangularShape对象的几何形状可以从完全包围Shape轮廓的矩形中推断出来。

二次和三次曲线

QuadCurve2D使您能够创建二次参数曲线段。二次曲线由两个端点和一个控制点定义。

CubicCurve2D类使您能够创建三次参数曲线段。三次曲线由两个端点和两个控制点定义。以下是二次和三次曲线的示例。请参阅描边和填充图形基元以获取三次和二次曲线的实现。

此图表示一个二次曲线。

此图表示一个三次曲线。

任意形状

GeneralPath类使您能够通过指定沿着形状边界的一系列位置来构造任意形状。这些位置可以通过线段、二次曲线或三次（贝塞尔）曲线连接。以下形状可以通过三条线段和一条三次曲线创建。有关此形状实现的更多信息，请参见描边和填充图形基元。

区域

使用Area类，您可以对任意两个Shape对象执行布尔运算，如并集、交集和差集。这种技术通常被称为构造性区域几何，使您能够快速创建复杂的Shape对象，而无需描述每条线段或曲线。

文本

原文：docs.oracle.com/javase/tutorial/2d/overview/text.html

Java 2D API 具有各种文本渲染功能，包括用于呈现字符串的方法以及用于设置字体属性和执行文本布局的整个类。

如果您只想绘制静态文本字符串，最直接的方法是通过Graphics类使用drawString方法直接呈现它。要指定字体，您可以使用Graphics类的setFont方法。

如果您想要实现自己的文本编辑例程或需要比文本组件提供的更多对文本布局的控制，您可以使用java.awt.font包中的 Java 2D 文本布局类。

字体

字体用于表示字符串中字符的形状称为字形。特定字符或字符组合可能表示为一个或多个字形。例如，á可能由两个字形表示，而连字fi可能由一个字形表示。

字体可以被视为一组字形。单个字体可能有许多面孔，如斜体和常规。字体中的所有面孔具有类似的印刷特征，并且可以被识别为同一字体系列的成员。换句话说，具有特定样式的一组字形形成一个字体面孔。一组字体面孔形成一个字体系列。字体系列的集合形成了系统中可用的字体集。

当您使用 Java 2D API 时，您可以通过使用Font的实例来指定字体。您可以通过调用静态方法GraphicsEnvironment.getLocalGraphicsEnvironment并查询返回的GraphicsEnvironment来确定可用的字体。getAllFonts方法返回一个包含系统上所有可用字体的Font实例数组。getAvailableFontFamilyNames方法返回可用字体系列的列表。

文本布局

在文本可以显示之前，必须对其进行布局，以便字符以适当的位置表示为适当的字形。以下是两种用于管理文本布局的 Java 2D 机制：

• TextLayout类管理文本布局、高亮显示和命中检测。TextLayout提供的功能处理最常见的情况，包括具有混合字体、混合语言和双向文本的字符串。

• 您可以通过使用Font类创建自己的GlyphVector对象，然后通过Graphics2D类渲染每个GlyphVector对象。因此，您可以完全控制文本的形状和位置。

文本的渲染提示

Java 2D API 使您能够通过使用渲染提示来控制形状和文本渲染的质量。渲染提示由java.awt.RenderingHints类封装。

当应用于文本时，这种能力用于抗锯齿（也称为平滑边缘）。例如，KEY_TEXT_ANTIALIASING提示可以让您单独控制文本的抗锯齿效果，而不影响其他形状的抗锯齿效果。要了解更多关于渲染提示的信息，请参阅控制渲染质量课程。

图像

原文：docs.oracle.com/javase/tutorial/2d/overview/images.html

在 Java 2D API 中，图像通常是一个矩形的二维像素数组，其中每个像素表示图像该位置的颜色，而维度表示图像显示时的水平范围（宽度）和垂直范围（高度）。

表示此类图像最重要的图像类是java.awt.image.BufferedImage类。Java 2D API 将这些图像的内容存储在内存中，以便可以直接访问。

应用程序可以直接创建一个BufferedImage对象，或从外部图像格式（如 PNG 或 GIF）获取图像。

在任一情况下，应用程序可以通过使用 Java 2D API 图形调用在图像上绘制。因此，图像不仅限于显示照片类型的图像。不同的对象，如线条艺术、文本和其他图形，甚至其他图像都可以绘制到图像上（如下图所示）。

Java 2D API 允许您对BufferedImage应用图像过滤操作，并包括几个内置过滤器。例如，ConvolveOp过滤器可用于模糊或锐化图像。

然后生成的图像可以绘制到屏幕上，发送到打印机上，或保存为 PNG、GIF 等图形格式。要了解更多关于图像的信息，请参阅使用图像课程。

打印

原文：docs.oracle.com/javase/tutorial/2d/overview/printing.html

所有的 Swing 和 Java 2D 图形，包括合成图形和图像，都可以通过使用 Java 2D Printing API 渲染到打印机上。该 API 还提供文档组合功能，使您能够执行诸如更改打印页面顺序之类的操作。

渲染到打印机就像渲染到屏幕一样。打印系统控制何时渲染页面，就像绘图系统控制组件何时在屏幕上绘制一样。

Java 2D Printing API 基于回调模型，其中打印系统而不是应用程序控制打印页面的时间。应用程序向打印系统提供要打印的文档信息，打印系统确定何时需要成像每一页。

以下两个功能对支持打印很重要：

• 作业控制 – 启动和管理打印作业，包括显示标准打印和设置对话框

• 分页 – 在打印系统请求时呈现每一页

当需要成像页面时，打印系统使用适当的Graphics上下文调用应用程序的print方法。要在打印时使用 Java 2D API 功能，您将Graphics对象转换为Graphics2D类，就像在渲染到屏幕时一样。

教程：开始使用图形

原文：docs.oracle.com/javase/tutorial/2d/basic2d/index.html

Java 2D API 强大而复杂。然而，Java 2D API 的绝大多数用途利用了java.awt.Graphics类中封装的其功能的一个小子集。本课程涵盖了应用程序开发人员最常见的需求。较少常见的需求稍后在 Java 2D API 的高级主题中描述。

Graphics类的大多数方法可以分为两个基本组：

• 绘制和填充方法，使您能够渲染基本形状、文本和图像

• 设置属性的方法，影响绘制和填充的外观

诸如setFont和setColor之类的方法定义了如何渲染绘制和填充方法。

本图说明了这些方法与图形对象的关系：

绘制方法包括：

• drawString – 用于绘制文本

  g.drawString("Hello", 10, 10);
  
  

• drawImage – 用于绘制图像

  g.drawImage(img, 
              0, 0, width, height,
              0, 0, imageWidth, imageHeight,
              null);                    
  
  

• drawLine，drawArc，drawRect，drawOval，drawPolygon – 用于绘制几何形状

  g2.draw(new Line2D.Double(0, 0, 30, 40));
  
  

根据您当前的需求，您可以根据以下标准在Graphics类中选择几种方法之一：

• 无论您想要在指定位置以原始大小渲染图像还是将其缩放以适应给定矩形

• 无论您喜欢用颜色填充图像的透明区域还是保持其透明

填充方法适用于几何形状，包括fillArc，fillRect，fillOval，fillPolygon。

无论您绘制文本还是图像，记住在 2D 图形中，每个点由其 x 和 y 坐标确定。所有绘制和填充方法都需要这些信息，这些信息确定了文本或图像应该渲染在哪里。

例如，要绘制一条线，应用程序调用以下代码：

java.awt.Graphics.drawLine(int x1, int y1, int x2, int y2)

在此代码中(x1, y1)是线的起点，(x2, y2)是线的终点。

因此，绘制水平线的代码如下：

Graphics.drawLine(20, 100, 120, 100);

下面的演示累积了所有提到的技术。移动滑块以显示各种天气类型。

WeatherWizard 演示使用 JSlider 组件以及各种图形功能来生成和显示指定的天气类型。有关 JSlider 类的更多信息，请参阅 Swing 教程的 How to Use Sliders 部分。

WeatherPainter 类的 paint 方法实现了图形特性。以下代码使用 setupWeatherReport() 方法绘制了一个图像。

...
origComposite = g2.getComposite();
if (alpha0 != null) g2.setComposite(alpha0);
g2.drawImage(img0,
             0, 0, size.width, size.height,
             0, 0, img0.getWidth(null),
             img0.getHeight(null), null);
if (img1 != null) {
    if (alpha1 != null) g2.setComposite(alpha1);
    g2.drawImage(img1,
                 0, 0, size.width, size.height,
                 0, 0, img1.getWidth(null),
                 img1.getHeight(null), null);
} 
...

setFont 和 drawString 方法渲染温度和天气状况。

...
// Freezing, Cold, Cool, Warm, Hot,
// Blue, Green, Yellow, Orange, Red
Font font = new Font("Serif", Font.PLAIN, 36);
g.setFont(font);

String tempString = feels + " " + temperature+"F";
FontRenderContext frc =
           ((Graphics2D)g).getFontRenderContext();
...
g.setColor(textColor);
int xTextTemp = rX-(int)boundsTemp.getX();
int yTextTemp = rY-(int)boundsTemp.getY();
g.drawString(tempString, xTextTemp, yTextTemp);

int xTextCond = rX-(int)boundsCond.getX();
int yTextCond = rY-(int)boundsCond.getY()
                   + (int)boundsTemp.getHeight();
g.drawString(condStr, xTextCond, yTextCond);

fillRect 方法允许您绘制一个填充了指定颜色的矩形。

...
Rectangle2D boundsTemp 
          = font.getStringBounds(tempString, frc);
Rectangle2D boundsCond 
          = font.getStringBounds(condStr, frc);
int wText = Math.max((int)boundsTemp.getWidth(),
            (int)boundsCond.getWidth());
int hText = (int)boundsTemp.getHeight()
            + (int)boundsCond.getHeight();
int rX = (size.width-wText)/2;
int rY = (size.height-hText)/2;

g.setColor(Color.LIGHT_GRAY);
g2.fillRect(rX, rY, wText, hText);
...

尝试修改 WeatherWizard 演示以更改图形内容。例如，使用 fillRoundRect 方法代替 fillRect 或在 setFont 方法中应用另一个字体大小。在 WeatherWizard.java 文件中找到此小程序的完整代码。演示还需要以下图像：weather-cloud.png, weather-rain.png, weather-snow.png 和 weather-sun.png，这些图像位于 images 目录中。

教程：与几何形状一起工作

原文：docs.oracle.com/javase/tutorial/2d/geometry/index.html

在之前的课程中，您已经学习了关于图形概念的知识，包括关于坐标系和图形对象创建的基本信息。现在，您将进一步学习有关 2D 图形类的详细课程。本课程将向您展示如何使用Graphics2D类绘制图形基元以及任意形状，以及如何使用花哨的轮廓和填充样式显示图形。这些主题将在以下部分讨论。

绘制几何基元

这一部分解释了如何创建标准形状，如点、线、曲线、弧线、矩形和椭圆。

绘制任意形状

这一部分解释了如何使用GeneralPath类绘制由直线几何基元组合表示的形状。

填充和描边

这一部分解释了如何设置描边和填充属性，以控制应用于Shape对象和文本的轮廓和填充样式。

绘制几何图元

原文：docs.oracle.com/javase/tutorial/2d/geometry/primitives.html

Java 2D API 提供了几个定义常见几何对象（如点、线、曲线和矩形）的类。这些几何类是java.awt.geom包的一部分。

PathIterator接口定义了从路径中检索元素的方法。

Shape接口提供了一组描述和检查几何路径对象的方法。该接口由GeneralPath类和其他几何类实现。

本节中的所有示例都是通过使用java.awt.geom包创建几何图形，然后通过使用Graphics2D类来呈现它们。首先，您需要获取一个Graphics2D对象，例如通过将paint()方法的Graphics参数进行强制转换。

public void paint (Graphics g) {
    Graphics2D g2 = (Graphics2D) g;
    ...
}

点

Point类创建一个表示(x,y)坐标空间中位置的点。子类Point2D.Float和Point2D.Double分别提供存储点坐标的浮点和双精度。

//Create Point2D.Double
Point2D.Double point = new Point2D.Double(x, y);

要创建坐标为 0,0 的点，您可以使用默认构造函数Point2D.Double()。

您可以使用setLocation方法设置点的位置如下：

• setLocation(double x, double y) – 以双精度值设置点的位置-定义坐标。

• setLocation(Point2D p) – 使用另一个点的坐标设置点的位置。

此外，Point2D类有方法来计算当前点与给定坐标点之间的距离，或者两点之间的距离。

线

Line2D类表示(x, y)坐标空间中的线段。Line2D.Float和Line2D.Double子类指定了浮点和双精度的线。例如：

// draw Line2D.Double
g2.draw(new Line2D.Double(x1, y1, x2, y2));

该类包括几个setLine()方法来定义线的端点。

或者，可以使用Line2D.Float类的构造函数指定线的端点如下：

• Line2D.Float(float X1, float Y1, float X2, float Y2)

• Line2D.Float(Point2D p1, Point2D p2)

在Graphics2D类中使用 Stroke 对象定义线路径的笔画。

曲线

java.awt.geom包使您能够创建二次或三次曲线段。

二次曲线段

QuadCurve2D类实现了Shape接口。该类表示(x, y)坐标空间中的二次参数曲线段。QuadCurve2D.Float和QuadCurve2D.Double子类指定了浮点和双精度的二次曲线。

几个setCurve方法用于指定曲线的两个端点和控制点，其坐标可以直接定义，通过其他点的坐标定义，或使用给定数组。

一个非常有用的方法，setCurve(QuadCurve2D)，设置具有与提供的曲线相同端点和控制点的二次曲线。例如：

// create new QuadCurve2D.Float
QuadCurve2D q = new QuadCurve2D.Float();
// draw QuadCurve2D.Float with set coordinates
q.setCurve(x1, y1, ctrlx, ctrly, x2, y2);
g2.draw(q);

三次曲线段

CubicCurve2D类还实现了Shape接口。该类表示(x, y)坐标空间中的三次参数曲线段。CubicCurve2D.Float和CubicCurve2D.Double子类指定了浮点和双精度的三次曲线。

CubicCurve2D类具有设置曲线的类似方法，与QuadraticCurve2D类相同，只是有第二个控制点。例如：

// create new CubicCurve2D.Double
CubicCurve2D c = new CubicCurve2D.Double();
// draw CubicCurve2D.Double with set coordinates
c.setCurve(x1, y1, ctrlx1,
           ctrly1, ctrlx2, ctrly2, x2, y2);
g2.draw(c);

矩形

在下面的示例中表示的原语的类扩展了RectangularShape类，该类实现了Shape接口并添加了一些自己的方法。

这些方法使您能够获取有关形状位置和大小的信息，检查矩形的中心点，并设置形状的边界。

Rectangle2D类表示由位置(x, y)和尺寸(w x h)定义的矩形。Rectangle2D.Float和Rectangle2D.Double子类指定了浮点和双精度的矩形。例如：

// draw Rectangle2D.Double
g2.draw(new Rectangle2D.Double(x, y,
                               rectwidth,
                               rectheight));

RoundRectangle2D类表示具有圆角的矩形，由位置(x, y)、尺寸(w x h)和圆角的宽度和高度定义。RoundRectangle2D.Float和RoundRectangle2D.Double子类指定了浮点和双精度的圆角矩形。

圆角矩形由以下参数指定：

• 位置

• 宽度

• 高度

• 圆角弧的宽度

• 圆角弧的高度

要设置RoundRectangle2D对象的位置、大小和弧度，请使用方法setRoundRect(double a, double y, double w, double h, double arcWidth, double arcHeight)。例如：

// draw RoundRectangle2D.Double
g2.draw(new RoundRectangle2D.Double(x, y,
                                   rectwidth,
                                   rectheight,
                                   10, 10));

椭圆

Ellipse2D类表示由边界矩形定义的椭圆。Ellipse2D.Float和Ellipse2D.Double子类指定了以浮点和双精度表示的椭圆。

椭圆由位置、宽度和高度完全定义。例如：

// draw Ellipse2D.Double
g2.draw(new Ellipse2D.Double(x, y,
                             rectwidth,
                             rectheight));

弧

要绘制椭圆的一部分，您可以使用Arc2D类。这个类表示由边界矩形、起始角度、角度范围和闭合类型定义的弧。Arc2D.Float和Arc2D.Double子类指定了以浮点和双精度表示的弧。

Arc2D类定义了这个类中对应常量表示的三种弧形：OPEN、PIE 和 CHORD。

有几种方法可以设置弧的大小和参数：

• 直接，通过坐标

• 通过提供的Point2D和Dimension2D

• 通过复制现有的Arc2D

此外，您可以使用setArcByCenter方法来指定从中心点开始的弧，给定其坐标和半径。

// draw Arc2D.Double
g2.draw(new Arc2D.Double(x, y,
                         rectwidth,
                         rectheight,
                         90, 135,
                         Arc2D.OPEN));

ShapesDemo2D.java代码示例包含了所有描述的几何原语的实现。有关本节中所代表的类和方法的更多信息，请参阅java.awt.geom规范。

绘制任意形状

原文：docs.oracle.com/javase/tutorial/2d/geometry/arbitrary.html

您已经学会了如何绘制java.awt.geom包中表示的大多数形状。要创建更复杂的几何图形，如多边形、折线或星形，您可以使用此包中的另一个类GeneralPath。

此类实现了Shape接口，表示由线段、二次曲线和三次曲线构成的几何路径。此类中的三个构造函数可以使用默认绕组规则(WIND_NON_ZERO)、给定的绕组规则(WIND_NON_ZERO或WIND_EVEN_ODD)或指定的初始坐标容量创建GeneralPath对象。绕组规则指定了如何确定路径的内部。

public void paint (Graphics g) {
    Graphics2D g2 = (Graphics2D) g;
    ...
}

要创建一个空的GeneralPath实例，请调用new GeneralPath()，然后使用以下方法向形状添加线段：

• moveTo(float x, float y) – 将路径的当前点移动到给定点

• lineTo(float x, float y) – 向当前路径添加一个直线段

• quadTo(float ctrlx, float ctrly, float x2, floaty2) – 向当前路径添加一个二次曲线段

• curveTo(float ctrlx1, float ctrly1, float ctrlx2, float ctrly2, float x3, floaty3) – 向当前路径添加一个三次曲线段

• closePath() – 关闭当前路径

以下示例说明了如何使用GeneralPath绘制折线：

|

// draw GeneralPath (polyline)
int x2Points[] = {0, 100, 0, 100};
int y2Points[] = {0, 50, 50, 0};
GeneralPath polyline = 
        new GeneralPath(GeneralPath.WIND_EVEN_ODD, x2Points.length);

polyline.moveTo (x2Points[0], y2Points[0]);

for (int index = 1; index < x2Points.length; index++) {
         polyline.lineTo(x2Points[index], y2Points[index]);
};

g2.draw(polyline);

此示例说明了如何使用GeneralPath绘制多边形：

|

// draw GeneralPath (polygon)
int x1Points[] = {0, 100, 0, 100};
int y1Points[] = {0, 50, 50, 0};
GeneralPath polygon = 
        new GeneralPath(GeneralPath.WIND_EVEN_ODD,
                        x1Points.length);
polygon.moveTo(x1Points[0], y1Points[0]);

for (int index = 1; index < x1Points.length; index++) {
        polygon.lineTo(x1Points[index], y1Points[index]);
};

polygon.closePath();
g2.draw(polygon);

请注意，最后两个代码示例之间唯一的区别是closePath()方法。此方法通过向上一次moveTo的坐标绘制一条直线，从而将折线变成多边形。

要将特定路径添加到您的GeneralPath对象的末尾，您可以使用append()方法之一。ShapesDemo2D.java代码示例包含了任意形状的额外实现。

描边和填充图形原语

原文：docs.oracle.com/javase/tutorial/2d/geometry/strokeandfill.html

您已经知道如何创建不同的几何原语和更复杂的形状。本课程教授如何为图形添加一些颜色和花哨的轮廓，并表示填充和描边：

• 填充 - 是用纯色、颜色渐变或纹理图案绘制形状内部的过程

• 描边 - 是绘制形状轮廓的过程，应用描边宽度、线条样式和颜色属性

要将花哨的线条样式和填充图案应用于几何原语，需在呈现之前更改Graphics2D上下文中的描边和绘制属性。例如，通过创建适当的Stroke对象来绘制虚线。在呈现线条之前，将此描边添加到Graphics2D上下文中，调用setStroke方法。同样，通过创建GradientPaint对象并将其添加到Graphics2D上下文中，可以将渐变填充应用于Shape对象。

以下代码行丰富了几何原语的填充和描边上下文：

// draw RoundRectangle2D.Double

final static float dash1[] = {10.0f};
    final static BasicStroke dashed =
        new BasicStroke(1.0f,
                        BasicStroke.CAP_BUTT,
                        BasicStroke.JOIN_MITER,
                        10.0f, dash1, 0.0f);
g2.setStroke(dashed);
g2.draw(new RoundRectangle2D.Double(x, y,
                                   rectWidth,
                                   rectHeight,
                                   10, 10));

// fill Ellipse2D.Double
redtowhite = new GradientPaint(0,0,color.RED,100, 0,color.WHITE);
g2.setPaint(redtowhite);
g2.fill (new Ellipse2D.Double(0, 0, 100, 50));

ShapesDemo2D.java代码示例代表了描边和填充的额外实现。

定义花哨的线条样式和填充图案

使用 Java 2D 的Stroke和Paint类，可以定义花哨的线条样式和填充图案。

线条样式

线条样式由Graphics2D呈现上下文中的描边属性定义。要设置描边属性，需创建一个BasicStroke对象并将其传递给Graphics2D的setStroke方法。

一个BasicStroke对象保存有关线宽、连接样式、端点样式和虚线样式的信息。当使用draw方法呈现Shape时，将使用此信息。

线宽是线条垂直于其轨迹的厚度。线宽以用户坐标单位的float值指定，当使用默认变换时，这些单位大致相当于 1/72 英寸。

连接样式是应用在两条线段相遇处的装饰。BasicStroke支持以下三种连接样式：

JOIN_BEVEL

JOIN_MITER

JOIN_ROUND

端点样式是应用在线段结束处的装饰。BasicStroke支持以下三种端点样式：

CAP_BUTT

CAP_ROUND

CAP_SQUARE

虚线样式定义了沿着线长度应用的不透明和透明部分的模式。虚线样式由一个虚线数组和一个虚线相位定义。虚线数组定义了虚线模式。数组中的交替元素表示用户坐标单位中的虚线长度和虚线之间的空间长度。元素 0 表示第一个虚线，元素 1 表示第一个空格，依此类推。虚线相位是虚线模式中的偏移量，也以用户坐标单位指定。虚线相位指示应用于线的开头的虚线模式的哪个部分。

填充图案

填充图案由Graphics2D渲染上下文中的paint属性定义。要设置paint属性，您需要创建一个实现Paint接口的对象实例，并将其传递给Graphics2D的setPaint方法。

以下三个类实现了Paint接口：Color、GradientPaint和TexturePaint。

要创建一个GradientPaint，您需要指定起始位置和颜色以及结束位置和颜色。渐变沿着连接两个位置的线从一种颜色变化到另一种颜色。例如：

TexturePaint类的图案由BufferedImage类定义。要创建一个TexturePaint对象，您需要指定包含图案的图像和用于复制和锚定图案的矩形。以下图像表示了这个特性：

课程：使用文本 APIs

原文：docs.oracle.com/javase/tutorial/2d/text/index.html

本课程向您介绍了使用文本 API 的概念，以应用文本渲染功能。在本教程中，您已经使用了基本的 Java 2D 文本 API，并知道如何设置字体和位置，以及如何绘制文本。

本课程扩展了该材料，帮助您了解如何使用这些 API，并进一步了解 Java 2D 文本显示的功能。

这些主题将在以下部分中讨论。

物理和逻辑字体

这一部分解释了如何使用Font类的方法来确定系统上可用的字体，创建Font对象，并获取有关字体系列的信息。

测量文本

这一部分解释了如何通过使用FontMetrics类的实例来正确测量文本。

高级文本显示

这一部分解释了如何定位和渲染一段样式文本，显示抗锯齿文本，使用文本属性来设置文本样式，并处理双向文本。

字体概念

原文：docs.oracle.com/javase/tutorial/2d/text/fontconcepts.html

本节介绍了Font类，支持详细字体信息的规范和复杂排版功能的使用。

一个Font对象表示系统上可用的字体集合中的字体面实例。常见字体面的示例包括 Helvetica Bold 和 Courier Bold Italic。一个Font对象关联三个名称：其逻辑名称、族名称和字体面名称：

• 一个Font对象的逻辑名称是映射到系统上可用的特定字体之一的名称。在 Java 中指定Font时，请使用字体面名称而不是逻辑名称。您可以通过调用getName方法从Font中获取逻辑名称。要获取映射到系统上可用的特定字体的逻辑名称列表，请调用java.awt.GraphicsEnvironment.getAvailableFontFamilyNames方法。

  查看物理和逻辑字体以获取更多信息。

• 一个Font对象的族名称是确定跨多个字体面的排版设计的字体族名称，如 Helvetica。通过getFamily方法检索族名称。

• 一个Font对象的字体面名称指的是系统上安装的实际字体。这是您在指定字体时应该使用的名称。通常被称为字体名称。通过调用getFontName检索字体名称。要确定系统上可用的字体面，请调用java.awt.GraphicsEnvironment.getAllFonts方法。

您可以通过getAttributes方法访问有关Font的信息。Font对象的属性包括其名称、大小、变换和字体特征，如粗细和姿势。

一个LineMetrics对象封装了与Font相关的测量信息，如其上升、下降和行间距：

• 上升是基线到上升线的距离。这个距离代表大写字母的典型高度，但有些字符可能会延伸到上升线以上。

• 下降是基线到下行线的距离。大多数字符的最低点将落在下降线内，但有些字符可能会延伸到下行线以下。

• 行间距是推荐的从下行线底部到下一行顶部的距离。

以下图显示了上升线、基线和下行线的位置：

这些信息用于正确定位字符沿着一行，以及相对于彼此定位行。您可以通过getAscent、getDescent和getLeading方法访问这些行度量。您还可以通过LineMetrics类访问有关Font对象的高度、基线以及下划线和删除线特性的信息。

文本布局概念

原文：docs.oracle.com/javase/tutorial/2d/text/textlayoutconcepts.html

在显示一段文本之前，必须使用适当的字形和连字对其进行正确的形状和定位。这个过程被称为文本布局。文本布局过程涉及以下内容：

• 使用适当的字形和连字来形状文本

• 正确排序文本

• 测量和定位文本

用于排列文本的信息也对执行文本操作（如插入符定位、点击检测和高亮显示）是必要的。查看处理双向文本以获取有关这些文本操作的更多信息。

要开发可以部署在国际市场的软件，文本必须以符合适当书写系统规则的方式排列在不同语言中。

本节涵盖以下主题：

• 形状文本

• 排序文本

• 测量和定位文本

形状文本

字形是一个或多个字符的视觉表示。字形的形状、大小和位置取决于其上下文。根据字体和样式，可以使用许多不同的字形来表示单个字符或字符组合。

例如，在手写草书文本中，特定字符的形状可能会因其与相邻字符的连接方式而异。

在某些书写系统中，特别是阿拉伯文中，必须始终考虑字形的上下文。与英语不同，阿拉伯文中的草书形式是强制性的；在阿拉伯文中，不能不使用草书形式呈现文本。

根据上下文，这些草书形式在形状上可能有很大差异。例如，阿拉伯字母heh有以下图中显示的四种草书形式：

尽管这四种形式彼此非常不同，但这种草书形式的变化与英语中的草书写作并无根本区别。

在某些情况下，两个字形的形状甚至可以发生更大变化，合并成一个单一的字形。这种合并的字形称为连字。例如，大多数英文字体包含以下图中显示的连字fi：

合并的字形考虑了字母f的悬挑，并以一种自然的方式组合字符，而不是简单地让字母相撞。

阿拉伯文中也使用连字，有些连字的使用是强制性的；在不使用适当的连字的情况下呈现某些字符组合是不可接受的。当从阿拉伯字符形成连字时，形状甚至比在英文中更根本地改变。例如，下图说明了当两个阿拉伯字符在一起时如何组合成单个连字。

文本排序

在 Java 编程语言中，文本使用 Unicode 字符编码进行编码。使用 Unicode 字符编码的文本以逻辑顺序存储在内存中。逻辑顺序是字符和单词被读取和写入的顺序。逻辑顺序不一定与视觉顺序相同，即对应字形显示的顺序。

特定书写系统（脚本）中字形的视觉顺序称为脚本顺序。例如，罗马文本的脚本顺序是从左到右，而阿拉伯文和希伯来文的脚本顺序是从右到左。

一些书写系统除了脚本顺序外，还有规则来排列文本行上的字形和单词。例如，阿拉伯文和希伯来文的数字是从左到右排列的，即使字母是从右到左排列的。这意味着阿拉伯文和希伯来文，即使没有嵌入英文文本，也是真正的双向文本。更多信息请参见处理双向文本。

测量和定位文本

除非您使用等宽字体，否则字体中的不同字符具有不同的宽度。这意味着所有文本的定位和测量都必须考虑到确切使用了哪些字符，而不仅仅是数量。例如，要在比例字体中右对齐显示的数字列，您不能简单地使用额外的空格来定位文本。为了正确对齐列，您需要知道每个数字的确切宽度，以便相应调整。

文本通常使用多种字体和样式显示，如粗体或斜体。在这种情况下，即使是相同的字符也可能有不同的形状和宽度，这取决于其样式。为了正确定位、测量和呈现文本，您需要跟踪每个单独的字符和应用于该字符的样式。幸运的是，TextLayout类可以为您完成这些工作。

要正确显示希伯来文和阿拉伯文等语言的文本，需要测量和定位每个单独的字符，并将其放置在相邻字符的上下文中。由于字符的形状和位置可能会根据上下文而变化，因此在不考虑上下文的情况下测量和定位此类文本会产生不可接受的结果。

此外，Java SE 为您提供了FontMetrics类，它使您能够获取由Font对象渲染的文本的测量值，比如字体中一行文本的高度。您可以利用这些信息在 Java 图形应用程序中精确定位文本。更多信息请参见测量文本。

物理和逻辑字体

原文：docs.oracle.com/javase/tutorial/2d/text/fonts.html

有两种字体：物理字体和逻辑字体。物理字体是实际的字体库，包括 TrueType 或 PostScript Type 1 字体。物理字体可以是 Time、Helvetica、Courier 或任何其他字体，包括国际字体。逻辑字体是以下五个字体系列：Serif、SansSerif、Monospaced、Dialog 和 DialogInput。这些逻辑字体不是实际的字体库。相反，Java 运行时环境通过逻辑字体名称将其映射到物理字体。

本节帮助您确定在应用程序中使用哪种字体。它涵盖以下主题：

• 物理字体

  • Lucidia 字体

  • 将物理字体与您的应用程序捆绑

• 逻辑字体

• 使用物理和逻辑字体的优缺点

• 字体配置文件

物理字体

物理字体是包含字形数据和表的实际字体库，使用 TrueType 或 PostScript Type 1 等字体技术，以将字符序列映射到字形序列。要获取系统中安装的所有可用字体系列的名称，请调用以下内容：

GraphicsEnvironment ge = GraphicsEnvironment.getLocalGraphicsEnvironment();
String []fontFamilies = ge.getAvailableFontFamilyNames();

FontSelector 示例程序（在 FontSelector.java 中可用）演示了如何定位和选择这些字体。

注意： 应用程序不应假设任何特定的物理字体存在。然而，逻辑字体是一个安全的选择，因为它们始终存在。有关更多信息，请参阅逻辑字体。

Lucidia 字体

Oracle 的 JRE 包含这一系列物理字体，也被许可用于其他 Java 平台的实现。这些字体是物理字体，但不依赖于主机操作系统。

使用这些字体的应用程序可以在这些字体可用的任何地方实现相同的外观。此外，这些字体涵盖了大量的语言（特别是欧洲和中东地区），因此您可以为支持的语言创建完全多语言的应用程序。然而，这些字体可能不在所有 JRE 中可用。此外，它们目前不涵盖完整的 Unicode 字符集；特别是，不支持中文、日文和韩文。

将物理字体与您的应用程序捆绑

有时，应用程序不能依赖于系统上安装的字体，通常是因为该字体是一种不可用的自定义字体。在这种情况下，必须将字体文件与应用程序捆绑在一起。

使用以下方法之一从现有物理字体创建 Font 对象：

Font java.awt.Font.createFont(int fontFormat, InputStream in);
Font java.awt.Font.createFont(int fontFormat, File fontFile);

要从 TrueType 字体创建 Font 对象，形式参数 fontFormat 必须是常量 Font.TRUETYPE_FONT。以下示例从 TrueType 字体文件 A.ttf 创建 Font 对象：

Font font = Font.createFont(Font.TRUETYPE_FONT, new File("A.ttf"));

直接从文件访问字体更简单、更方便。但是，如果您的代码无法访问文件系统资源，或者字体与应用程序或小程序的其余部分一起打包在 Java 存档（JAR）文件中，则可能需要一个 InputStream 对象。

createFont 方法创建一个具有点大小为 1 和样式 PLAIN 的新 Font 对象。然后可以使用 Font.deriveFont 方法将此基础字体用于派生具有不同大小、样式、变换和字体特性的新 Font 对象。例如：

try {
     //Returned font is of pt size 1
     Font font = Font.createFont(Font.TRUETYPE_FONT, new File("A.ttf"));

     //Derive and return a 12 pt version:
     //Need to use float otherwise
     //it would be interpreted as style

     return font.deriveFont(12f);

} catch (IOException|FontFormatException e) {
     // Handle exception
}

使用 deriveFont 方法很重要，因为应用程序创建的字体不属于底层字体系统所知的字体集。由于 deriveFont 方法是从最初创建的字体工作的，因此它没有这种限制。

解决此问题的方法是将创建的字体注册到图形环境中。例如：

try {
     GraphicsEnvironment ge = 
         GraphicsEnvironment.getLocalGraphicsEnvironment();
     ge.registerFont(Font.createFont(Font.TRUETYPE_FONT, new File("A.ttf"));
} catch (IOException|FontFormatException e) {
     //Handle exception
}

在将字体注册到图形环境后，该字体可以在调用 getAvailableFontFamilyNames() 时使用，并且可以在字体构造函数中使用。

逻辑字体

Java SE 定义了以下五个逻辑字体系列：

• Dialog

• DialogInput

• Monospaced

• Serif

• SansSerif

这些字体在任何 Java 平台上都可用，并且可以被视为某些具有其名称所暗示属性的基础字体的别名。Serif 字体类似于 Times New Roman，通常用于印刷。Sans Serif 字体更适合屏幕使用。

这些字体可以根据用户的语言环境进行定制。此外，这些字体支持最广泛的代码点（Unicode 字符）范围。

除了字体系列，字体还具有其他属性，其中最重要的是 样式 和 大小。样式有 Bold 和 Italic。

Java 2D API 使用的默认字体是 12 磅的 Dialog。这种字体是在普通 72-120 DPI 显示设备上阅读文本的典型字号。应用程序可以通过指定以下内容直接创建此字体的实例：

Font font = new Font("Dialog", Font.PLAIN, 12);

使用物理和逻辑字体的优缺点

物理字体使应用程序能够充分利用所有可用字体，实现不同的文本外观和最大的语言覆盖范围。然而，创建使用物理字体的应用程序要困难得多。

将物理字体与您的应用程序捆绑在一起，可以使您创建的应用程序在任何地方看起来都一样，并且可以完全控制您想要支持的应用程序。然而，捆绑的字体可能会很大，特别是如果您希望您的应用程序支持中文、日文和韩文。此外，您可能需要解决许可问题。

逻辑字体名称保证在任何地方都能正常工作，并且它们至少能够在主机操作系统本地化的语言中进行文本呈现（通常支持更广泛的语言范围）。然而，用于呈现文本的物理字体在不同的实现、主机操作系统和区域设置之间会有所不同，因此应用程序无法在任何地方实现相同的外观。此外，映射机制有时会限制可以呈现的字符范围。这在 JRE 版本 5.0 之前曾经是一个大问题：例如，日文文本只能在日本本地化的主机操作系统上呈现，而在其他本地化系统上即使安装了日文字体也无法呈现。对于使用 2D 字体呈现的应用程序，在 JRE 版本 5.0 及更高版本中，这个问题要少得多，因为映射机制现在通常会识别并使用所有支持的书写系统的字体（如果已安装）。

字体配置文件

Java SE 运行时环境使用字体配置文件将逻辑字体名称映射到物理字体。根据主机操作系统版本的不同映射，有几个文件支持不同的映射。这些文件位于 JRE 安装的 lib 目录中。您可以编辑或创建自己的字体配置文件，以调整映射到您特定系统设置的映射。有关更多信息，请参阅字体配置文件。

测量文本

原文：docs.oracle.com/javase/tutorial/2d/text/measuringtext.html

要正确测量文本，您需要学习一些方法和一些要避免的错误。字体度量是由Font对象呈现的文本的测量，例如字体中一行文本的高度。测量文本最常见的方法是使用封装了这些度量信息的FontMetrics实例。例如：

// get metrics from the graphics
FontMetrics metrics = graphics.getFontMetrics(font);
// get the height of a line of text in this
// font and render context
int hgt = metrics.getHeight();
// get the advance of my text in this font
// and render context
int adv = metrics.stringWidth(text);
// calculate the size of a box to hold the
// text with some padding.
Dimension size = new Dimension(adv+2, hgt+2);

对于许多应用程序来说，这种方式足以均匀间隔文本行或调整 Swing 组件的大小。

注意以下内容：

• 这些度量是从Graphics类中获取的，因为这个类封装了FontRenderContext，这是准确测量文本所需的。在屏幕分辨率下，字体会根据易读性进行调整。随着文本大小的增加，这种调整并不是线性缩放的。因此，在 20 pt 时，字体显示的文本长度不会正好是在 10 pt 时的两倍。除了文本本身和字体之外，用于测量文本的另一个重要信息是FontRenderContext。该方法包括从用户空间到设备像素的变换，用于测量文本。

• 高度报告时没有参考任何特定文本字符串。例如，在文本编辑器中，您希望每行文本之间具有相同的行间距时，这是有用的。

• stringWidth()返回文本的前进宽度。前进宽度是从文本原点到随后呈现的字符串位置的距离。

在使用这些方法测量文本时，请注意文本可以向字体高度和字符串前进的矩形定义之外的任何方向延伸。

通常，最简单的解决方案是确保文本不被裁剪，例如，由围绕文本的组件。在可能导致文本被裁剪的情况下添加填充。

如果此解决方案不足够，Java 2D 软件中的其他文本测量 API 可以返回矩形边界框。这些框考虑了要测量的特定文本的高度和像素化效果。

高级文本显示

原文：docs.oracle.com/javase/tutorial/2d/text/advanced.html

Java 2D API 提供了支持复杂文本布局的机制。本节描述了高级文本显示的以下特性。

使用渲染提示显示抗锯齿文本

本节介绍如何通过使用渲染提示来控制渲染质量。

使用文本属性来设置文本样式

本节解释了如何使用TextAttribute类来给文本添加下划线或删除线。

绘制多行文本

本节解释了如何使用TextLayout和LineBreakMeasurer类来定位和渲染一段样式化文本。

处理双向文本

本节讨论如何使用java.awt和java.awt.font包中的类处理双向文本。

使用渲染提示显示抗锯齿文本

原文：docs.oracle.com/javase/tutorial/2d/text/renderinghints.html

Java 2D 文本渲染可能受渲染提示的影响。

请记住最重要的文本绘制方法如下：

Graphics.drawString(String s, int x, int y);

通常，该方法会使用纯色绘制文本字符串中的每个字形，而该字形中的每个“开启”像素都会设置为该颜色。这种绘制方式产生了最高对比度的文本，但有时会出现锯齿状（锯齿状）边缘。

文本抗锯齿是一种用于平滑屏幕上文本边缘的技术。Java 2D API 使应用程序能够指定是否应使用此技术以及通过将文本渲染提示应用于Graphics来使用哪种算法。

最常见的渲染提示会将前景（文本）颜色与文本边缘的屏幕背景像素混合。要请求此提示，应用程序必须调用以下方法：

graphics2D.setRenderingHint(
        RenderingHints.KEY_TEXT_ANTIALIASING,
        RenderingHints.VALUE_TEXT_ANTIALIAS_ON);

以下图示说明了抗锯齿功能。

如果不当使用，此方法可能使文本显得过于模糊。在这种情况下，更好的提示是以下提示：

graphics2D.setRenderingHint(
        RenderingHints.KEY_TEXT_ANTIALIASING,
        RenderingHints.VALUE_TEXT_ANTIALIAS_GASP);

这种方法会自动使用字体本身的信息来决定是使用抗锯齿还是使用纯色。

LCD 显示器具有 Java 2D API 可以利用的属性，以产生不像典型抗锯齿那样模糊的文本，但在小尺寸下更易读的文本。要求使用典型 LCD 显示器的子像素 LCD 文本模式绘制文本，应用程序必须调用以下方法：

graphics2D.setRenderingHint(
        RenderingHints.KEY_TEXT_ANTIALIASING,
        RenderingHints.VALUE_TEXT_ANTIALIAS_LCD_HRGB);

下面所示的代码示例说明了抗锯齿功能的顺序：

1. 抗锯齿已关闭。

2. 抗锯齿已开启。

3. 使用TEXT_ANTIALIAS_GASP提示进行抗锯齿。

   ---

   注意： 因此，GASP 表指定仅在这些大小上使用提示，而不是“平滑”。因此，在许多情况下，结果文本显示等同于VALUE_TEXT_ANTIALIAS_OFF。

   ---

4. 使用TEXT_ANTIALIAS_LCD_HRGB提示进行抗锯齿。

此 applet 的完整代码在AntialiasedText.java中。

使用文本属性来设置文本样式

原文：docs.oracle.com/javase/tutorial/2d/text/textattributes.html

应用程序通常需要能够应用以下文本属性：

• 下划线 – 在文本下方绘制的线

• 删除线 – 通过文本绘制的水平线

• 上标或下标 – 文本或字母略高于一行或相应地低于一行

• 字间距 – 调整字符之间的空间

这些以及其他文本属性可以通过使用 Java 2D TextAttribute 类来应用。

要应用这些文本属性，请将它们添加到 Font 对象中。例如：

Map<TextAttribute, Object> map =
    new Hashtable<TextAttribute, Object>();
map.put(TextAttribute.KERNING,
    TextAttribute.KERNING_ON);
font = font.deriveFont(map);
graphics.setFont(font);

下面的代码示例显示了按以下顺序应用文本属性：

1. 示例字符串（未应用文本属性）

2. 字间距

3. 字间距和下划线

4. 字间距、下划线和删除线

5. 字间距、下划线、删除线和颜色

此 applet 的完整代码在 AttributedText.java 中。

绘制多行文本

原文：docs.oracle.com/javase/tutorial/2d/text/drawmulstring.html

如果您有一段带样式的文本，希望将其适应特定宽度，可以使用 LineBreakMeasurer 类。这个类使得带样式的文本可以被分成行，以便它们适应特定的视觉前进。每一行作为一个 TextLayout 对象返回，代表不可改变的、带样式的字符数据。然而，这个类也使得可以访问布局信息。TextLayout 的 getAscent 和 getDescent 方法返回有关用于在组件中定位行的字体的信息。文本被存储为 AttributedCharacterIterator 对象，以便字体和点大小属性可以与文本一起存储。

以下小程序使用 LineBreakMeasurer、TextLayout 和 AttributedCharacterIterator 在组件中定位一段带样式的文本。

这个小程序的完整代码在 LineBreakSample.java 中。

以下代码创建一个包含字符串 vanGogh 的迭代器。检索迭代器的开始和结束，并从迭代器创建一个新的 LineBreakMeasurer。

    AttributedCharacterIterator paragraph = vanGogh.getIterator();
    paragraphStart = paragraph.getBeginIndex();
    paragraphEnd = paragraph.getEndIndex();
    FontRenderContext frc = g2d.getFontRenderContext();
    lineMeasurer = new LineBreakMeasurer(paragraph, frc);

窗口的大小用于确定何处应该断行。同时为段落中的每一行创建一个 TextLayout 对象。

// Set break width to width of Component.
float breakWidth = (float)getSize().width;
float drawPosY = 0;
// Set position to the index of the first
// character in the paragraph.
lineMeasurer.setPosition(paragraphStart);

// Get lines from until the entire paragraph
// has been displayed.
while (lineMeasurer.getPosition() < paragraphEnd) {

    TextLayout layout = lineMeasurer.nextLayout(breakWidth);

    // Compute pen x position. If the paragraph
    // is right-to-left we will align the
    // TextLayouts to the right edge of the panel.
    float drawPosX = layout.isLeftToRight()
        ? 0 : breakWidth - layout.getAdvance();

    // Move y-coordinate by the ascent of the
    // layout.
    drawPosY += layout.getAscent();

    // Draw the TextLayout at (drawPosX,drawPosY).
    layout.draw(g2d, drawPosX, drawPosY);

    // Move y-coordinate in preparation for next
    // layout.
    drawPosY += layout.getDescent() + layout.getLeading();
}

TextLayout 类通常不会被应用程序直接创建。然而，当应用程序需要直接处理在文本中特定位置应用了样式（文本属性）的文本时，这个类就非常有用。例如，要在段落中画一个单词斜体，应用程序需要为每个子字符串执行测量并设置字体。如果文本是双向的，这个任务就不那么容易正确完成。通过从 AttributedString 对象创建一个 TextLayout 对象来处理这个问题。请参考 Java SE 规范了解更多关于 TextLayout 的信息。

处理双向文本

译文：docs.oracle.com/javase/tutorial/2d/text/textlayoutbidirectionaltext.html

这一部分讨论如何使用java.awt和java.awt.font包中的类处理双向文本。这些类允许您以任何语言或脚本绘制样式化文本，这些语言或脚本受到 Unicode 标准的支持：这是一个全球字符编码系统，用于处理各种现代、古典和历史语言。在绘制文本时，必须考虑文本的阅读方向，以便字符串中的所有单词都能正确显示。这些类维护文本的方向，并正确绘制它，无论字符串是从左到右、从右到左还是双向运行。双向文本对于正确定位插入符、准确定位选择以及正确显示多行文本提出了有趣的问题。另外，双向和从右到左的文本对于根据右箭头和左箭头键的按压正确移动插入符也存在类似问题。

下列主题包括：

• 文本排序

• 操作双向文本

  • 显示插入符

  • 移动插入符

  • 点击测试

  • 突出显示选择

• 在 Java 应用程序中执行文本布局

• 使用 TextLayout 类管理文本布局

  • 使用 TextLayout 类布局文本

  • 使用 TextLayout 类显示双插入符

  • 使用 TextLayout 类移动插入符

  • 使用 TextLayout 类进行点击测试

  • 使用 TextLayout 类突出显示选择

如果您计划使用 Swing 组件，请参阅使用 JTextComponent 类处理双向文本和使用文本组件获取更多信息。

文本排序

Java SE 在内存中以逻辑顺序存储文本，这是字符和单词读取和写入的顺序。逻辑顺序不一定与视觉顺序相同，后者是显示相应字形的顺序。

即使混合使用多种语言，双向文本中必须保持书写系统的视觉顺序。下图展示了一个嵌入在英语句子中的阿拉伯短语。

注意： 在这个和后续的示例中，阿拉伯语和希伯来语文本由大写字母表示，空格由下划线表示。每个示例包含两部分：存储在内存中的字符表示（逻辑顺序的字符）后跟这些字符如何显示的表示（视觉顺序的字符）。字符框下面的数字表示插入偏移量。

尽管它们是英语句子的一部分，但阿拉伯语单词以阿拉伯语书写顺序从右到左显示。因为斜体的阿拉伯语单词在逻辑上位于普通文本的阿拉伯语单词之后，所以在视觉上位于普通文本的左侧。

当显示混合左到右和右到左文本的行时，基本方向很重要。基本方向是主要书写系统的书写顺序。例如，如果文本主要是英语并带有一些嵌入的阿拉伯语，则基本方向是从左到右。如果文本主要是阿拉伯语并带有一些嵌入的英语或数字，则基本方向是从右到左。

基本方向确定具有共同方向的文本段的显示顺序。在前面图中显示的示例中，基本方向是从左到右。在这个示例中有三个方向性运行：句子开头的英语文本从左到右运行，阿拉伯文本从右到左运行，句号从左到右运行。

图形通常嵌入在文本流中。这些内联图形在影响文本流和换行方式方面类似于字形。这样的内联图形需要使用相同的双向布局算法定位，以便它们出现在字符流的适当位置。

Java SE 使用Unicode 双向算法，这是一种用于在一行内对字形进行排序的算法，从而确定双向文本的方向性。在大多数情况下，您无需包含任何额外信息，以便该算法获取正确的显示顺序。

操纵双向文本

为了允许用户编辑双向文本，您必须能够执行以下操作：

• 显示插入符

• 移动插入符

• 点击测试

• 突出显示选择

显示插入符

在可编辑文本中，插入符用于图形化表示当前插入点，即文本中新字符将被插入的位置。通常，插入符显示为两个字形之间闪烁的垂直条。新字符被插入并显示在插入符的位置。

计算插入符位置可能会很复杂，特别是对于双向文本。在方向边界上的插入偏移量有两个可能的插入符位置，因为对应于字符偏移量的两个字形不会相邻显示。如下图所示。在此图中，插入符显示为方括号，表示插入符对应的字形。

字符偏移量 8 对应于下划线后和A之前的位置。如果用户输入阿拉伯字符，其字形将显示在A的右侧；如果用户输入英文字符，其字形将显示在下划线的右侧。

为了处理这种情况，一些系统显示双插入符，一个强（主要）插入符和一个弱（次要）插入符。强插入符指示插入的字符的方向与文本基础方向相同时将显示在何处。弱插入符显示插入的字符的方向与基础方向相反时将显示在何处TextLayout自动支持双插入符。

当处理双向文本时，不能简单地将字符偏移量之前的字形宽度相加以计算插入符位置。如果这样做，插入符将被绘制在错误的位置，如下图所示：

为了正确定位插入符，需要将偏移量左侧的字形宽度相加，并考虑当前上下文。除非考虑上下文，否则字形度量可能不会与显示匹配。（上下文可能会影响使用哪些字形。）

移动插入符

所有文本编辑器都允许用户使用箭头键移动插入符。用户期望插入符沿按下的箭头键方向移动。在从左到右的文本中，移动插入偏移量很简单：右箭头键将插入偏移量增加一，左箭头键将其减少一。在双向文本或带有连字的文本中，此行为会导致插入符跨越方向边界的字形并在不同方向运行内部反向移动。

要在双向文本中平滑移动插入符，需要考虑文本运行的方向。当按下右箭头键时不能简单地增加插入偏移量，当按下左箭头键时减少它。如果当前插入偏移量位于从右到左字符的运行内，右箭头键应减少插入偏移量，左箭头键应增加它。

在跨越方向边界时移动插入符更加复杂。下图说明了当用户使用箭头键导航时，当穿越方向边界时会发生什么。在显示的文本中向右移动三个位置对应于移动到字符偏移 7、19，然后是 18。

某些字形之间永远不应该有插入符；相反，插入符应该移动得像这些字形代表一个单一字符一样。例如，如果一个 o 和一个变音符由两个单独的字符表示，那么它们之间永远不应该有插入符。

TextLayout 类提供了方法（getNextRightHit 和 getNextLeftHit），使您能够轻松地在双向文本中平滑地移动插入符。

命中测试

通常，设备空间中的位置必须转换为文本偏移量。例如，当用户在可选择文本上单击鼠标时，鼠标位置将转换为文本偏移量，并用作选择范围的一端。从逻辑上讲，这是放置插入符的逆过程。

当处理双向文本时，显示中的单个视觉位置可以对应源文本中的两个不同偏移量，如下图所示：

因为单个视觉位置可以对应两个不同的偏移量，所以命中测试双向文本不仅仅是测量字形宽度直到找到正确位置的字形，然后将该位置映射回字符偏移量。检测命中位置所在的一侧有助于区分这两种选择。

您可以使用 TextLayout.hitTestChar 进行命中测试。命中信息封装在 TextHitInfo 对象中，并包括有关命中位置所在一侧的信息。

突出显示选择

一段选定的字符范围通过一个高亮区域图形化表示，其中字形以反色或不同背景颜色显示。

高亮区域，就像插入符一样，在双向文本中比单向文本更复杂。在双向文本中，一段连续的字符范围在显示时可能没有连续的高亮区域。相反，显示为视觉上连续的一系列字形的高亮区域可能不对应单一、连续的字符范围。

这导致双向文本中突出选择的两种策略：

• 逻辑高亮：使用逻辑高亮，所选字符在文本模型中始终是连续的，而高亮区域允许是不连续的。以下是逻辑高亮的示例：

  

• 可视高亮：使用可视高亮，可能会有多个选定字符范围，但高亮区域始终是连续的。以下是可视高亮的示例：

  

逻辑高亮更容易实现，因为所选字符在文本中始终是连续的。

示例SelectionSample.java演示了逻辑高亮：

在 Java 应用程序中执行文本布局

根据您使用的 Java API，您可以根据需要对文本布局进行精细或粗略的控制：

• 如果您只想显示一块文本或需要一个可编辑的文本控件，您可以使用JTextComponent，它将为您执行文本布局。JTextComponent旨在处理大多数国际应用程序的需求，并支持双向文本。有关JTextComponent的更多信息，请参见使用 JTextComponent 类处理双向文本和使用文本组件。

• 如果您想显示一个简单的文本字符串，您可以调用方法Graphics2D.drawString，让 Java 2D 为您布局字符串。您还可以使用Graphics2D.drawString来呈现带样式的字符串和包含双向文本的字符串。有关通过Graphics2D呈现文本的更多信息，请参见使用文本 API。

• 如果您想实现自己的文本编辑例程，可以使用 TextLayout 来管理文本布局、高亮显示和点击检测。TextLayout 提供的功能处理了大多数常见情况，包括具有混合字体、混合语言和双向文本的文本字符串。有关使用 TextLayout 的更多信息，请参见管理文本布局。

• 如果您想完全控制文本的形状和位置，可以使用 Font 类构建自己的 GlyphVector 实例，然后通过 Graphics2D 类进行渲染。

通常，您不需要自己执行文本布局操作。对于大多数应用程序，JTextComponent 是显示静态和可编辑文本的最佳解决方案。但是，JTextComponent 不支持双插入符或双向文本中的不连续选择的显示。如果您的应用程序需要这些功能，或者您更喜欢实现自己的文本编辑例程，可以使用 Java 2D 文本布局 API。

使用 TextLayout 类管理文本布局

TextLayout 类支持包含多种样式和来自不同书写系统（包括阿拉伯文和希伯来文）的字符的文本。（阿拉伯文和希伯来文特别难以显示，因为您必须重新排列和重新排序文本以获得可接受的表示。）

即使您只处理英文文本，TextLayout 也简化了显示和测量文本的过程。通过使用 TextLayout，您可以在不费额外努力的情况下实现高质量的排版。

TextLayout 被设计为在显示简单的单向文本时不会产生显著的性能影响。当使用 TextLayout 显示阿拉伯文或希伯来文时，会有一些额外的处理开销。但是，这通常是每个字符的微秒数量级，并且被正常绘图代码的执行所主导。

TextLayout 类为您管理字形的定位和排序。您可以使用TextLayout 来执行以下操作：

• 使用 TextLayout 类进行文本布局

• 使用 TextLayout 类显示双光标

• 使用 TextLayout 类移动光标

• 使用 TextLayout 类进行点击测试

• 使用 TextLayout 类突出显示选择内容

使用 TextLayout 类进行文本布局

TextLayout 自动布局文本，包括双向文本，具有正确的形状和顺序。为了正确形状和排序表示一行文本的字形，TextLayout 必须了解文本的完整上下文：

• 如果文本适合单行，例如按钮的单词标签或对话框中的一行文本，您可以直接从文本构造一个TextLayout。

• 如果您有更多文本无法适合单行或想要在单行文本上分隔制表符段，您不能直接构造一个TextLayout。您必须使用LineBreakMeasurer 提供足够的上下文。有关更多信息，请参见绘制多行文本。

文本的基本方向通常由文本上的属性（样式）设置。如果该属性缺失，TextLayout 将遵循 Unicode 双向算法，并从段落中的初始字符推导基本方向。

使用 TextLayout 类显示双光标

TextLayout 保留光标信息，如光标Shape、位置和角度。您可以使用此信息轻松地在单向和双向文本中显示光标。在为双向文本绘制光标时，使用TextLayout 可确保光标位置正确。

TextLayout提供默认插入符Shapes并自动支持双插入符。对于斜体和倾斜字形，TextLayout会产生倾斜插入符，如下图所示。这些插入符位置也用作高亮和命中测试之间的字形边界，有助于产生一致的用户体验。

给定插入偏移量，getCaretShapes方法返回一个包含两个Shape对象的数组：元素 0 包含强插入符，元素 1 包含弱插入符（如果存在）。要显示双插入符，只需绘制两个插入符Shape对象；插入符将自动呈现在正确的位置。

如果您想使用自定义插入符，可以从TextLayout中检索插入符的位置和角度，并自行绘制它们。

示例HitTestSample.java演示了双插入符。

点击希伯来文本旁边的o会记录用户在o之后点击的位置，这部分属于英文文本。这将使弱（黑色）插入符位于o旁边，而强插入符（红色）位于H之前：

点击o右侧的空格会记录用户点击了空格，这部分属于希伯来文本。这将使强（红色）插入符位于o旁边，而弱插入符（黑色）位于H之前：

使用 TextLayout 类移动插入符

您还可以使用TextLayout类确定用户按下左箭头或右箭头键时的插入偏移量。给定表示当前插入偏移量的TextHitInfo对象，getNextRightHit方法返回一个表示正确插入偏移量的TextHitInfo对象，如果按下右箭头键。getNextLeftHit方法为左箭头键提供相同的信息。

来自示例ArrowKeySample.java的以下摘录演示了确定用户按下左箭头或右箭头键时的插入偏移量的方法：

public class ArrowKeySample extends JPanel implements KeyListener {

  // ...

  private static void createAndShowGUI() {
    // Create and set up the window.
    ArrowKey demo = new ArrowKey();
    frame = new JFrame("Arrow Key Sample");
    frame.addKeyListener(demo);
    // ...
  }

  private void handleArrowKey(boolean rightArrow) {
    TextHitInfo newPosition;
    if (rightArrow) {
      newPosition = textLayout.getNextRightHit(insertionIndex);
    } else {
      newPosition = textLayout.getNextLeftHit(insertionIndex);
    }

    // getNextRightHit() / getNextLeftHit() will return null if
    // there is not a caret position to the right (left) of the
    // current position.
    if (newPosition != null) {
      // Update insertionIndex.
      insertionIndex = newPosition.getInsertionIndex();
      // Repaint the Component so the new caret(s) will be displayed.
      frame.repaint();
    }
  }

  // ...

  @Override
  public void keyPressed(KeyEvent e) {
    int keyCode = e.getKeyCode();
    if (keyCode == KeyEvent.VK_LEFT || keyCode == KeyEvent.VK_RIGHT) {
      handleArrowKey(keyCode == KeyEvent.VK_RIGHT);
    }
  }
}

使用 TextLayout 类进行命中测试

TextLayout类提供了一个简单的文本命中测试机制。hitTextChar方法以鼠标的x和y坐标作为参数，并返回一个TextHitInfo对象。TextHitInfo包含指定位置的插入偏移量和命中位置的侧面。插入偏移量是最接近命中位置的偏移量：如果命中位置超过行尾，将返回行尾的偏移量。

来自HitTestSample.java的以下摘录从鼠标点击中检索偏移量：

private class HitTestMouseListener extends MouseAdapter {
    public void mouseClicked(MouseEvent e) {
      Point2D origin = computeLayoutOrigin();
      // Compute the mouse click location relative to
      // textLayout's origin.
      float clickX = (float) (e.getX() - origin.getX());
      float clickY = (float) (e.getY() - origin.getY());
      // Get the character position of the mouse click.
      TextHitInfo currentHit = textLayout.hitTestChar(clickX, clickY);
      insertionIndex = currentHit.getInsertionIndex();
      // Repaint the Component so the new caret(s) will be displayed.
      repaint();
    }
  }

使用 TextLayout 类进行高亮选择

你可以从TextLayout获取代表高亮区域的Shape。在计算高亮区域的尺寸时，TextLayout会自动考虑上下文。TextLayout支持逻辑和视觉高亮。

来自SelectionSample.java的以下摘录演示了显示高亮文本的一种方法：

public void paint(Graphics g) {

    // ...

    boolean haveCaret = anchorEnd == activeEnd;

    if (!haveCaret) {
      // Retrieve highlight region for selection range.
      Shape highlight = 
          textLayout.getLogicalHighlightShape(anchorEnd, activeEnd);
      // Fill the highlight region with the highlight color.
      graphics2D.setColor(HIGHLIGHT_COLOR);
      graphics2D.fill(highlight);
    }

    // ...

  }

  // ...

  private class SelectionMouseMotionListener extends MouseMotionAdapter {
    public void mouseDragged(MouseEvent e) {
      Point2D origin = computeLayoutOrigin();
      // Compute the mouse location relative to
      // textLayout's origin.
      float clickX = (float) (e.getX() - origin.getX());
      float clickY = (float) (e.getY() - origin.getY());
      // Get the character position of the mouse location.
      TextHitInfo position = textLayout.hitTestChar(clickX, clickY);
      int newActiveEnd = position.getInsertionIndex();
      // If newActiveEnd is different from activeEnd, update activeEnd
      // and repaint the Panel so the new selection will be displayed.
      if (activeEnd != newActiveEnd) {
        activeEnd = newActiveEnd;
        frame.repaint();
      }
    }
  }

  private class SelectionMouseListener extends MouseAdapter {
    public void mousePressed(MouseEvent e) {
      Point2D origin = computeLayoutOrigin();
      // Compute the mouse location relative to
      // TextLayout's origin.
      float clickX = (float) (e.getX() - origin.getX());
      float clickY = (float) (e.getY() - origin.getY());
      // Set the anchor and active ends of the selection
      // to the character position of the mouse location.
      TextHitInfo position = textLayout.hitTestChar(clickX, clickY);
      anchorEnd = position.getInsertionIndex();
      activeEnd = anchorEnd;
      // Repaint the Panel so the new selection will be displayed.
      frame.repaint();
    }
  }

方法SelectionMouseListener.mousePressed指定了变量anchorEnd，它是鼠标点击的文本位置。方法SelectionMouseMotionListener.mouseDragged指定了变量activeEnd，它是鼠标拖动到的文本位置。paint方法检索一个代表所选文本的Shape对象（即anchorEnd和activeEnd位置之间的文本）。然后paint方法用高亮颜色填充Shape对象。

教程：处理图像

原文：docs.oracle.com/javase/tutorial/2d/images/index.html

正如您已经从 图像 教程中了解的那样，Image 由以像素为单位的宽度和高度描述，并且具有与绘图表面无关的坐标系。

处理图像时有许多常见任务。

• 将外部 GIF、PNG JPEG 图像格式文件加载到 Java 2D 使用的内部图像表示中。

• 直接创建 Java 2D 图像并对其进行渲染。

• 将 Java 2D 图像的内容绘制到绘图表面上。

• 将 Java 2D 图像的内容保存到外部 GIF、PNG 或 JPEG 图像文件中。

本课程教授如何加载、显示和保存图像的基础知识。

您必须了解的两个主要类来处理图像：

• java.awt.Image 类是表示图形图像的像素矩形数组的超类。

• java.awt.image.BufferedImage 类扩展了 Image 类，允许应用程序直接操作图像数据（例如，检索或设置像素颜色）。应用程序可以直接构造此类的实例。

BufferedImage 类是 Java 2D 立即模式成像 API 的基石。它管理内存中的图像，并提供存储、解释和获取像素数据的方法。由于 BufferedImage 是 Image 的子类，因此可以通过接受 Image 参数的 Graphics 和 Graphics2D 方法来呈现它。

BufferedImage 本质上是具有可访问数据缓冲区的 Image。因此，直接使用 BufferedImage 更有效。BufferedImage 具有 ColorModel 和图像数据的 Raster。ColorModel 提供图像像素数据的颜色解释。

Raster 执行以下功能：

• 表示图像的矩形坐标

• 在内存中维护图像数据

• 提供从单个图像数据缓冲区创建多个子图像的机制

• 提供访问图像内特定像素的方法

图像的基本操作在以下部分中表示：

读取/加载图像

本节解释了如何使用 Image I/O API 将外部图像格式的图像加载到 Java 应用程序中。

绘制图像

本节教授如何使用 Graphics 和 Graphics2D 类的 drawImage 方法显示图像。

创建和绘制到图像

本节描述了如何创建图像以及如何将图像本身用作绘图表面。

写入/保存图像

本节解释了如何以适当的格式保存创建的图像。

读取/加载图像

原文：docs.oracle.com/javase/tutorial/2d/images/loadimage.html

当你想到数字图像时，你可能会想到采样图像格式，比如数字摄影中使用的 JPEG 图像格式，或者网页常用的 GIF 图像。所有可以使用这些图像的程序都必须首先将它们从外部格式转换为内部格式。

Java 2D 支持使用其 Image I/O API 将这些外部图像格式加载到其 BufferedImage 格式中，该 API 位于 javax.imageio 包中。Image I/O 内置支持 GIF、PNG、JPEG、BMP 和 WBMP。Image I/O 也是可扩展的，因此开发人员或管理员可以为其他格式“插入”支持。例如，TIFF 和 JPEG 2000 的插件是单独可用的。

要从特定文件加载图像，请使用以下代码，这段代码来自 LoadImageApp.java：

BufferedImage img = null;
try {
    img = ImageIO.read(new File("strawberry.jpg"));
} catch (IOException e) {
}

Image I/O 将文件的内容识别为 JPEG 格式图像，并将其解码为可以被 Java 2D 直接使用的 BufferedImage。

LoadImageApp.java 展示了如何显示这个图像。

如果代码在小程序中运行，那么从小程序代码库获取图像就像轻而易举一样。以下摘录来自 LoadImageApplet.java：

try {
    URL url = new URL(getCodeBase(), "examples/strawberry.jpg");
    img = ImageIO.read(url);
} catch (IOException e) {
}

这个示例中使用的 getCodeBase 方法返回部署在 Web 服务器上时包含这个小程序的目录的 URL。如果小程序是本地部署的，getCodeBase 返回 null，小程序将无法运行。

以下示例展示了如何使用 getCodeBase 方法加载 strawberry.jpg 文件。

LoadImageApplet.java 包含了这个示例的完整代码，这个小程序需要 strawberry.jpg 图像文件。

除了从文件或 URLS 读取外，Image I/O 还可以从其他来源读取，比如 InputStream。ImageIO.read() 对于大多数应用程序来说是最直接的便利 API，但 javax.imageio.ImageIO 类提供了更多静态方法，用于更高级的 Image I/O API 的用法。这个类上的方法集仅代表了用于发现关于图像信息和控制图像解码（读取）过程的丰富 API 集合的一部分。

我们将在 写入/保存图像 部分中进一步探讨 Image I/O 的其他功能。

绘制图像

原文：docs.oracle.com/javase/tutorial/2d/images/drawimage.html

正如您已经了解的那样，Graphics.drawImage方法在特定位置绘制图像：

boolean Graphics.drawImage(Image img,
                   int x, int y,
                   ImageObserver observer);

x,y位置指定了图像左上角的位置。observer参数通知应用程序异步加载的图像更新。observer参数通常不直接使用，对于BufferedImage类来说，通常为 null。

描述的方法仅适用于整个图像要绘制的情况，将图像像素映射到用户空间坐标 1:1。有时应用程序需要绘制图像的一部分（子图像），或者缩放图像以覆盖绘图表面的特定区域，或在绘制之前对图像进行变换或过滤。

drawImage()方法的重载执行这些操作。例如，drawImage()方法的以下重载使您可以绘制指定图像的指定区域的尽可能多的部分，将其缩放以适合目标可绘制表面的指定区域：

boolean Graphics.drawImage(Image img,
       int dstx1, int dsty1, int dstx2, int dsty2,
       int srcx1, int srcy1, int srcx2, int srcy2,
       ImageObserver observer);

src参数表示要复制和绘制的图像区域。dst参数显示要由源区域覆盖的目标区域。dstx1, dsty1坐标定义了绘制图像的位置。目标区域的宽度和高度维度由以下表达式计算：(dstx2-dstx1), (dsty2-dsty1)。如果源区域和目标区域的尺寸不同，Java 2D API 将根据需要进行放大或缩小。

以下代码示例将图像分成四个象限，并随机将源图像的每个象限绘制到目标的不同象限。

此小程序的完整代码在JumbledImageApplet.java中。

此示例使用以下代码绘制混乱的duke_skateboard.jpg图像。它迭代源图像的四个子图像，依次将每个子图像绘制到随机选择的目标象限中。

/* divide the image 'bi' into four rectangular
 * areas and draw each of these areas in to a
 * different part of the image, so as to jumble
 * up the image.  'cells' is an array which has
 * been populated with values which redirect
 * drawing of one subarea to another subarea.
 */
int cellWidth = bi.getWidth(null)/2;
int cellHeight = bi.getHeight(null)/2;
for (int x=0; x<2; x++) {
    int sx = x*cellWidth;
    for (int y=0; y<2; y++) {
        int sy = y*cellHeight;
        int cell = cells[x*2+y];
        int dx = (cell / 2) * cellWidth;
        int dy = (cell % 2) * cellHeight;
        g.drawImage(bi,
                    dx, dy, 
                    x+cellWidth, dy+cellHeight,
                    sx, sy,
                    sx+cellWidth, sy+cellHeight,
                    null);
    }
}

图像过滤

除了复制和缩放图像外，Java 2D API 还可以对图像进行滤镜处理。滤镜是通过将算法应用于源图像的像素来绘制或生成新图像。可以使用以下方法应用图像滤镜：

void Graphics2D.drawImage(BufferedImage img,
                          BufferedImageOp op,
                          int x, int y)

BufferedImageOp 参数实现了滤镜。以下小程序代表了一个在文本上方绘制的图像。拖动滑块以通过图像显示更多或更少的文本，并使图像更加透明。

以下代码显示了如何通过使用RescaleOp对象对带有alpha通道的BufferedImage对象执行滤镜操作，并通过该对象重新调整 alpha 通道。alpha 通道确定每个像素的透明度。它还指定了此图像覆盖的程度。

/* Create an ARGB BufferedImage */
BufferedImage img = ImageIO.read(imageSrc);
int w = img.getWidth(null);
int h = img.getHeight(null);
BufferedImage bi = new
    BufferedImage(w, h, BufferedImage.TYPE_INT_ARGB);
Graphics g = bi.getGraphics();
g.drawImage(img, 0, 0, null);

/*
 * Create a rescale filter op that makes the image
 * 50% opaque.
 */
float[] scales = { 1f, 1f, 1f, 0.5f };
float[] offsets = new float[4];
RescaleOp rop = new RescaleOp(scales, offsets, null);

/* Draw the image, applying the filter */
g2d.drawImage(bi, rop, 0, 0);

完整示例在SeeThroughImageApplet.java中包含了使用滑块调整透明度从初始 50%的代码。此示例还需要 duke_skateboard.jpg 图像。

RescaleOp 对象只是可以创建的许多滤镜之一。Java 2D API 具有几种内置滤镜，包括以下内容：

• ConvolveOp。每个输出像素都是从源图像中周围像素计算出来的。可用于模糊或锐化图像。

• AffineTransformOp。此滤镜通过在像素位置上应用变换将源中的像素映射到目标中的不同位置。

• LookupOp。此滤镜使用应用提供的查找表重新映射像素颜色。

• RescaleOp。此滤镜将颜色乘以某个因子。可用于使图像变亮或变暗，增加或减少其不透明度等。

以下示例使用了描述的每个滤镜以及缩放：

此小程序的完整代码在ImageDrawingApplet.java中，此小程序需要 bld.jpg 图像。

使用下拉菜单选择图像缩放或滤镜操作。

创建和绘制图像

原文：docs.oracle.com/javase/tutorial/2d/images/drawonimage.html

我们已经知道如何加载现有图像，该图像在您的系统中创建并存储，或者在任何网络位置。但是，您可能还想创建一个新图像作为像素数据缓冲区。

在这种情况下，您可以手动创建一个 BufferedImage 对象，使用该类的三个构造函数：

• new BufferedImage(width, height, type) - 构造一个预定义图像类型的 BufferedImage。

• new BufferedImage(width, height, type, colorModel) - 构造一个预定义图像类型的 BufferedImage：TYPE_BYTE_BINARY 或 TYPE_BYTE_INDEXED。

• new BufferedImage(colorModel, raster, premultiplied, properties) - 使用指定的 ColorModel 和 Raster 构造一个新的 BufferedImage。

另一方面，我们可以使用 Component 类的方法。这些方法可以分析给定 Component 或 GraphicsConfiguration 的显示分辨率，并创建一个适当类型的图像。

• Component.createImage(width, height)

• GraphicsConfiguration.createCompatibleImage(width, height)

• GraphicsConfiguration.createCompatibleImage(width, height, transparency)

GraphicsConfiguration 返回一个 BufferedImage 类型的对象，但 Component 返回一个 Image 类型的对象，如果您需要一个 BufferedImage 对象，那么您可以在代码中执行 instanceof 并转换为 BufferedImage。

正如在之前的课程中已经提到的，我们不仅可以在屏幕上渲染图像。图像本身可以被视为一个绘图表面。您可以使用 BufferedImage 类的 createGraphics() 方法来实现这一目的：

...

BufferedImage off_Image =
  new BufferedImage(100, 50,
                    BufferedImage.TYPE_INT_ARGB);

Graphics2D g2 = off_Image.createGraphics();

另一个有趣的离屏图像的用途是自动双缓冲。这个功能允许通过将图像绘制到后备缓冲区，然后将该缓冲区复制到屏幕上，而不是直接绘制到屏幕上，从而避免动画图像的闪烁。

Java 2D 还允许访问用于离屏图像的硬件加速，这可以提供更好的渲染性能以及从这些图像复制。您可以通过使用 Image 类的以下方法来获得此功能的好处：

• getCapabilities 方法允许您确定图像当前是否加速。

• setAccelerationPriority 方法允许您设置有关图像加速重要性的提示。

• getAccelerationPriority 方法获取有关加速重要性的提示。

写入/保存图像

原文：docs.oracle.com/javase/tutorial/2d/images/saveimage.html

本课程从解释如何使用javax.imageio包开始，将图像从外部图像格式加载到 Java 2D 使用的内部BufferedImage格式。然后解释如何使用Graphics.drawImage()来绘制该图像，可选择进行滤镜处理。

最后一阶段是将BufferedImage对象保存为外部图像格式。这可能是最初由Image I/O类从外部图像格式加载并可能使用 Java 2D API 修改的图像，也可能是由 Java 2D 创建的图像。

Image I/O类提供了一种简单的方法，在以下示例中以各种图像格式保存图像：

static boolean ImageIO.write(RenderedImage im, 
                             String formatName,
                             File output)  throws IOException

注意： BufferedImage类实现了RenderedImage接口。

。

formatName参数选择要保存BufferedImage的图像格式。

try {
    // retrieve image
    BufferedImage bi = getMyImage();
    File outputfile = new File("saved.png");
    ImageIO.write(bi, "png", outputfile);
} catch (IOException e) {
    ...
}

ImageIO.write方法调用实现 PNG 写入的代码，即“PNG 写入插件”。术语插件用于Image I/O是可扩展的，可以支持各种格式。

但以下标准图像格式插件：JPEG、PNG、GIF、BMP 和 WBMP 始终存在。

每种图像格式都有其优点和缺点：

对于大多数应用程序来说，使用这些标准插件就足够了。它们的优点是易于获取。Image I/O类提供了一种插入对额外格式的支持的方式，可以使用许多这样的插件。如果您想知道系统中可加载或保存的文件格式，可以使用ImageIO类的getReaderFormatNames和getWriterFormatNames方法。这些方法返回一个字符串数组，列出了此 JRE 支持的所有格式。

String writerNames[] = ImageIO.getWriterFormatNames();

返回的名称数组将包括任何已安装的附加插件，这些名称中的任何一个都可以用作格式名称来选择图像写入器。以下代码示例是一个简单版本的完整图像编辑/修饰程序，使用了修订版本的ImageDrawingApplet.java示例程序，可以按以下方式使用：

• 图像首先通过 Image I/O 加载

• 用户从下拉列表中选择一个滤镜，然后绘制一个新的更新图像

• 用户从下拉列表中选择保存格式

• 接下来会出现文件选择器，用户选择保存图像的位置

• 修改后的图像现在可以被其他桌面应用程序查看。

这个示例的完整代码在SaveImage.java中表示。

在本课程中，您仅学习了Image I/O的基础知识，该知识提供了广泛的支持，包括直接使用ImageWriter插件来实现对编码过程的更精细控制。 ImageIO 可以写入多个图像、图像元数据，并确定质量与大小之间的权衡。更多信息请参见Java Image I/O API 指南。

课程：打印

原文：docs.oracle.com/javase/tutorial/2d/printing/index.html

由于 Java 2D API 使您能够在任何表面上绘制，因此其自然扩展是能够打印 Java 2D 图形。打印机可以被视为与显示器一样的图形设备。

Java 2D 打印 API 不仅限于打印图形。它还使您能够打印应用程序用户界面的内容。内容可以通过将原始数据发送到打印机并在 Java 2D 打印 API 的格式控制下进行打印，或者使用 Java 2D 图形 API 来打印。

在这节课中，您将探索 Java 2D 打印 API 的打印机和作业控制功能，这些功能是对渲染元素的补充。您将学习如何查找系统或网络上配置的打印机，并发现有关这些打印机的信息，例如支持的纸张尺寸，并选择这些属性进行打印和用户对话框。

参与打印的主要类和接口在java.awt.print和javax.print包中（最后一个包允许您访问打印服务）。

基本的打印操作在以下部分中表示：

• 一个基本的打印程序 – 本节描述了Printable接口并呈现了一个基本的打印程序。

• 使用打印设置对话框– 本节解释了如何显示打印设置对话框。

• 打印多页文档 – 本节解释了如何使用分页打印多页文档。

• 使用打印服务和属性 – 本节教您有关打印服务的知识，如何指定打印数据格式，以及如何使用javax.print包创建打印作业。

• 打印用户界面的内容 – 本节解释了如何打印窗口或框架的内容。

• Swing 组件中的打印支持 – 本节简要描述了Swing中相关打印功能，并引用了特定的Swing类和接口。

一个基本的打印程序

原文：docs.oracle.com/javase/tutorial/2d/printing/printable.html

本节解释了如何创建一个基本的打印程序，显示打印对话框，并将文本“Hello World”打印到所选打印机。

打印任务通常由两部分组成：

• 作业控制 — 创建打印作业，将其与打印机关联，指定副本数量，并与用户打印对话框交互。

• 页面成像 — 将内容绘制到页面上，并管理跨页的内容（分页）。

首先创建打印作业。表示打印作业和大多数其他相关类的类位于java.awt.print包中。

import java.awt.print.*;

PrinterJob job = PrinterJob.getPrinterJob();

接下来提供代码，通过实现Printable接口将内容呈现到页面上。

class HelloWorldPrinter
              implements Printable { ... }
...
job.setPrintable(new HelloWorldPrinter());

应用程序通常会显示打印对话框，以便用户可以调整各种选项，如副本数量、页面方向或目标打印机。

boolean doPrint = job.printDialog();

此对话框会一直显示，直到用户批准或取消打印。如果doPrint变量为 true，则用户已经下达打印命令。如果doPrint变量为 false，则用户取消了打印作业。由于显示对话框是可选的，返回的值纯粹是信息性的。

如果doPrint变量为 true，则应用程序将通过调用PrinterJob.print方法请求打印作业。

if (doPrint) {
    try {
        job.print();
    } catch (PrinterException e) {
        // The job did not successfully
        // complete
    }
}

如果发送作业到打印机时出现问题，将抛出PrinterException。然而，由于PrinterJob.print方法一旦作业发送到打印机就会返回，用户应用程序无法检测到纸张卡住或缺纸等问题。这个作业控制样板对于基本的打印使用已经足够。

Printable接口只有一个方法：

public int print(Graphics graphics,
           PageFormat pf, int page)
           throws PrinterException;

PageFormat类描述了页面方向（纵向或横向）及其大小和可成像区域，单位为 1/72 英寸。可成像区域考虑了大多数打印机的边距限制（硬件边距）。可成像区域是这些边距内的空间，在实践中通常进一步限制以留出页眉或页脚的空间。

page参数是将要呈现的基于零的页码。

以下代码表示完整的Printable实现：

import java.awt.print.*;
import java.awt.*;

public class HelloWorldPrinter
    implements Printable {

  public int print(Graphics g, PageFormat pf, int page)
      throws PrinterException {

    // We have only one page, and 'page'
    // is zero-based
    if (page > 0) {
         return NO_SUCH_PAGE;
    }

    // User (0,0) is typically outside the
    // imageable area, so we must translate
    // by the X and Y values in the PageFormat
    // to avoid clipping.
    Graphics2D g2d = (Graphics2D)g;
    g2d.translate(pf.getImageableX(), pf.getImageableY());

    // Now we perform our rendering
    g.drawString("Hello world!", 100, 100);

    // tell the caller that this page is part
    // of the printed document
    return PAGE_EXISTS;
  }
}

此示例的完整代码在HelloWorldPrinter.java中。

将Graphics实例发送到打印机基本上与将其呈现到屏幕相同。在这两种情况下，您需要执行以下步骤：

• 绘制测试字符串与描述绘制到Graphics2D的其它操作一样简单。

• 打印机图形具有更高的分辨率，这对大多数代码来说应该是透明的。

• Printable.print() 方法由打印系统调用，就像 Component.paint() 方法被调用来在显示器上绘制组件一样。打印系统会在页面 0、1、..等等调用 Printable.print() 方法，直到 print() 方法返回 NO_SUCH_PAGE。

• print() 方法可能会在文档完成之前多次以相同的页面索引被调用。当用户指定了诸如多份拷贝和逐份选项等属性时，会应用此功能。

• PageFormat 的可打印区域决定了剪切区域。可打印区域在计算分页或者如何跨打印页面展示内容时也很重要，因为页面断点是由每页能容纳多少内容决定的。

  ---

  注意： 如果用户指定了不涉及特定页面索引的不同页面范围，那么对于某些页面索引，可能会跳过对 print() 方法的调用。

  ---

使用打印设置对话框

原文：docs.oracle.com/javase/tutorial/2d/printing/dialog.html

传统上，用户希望看到页面设置和打印对话框。从打印对话框中，您可以选择打印机，指定要打印的页面，并设置副本数量。

当用户按下与打印命令相关的按钮或从打印菜单中选择项目时，应用程序会显示打印对话框。要显示此对话框，请调用PrinterJob类的printDialog方法：

PrinterJob pj = PrinterJob.getPrinterJob();
...
    if (pj.printDialog()) {
        try {pj.print();}
        catch (PrinterException exc) {
            System.out.println(exc);
         }
     }   
...    

如果用户点击确定按钮离开对话框，则此方法返回true，否则返回false。对话框中用户的选择受限于已设置到PrinterJob的页面的数量和格式。

上述代码片段中的printDialog方法打开一个本机打印对话框。PrintDialogExample.java代码示例展示了如何显示跨平台打印对话框。

你可以通过使用页面设置对话框来更改包含在PageFormat对象中的页面设置信息。

要显示页面设置对话框，请调用PrinterJob类的pageDialog方法。

PrinterJob pj = PrinterJob.getPrinterJob();
PageFormat pf = pj.pageDialog(pj.defaultPage());

页面设置对话框使用传递给pageDialog的参数进行初始化。如果用户在对话框中点击确定按钮，则将根据用户的选择创建PageFormat实例，然后返回。如果用户取消对话框，则pageDialog将返回原始未更改的PageFormat。

通常，Java 2D 打印 API 要求应用程序显示打印对话框，但有时可能可以在不显示任何对话框的情况下打印。这种类型的打印称为静默打印。在特定情况下可能会很有用，例如，当您需要打印特定数据库每周报告时。在其他情况下，始终建议在打印过程开始时通知用户。

打印多页文档

原文：docs.oracle.com/javase/tutorial/2d/printing/set.html

您已经学会了如何使用Printable接口打印单页文档。但是，文档通常不止一页。分页是识别文档中分页位置并相应打印的过程。

如果要打印多个图形图像，每页一个，使用页面索引来遍历这些页面，并在每页上打印一个。例如，如果几个图像在以下数组中表示：

BufferedImage[] images = new BufferedImage[10];

然后使用以下代码片段中显示的print()方法：

public int print(Graphics graphics,
           PageFormat pageFormat, int pageIndex)
           throws PrinterException {

    if (pageIndex < images.length) {
        graphics.drawImage(images[pageIndex], 100, 100, null);
        return PAGE_EXISTS;
    } else {
        return NO_SUCH_PAGE:
    }
}

如果文档是连续的，应用程序必须计算每页可以容纳多少内容，并在该点分页。如果文本文档由许多行组成，则应用程序必须计算这些行中有多少可以完全适合一页。Point类创建一个表示位置的点(x,y)

要计算单行文本的高度，请使用FontMetrics类。

Font font = new Font("Serif", Font.PLAIN, 10);
FontMetrics metrics = graphics.getFontMetrics(font);
int lineHeight = metrics.getHeight();

PageFormat参数描述了页面的可打印区域。特别是，要找到页面的垂直跨度，请使用以下代码片段：

double pageHeight = pageFormat.getImageableHeight();

使用以下代码片段计算一页上适合的行数和分页数：

int linesPerPage = ((int)pageHeight)/lineHeight);
int numBreaks = (textLines.length-1)/linesPerPage;
int[] pageBreaks = new int[numBreaks];
for (int b=0; b < numBreaks; b++) {
    pageBreaks[b] = (b+1)*linesPerPage; 
}

使用print()方法计算以下原因的可打印区域：

• 文本测量取决于FontRenderContext，这在打印机图形返回的FontMetrics对象中是隐含的，除了在print()方法内部不可用。

• 直到打印发生，页面格式可能不会被揭示。因为如果用户在打印对话框中选择了横向模式，则需要考虑此设置。传递给print()方法的PageFormat对象提供了此信息。

分页位置如下代码片段所示：

/* Draw each line that is on this page.
 * Increment 'y' position by lineHeight
 * for each line.
 */
int y = 0; 
int start = (pageIndex == 0) ? 0 : pageBreaks[pageIndex-1];
int end   = (pageIndex == pageBreaks.length)
                 ? textLines.length : pageBreaks[pageIndex];
for (int line=start; line<end; line++) {
    y += lineHeight;
    g.drawString(textLines[line], 0, y);
}

如果一个文档包含 100 行，每页只能容纳 48 行，则应用程序将打印 3 页，每页在第 48 行和第 96 行之后分页。剩余的 4 行将打印在最后一页上。此示例的完整代码在PaginationExample.java中。

PaginationExample代码中使用了以下简化因素：

• 每页具有相同的高度。

• 使用相同的字体。

使用打印服务和属性

原文：docs.oracle.com/javase/tutorial/2d/printing/services.html

从之前的课程中，您已经了解到 Java 2D 打印 API 支持页面成像，显示打印和页面设置对话框，并指定打印属性。 打印服务是任何打印子系统的另一个关键组件。

Java 打印服务（JPS）API扩展了当前的 Java 2D 打印功能，提供以下功能：

• 应用程序通过动态查询打印机功能来发现满足其需求的打印机。

• 应用程序扩展了包含在 JPS API 中的属性。

• 第三方可以通过服务提供者接口插入其自己的打印服务，打印不同格式，包括 Postscript、PDF 和 SVG。

Java 打印服务 API 由四个包组成：

javax.print包为 Java 打印服务 API 提供了主要的类和接口。 它使客户端和服务器应用程序能够：

• 根据其功能发现和选择打印服务。

• 指定打印数据的格式。

• 将打印作业提交给支持要打印的文档类型的服务。

文档类型规范

DocFlavor类表示打印数据的格式，例如 JPEG 或 PostScript。DocFlavor格式由两部分组成：一个是 MIME 类型，另一个是表示类名称。 MIME 类型描述了格式，文档表示类名称指示文档如何传递给打印机或输出流。 应用程序使用DocFlavor和属性集来查找具有属性集指定功能的打印机。 此代码示例演示了获取能够将 GIF 图像转换为 PostScript 的StreamPrintService对象的StreamPrintServiceFactory对象数组：

DocFlavor flavor  = DocFlavor.INPUT_STREAM.GIF;
String psMimeType = DocFlavor.BYTE_ARRAY.
                    POSTSCRIPT.getMimeType();
StreamPrintServiceFactory[] psfactories =
              StreamPrintServiceFactory.
              lookupStreamPrintServiceFactories(
              flavor, psMimeType);

属性定义

javax.print.attribute和javax.print.attribute.standard包定义了描述打印服务功能、指定打印作业要求以及跟踪打印作业进度的打印属性。

例如，如果您想使用 A4 纸张格式并打印文档的三份副本，则必须创建一组实现PrintRequestAttributeSet接口的以下属性：

PrintRequestAttributeSet attr_set =
    new HashPrintRequestAttributeSet();
attr_set.add(MediaSize.ISO_A4); 
attr_set.add(new Copies(3)); 

然后，您必须将属性集传递给打印作业的print方法，以及DocFlavor。

打印服务发现

应用程序调用抽象类PrintServiceLookup的静态方法来定位具有满足应用程序打印请求能力的打印服务。例如，为了打印一份双面文档的两份副本，应用程序首先需要找到具有双面打印能力的打印机：

DocFlavor doc_flavor = DocFlavor.INPUT_STREAM.PDF;
PrintRequestAttributeSet attr_set =
    new HashPrintRequestAttributeSet();
attr_set.add(new Copies(2));
attr_set.add(Sides.DUPLEX);
PrintService[] service = PrintServiceLookup.
              lookupPrintServices(doc_flavor,
              attr_set);

API 的常见用法

总之，Java 打印服务 API 执行以下步骤来处理打印请求：

1. 选择一个DocFlavor。

2. 创建一组属性。

3. 定位一个可以处理由DocFlavor和属性集指定的打印请求的打印服务。

4. 创建一个封装了DocFlavor和实际打印数据的Doc对象。

5. 从打印服务获取由DocPrintJob表示的打印作业。

6. 调用打印作业的print方法。

有关 Java 打印服务的更多信息，请参阅Java 2D 打印服务 API 用户指南。

打印用户界面的内容

原文：docs.oracle.com/javase/tutorial/2d/printing/gui.html

另一个常见的打印任务是打印窗口或框架的内容，可以是全部内容，也可以是部分内容。窗口可能包含以下组件：工具栏、按钮、滑块、文本标签、可滚动文本区域、图像和其他图形内容。所有这些组件都是使用 Java 2D 打印 API 的以下方法打印的：

java.awt.Component.print(Graphics g);
java.awt.Component.printAll(Graphics g);

以下图表示一个简单的用户界面。

创建此用户界面的代码位于示例程序PrintUIWindow.java中。

要打印此窗口，请修改之前打印文本或图像的示例中的代码。结果代码应如下所示：

public int print(Graphics g, PageFormat pf, int page)
    throws PrinterException {
    if (page > 0) {
        return NO_SUCH_PAGE;
    }

    Graphics2D g2d = (Graphics2D)g;
    g2d.translate(pf.getImageableX(), pf.getImageableY());

    // Print the entire visible contents of a
    // java.awt.Frame.
    frame.printAll(g);

    return PAGE_EXISTS;
}

注意： printAll方法的调用是此示例与打印文本或图像示例之间的唯一区别。print(Graphics g)方法反映了用于屏幕渲染的java.awt.Component.paint(Graphics g)方法。使用print()方法而不是paint()方法，因为Components类可能已经重写了print()方法以不同方式处理打印情况。

printAll(Graphics g)方法打印组件及其所有子组件。通常使用此方法打印对象，例如完整窗口，而不是单个组件。

Swing 组件中的打印支持

原文：docs.oracle.com/javase/tutorial/2d/printing/swing.html

在前一节中展示的 PrintUIWindow.java 示例表明打印出的内容与屏幕上看到的完全相同。这种外观看起来是合理的。然而，如果一个窗口是可滚动的，那么当前滚动出视图的内容不会包含在打印输出中。这会在打印机上产生一个倾倒效果。当打印大型组件（如 Swing 表格或文本组件）时，这就成为一个特殊问题。组件可能包含许多行文本，这些文本在屏幕上并不都能完全可见。在这种情况下，以与屏幕显示一致的方式打印组件显示的内容。

要解决这个问题，Swing 表格和所有文本组件都具有打印功能。以下方法直接提供了 Java 2D 打印的使用：

• javax.swing.JTable.print();

• javax.swing.text.JTextComponent.print();

这些方法为它们的内容提供了完整的打印实现。应用程序不需要直接创建 PrinterJob 对象并实现 Printable 接口。调用这些方法会显示打印对话框，并根据用户的选择打印组件的数据。还有其他提供更多选项的方法。

课程：Java2D 高级主题

原文：docs.oracle.com/javase/tutorial/2d/advanced/index.html

本课程向您展示如何使用Graphics2D显示具有花哨轮廓和填充样式的图形，当它们被渲染时如何转换图形，将渲染限制在特定区域，并一般控制图形在被渲染时的外观。您还将学习如何通过组合简单形状来创建复杂的Shape对象，以及如何检测用户何时点击显示的图形基元。这些主题在以下部分中讨论：

变换形状、文本和图像

本节向您展示如何修改默认变换，以便在渲染时对象被平移、旋转、缩放或倾斜。

裁剪绘图区域

你可以使用任何形状作为裁剪路径—即渲染发生的区域。

合成图形

本节介绍了AlphaComposite支持的各种合成样式，并向您展示如何在Graphics2D渲染上下文中设置合成样式。

控制渲染质量

本节描述了Graphics2D支持的渲染提示，并向您展示如何在渲染质量和速度之间的权衡中指定您的偏好。

从几何原语构建复杂形状

本节向您展示如何使用Area类在Shape对象上执行布尔运算。

支持用户交互

本节向您展示如何在图形基元上执行点击检测。

变换形状、文本和图像

原文：docs.oracle.com/javase/tutorial/2d/advanced/transforming.html

您可以在Graphics2D上下文中修改变换属性，以在渲染时移动、旋转、缩放和剪切图形基元。变换属性由AffineTransform类的实例定义。仿射变换是一种变换，如平移、旋转、缩放或剪切，在变换后平行线仍保持平行。

Graphics2D类提供了几种方法来更改变换属性。您可以构造一个新的AffineTransform并通过调用transform来更改Graphics2D的变换属性。

AffineTransform定义了以下工厂方法，以便更容易构造新的变换：

• getRotateInstance

• getScaleInstance

• getShearInstance

• getTranslateInstance

或者，您可以使用Graphics2D的一个变换方法来修改当前变换。当您调用这些便利方法之一时，生成的变换将与当前变换连接，并在渲染期间应用：

• rotate — 用于指定以弧度为单位的旋转角度

• scale — 用于指定x和y方向的缩放因子

• shear — 用于指定x和y方向的剪切因子

• translate — 用于指定x和y方向的平移偏移量

您还可以直接构造一个AffineTransform对象，并通过调用transform方法将其与当前变换连接。

drawImage方法也被重载，允许您指定一个在渲染时应用于图像的AffineTransform。在调用drawImage时指定变换不会影响Graphics2D的变换属性。

示例：变换

下面的程序与StrokeandFill相同，但还允许用户在渲染选定对象时选择要应用的变换。

Transform.java 包含此小程序的完整代码。

当从变换菜单中选择一个变换时，该变换将连接到AffineTransform at上：

public void setTrans(int transIndex) {
    // Sets the AffineTransform.
    switch ( transIndex ) {
    case 0 :
        at.setToIdentity();
        at.translate(w/2, h/2);
        break;
    case 1 :
        at.rotate(Math.toRadians(45));
        break;
    case 2 :
        at.scale(0.5, 0.5);
        break;
    case 3 :
        at.shear(0.5, 0.0);
        break;
    }
}

在显示与菜单选择对应的形状之前，应用程序首先从Graphics2D对象中检索当前变换：

AffineTransform saveXform = g2.getTransform();

此变换将在渲染后恢复到Graphics2D中。

在检索当前变换后，创建另一个AffineTransform，toCenterAt，使形状在面板中心渲染。at AffineTransform被连接到toCenterAt上：

AffineTransform toCenterAt = new AffineTransform();
toCenterAt.concatenate(at);
toCenterAt.translate(-(r.width/2), -(r.height/2));

使用transform方法将toCenterAt变换连接到Graphics2D变换上：

g2.transform(toCenterAt);

渲染完成后，使用setTransform方法恢复原始变换：

g2.setTransform(saveXform);

注意：永远不要使用setTransform方法将坐标变换连接到现有的变换上。setTransform方法会覆盖Graphics2D对象的当前变换，这可能会因其他原因而需要，比如在窗口中定位 Swing 和轻量级组件。执行变换的步骤如下：

1. 使用getTransform方法获取当前变换。

2. 使用transform、translate、scale、shear或rotate来连接一个变换。

3. 执行渲染。

4. 使用setTransform方法恢复原始变换。

绘制区域剪切

原文：docs.oracle.com/javase/tutorial/2d/advanced/clipping.html

任何Shape对象都可以用作限制将呈现的绘图区域的剪切路径。剪切路径是Graphics2D上下文的一部分；要设置剪切属性，调用Graphics2D.setClip并传入定义要使用的剪切路径的Shape。可以通过调用clip方法并传入另一个Shape来缩小剪切路径；剪切设置为当前剪切和指定Shape的交集。

示例：ClipImage

该示例通过动画剪切路径来显示图像的不同部分。

ClipImage.java包含此小程序的完整代码。小程序需要clouds.jpg图像文件。

剪切路径由椭圆和随机设置尺寸的矩形的交集定义。将椭圆传递给setClip方法，然后调用clip将剪切路径设置为椭圆和矩形的交集。

private Ellipse2D ellipse = new Ellipse2D.Float();
private Rectangle2D rect = new Rectangle2D.Float();
...
ellipse.setFrame(x, y, ew, eh);
g2.setClip(ellipse);
rect.setRect(x+5, y+5, ew-10, eh-10);
g2.clip(rect);

示例：Starry

也可以从文本字符串创建一个剪切区域。以下示例使用字符串The Starry Night创建一个TextLayout。然后，获取TextLayout的轮廓。TextLayout.getOutline方法返回一个Shape对象，并从该Shape对象的边界创建一个Rectangle。边界包含布局可以绘制的所有像素。将图形上下文中的颜色设置为蓝色，并绘制轮廓形状，如下图和代码片段所示。

FontRenderContext frc = g2.getFontRenderContext();
Font f = new Font("Helvetica", 1, w/10);
String s = new String("The Starry Night");
TextLayout textTl = new TextLayout(s, f, frc);
AffineTransform transform = new AffineTransform();
Shape outline = textTl.getOutline(null);
Rectangle r = outline.getBounds();
transform = g2.getTransform();
transform.translate(w/2-(r.width/2), h/2+(r.height/2));
g2.transform(transform);
g2.setColor(Color.blue);
g2.draw(outline);   

接下来，使用从getOutline创建的Shape对象在图形上下文中设置一个剪切区域。将梵高的著名绘画作品The Starry Night的starry.gif图像绘制到从Rectangle对象的左下角开始的剪切区域中。

g2.setClip(outline);
g2.drawImage(img, r.x, r.y, r.width, r.height, this);

Starry.java 包含了这个程序的完整代码。这个小程序需要 Starry.gif 图像文件。

合成图形

原文：docs.oracle.com/javase/tutorial/2d/advanced/compositing.html

AlphaComposite 类封装了各种合成样式，确定重叠对象如何被渲染。AlphaComposite 还可以具有指定透明度的 alpha 值：alpha = 1.0 完全不透明，alpha = 0.0 完全透明（清除）。AlphaComposite 支持下表中显示的大多数标准 Porter-Duff 合成规则。

合成规则	描述
源覆盖 (SRC_OVER)	如果正在渲染的对象（源）中的像素与先前渲染的像素（目标）位于相同位置，则源像素将覆盖目标像素。
源中 (SRC_IN)	如果源和目标重叠，只有源区域的像素被渲染。
源减去 (SRC_OUT)	如果源和目标重叠，只有源区域外的像素被渲染。重叠区域的像素被清除。
目标覆盖 (DST_OVER)	如果源和目标重叠，只有源区域外的像素被渲染。重叠区域的像素不会改变。
目标中 (DST_IN)	如果源和目标重叠，源的 alpha 值将应用于重叠区域的目标像素。如果 alpha = 1.0，则重叠区域的像素保持不变；如果 alpha 为 0.0，则清除重叠区域的像素。
目标减去 (DST_OUT)	如果源和目标重叠，源的 alpha 值将应用于重叠区域的目标像素。如果 alpha = 1.0，则清除重叠区域的像素；如果 alpha 为 0.0，则重叠区域的像素保持不变。
清除 (CLEAR)	如果源和目标重叠，清除重叠区域的像素。

要更改 Graphics2D 类使用的合成样式，请创建一个 AlphaComposite 对象并将其传递给 setComposite 方法。

示例：合成

该程序演示了各种合成样式和 alpha 组合的效果。

Composite.java 包含了此 applet 的完整代码。

通过调用 AlphaComposite.getInstance 并指定所需的合成规则来构造一个新的 AlphaComposite 对象 ac。

AlphaComposite ac =
  AlphaComposite.getInstance(AlphaComposite.SRC);

当选择不同的合成规则或 alpha 值时，会再次调用 AlphaComposite.getInstance，并将新的 AlphaComposite 分配给 ac。所选的 alpha 值除了每个像素的 alpha 值外还会应用，并作为第二个参数传递给 AlphaComposite.getInstance。

ac = AlphaComposite.getInstance(getRule(rule), alpha);

通过将 AlphaComposite 对象传递给 Graphics 2D 的 setComposite 方法来修改合成属性。对象被渲染到 BufferedImage 中，然后复制到屏幕上，因此合成属性被设置在 BufferedImage 的 Graphics2D 上下文中：

BufferedImage buffImg = new BufferedImage(w, h,
                        BufferedImage.TYPE_INT_ARGB);
Graphics2D gbi = buffImg.createGraphics();
...
gbi.setComposite(ac);

控制渲染质量

原文：docs.oracle.com/javase/tutorial/2d/advanced/quality.html

使用Graphics2D类的渲染提示属性来指定您是希望对象尽可能快地呈现还是您更喜欢呈现质量尽可能高。

要设置或更改Graphics2D上下文中的渲染提示属性，请构造一个RenderingHints对象，并通过使用setRenderingHints方法将其传递给Graphics2D。如果您只想设置一个提示，可以调用Graphics2D的setRenderingHint并指定要设置的提示的键值对。（键值对在RenderingHints类中定义。）

例如，要设置抗锯齿首选项（如果可能的话），您可以使用setRenderingHint：

public void paint (graphics g){
    Graphics2D g2 = (Graphics2D)g;
    RenderingHints rh = new RenderingHints(
             RenderingHints.KEY_TEXT_ANTIALIASING,
             RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
    g2.setRenderingHints(rh);
...
}

注意：并非所有平台都支持修改渲染模式，因此指定渲染提示并不保证它们会被使用。

RenderingHints支持以下类型的提示：

| 抗锯齿 | KEY_ANTIALIASING | VALUE_ANTIALIAS_ON VALUE_ANTIALIAS_OFF

VALUE_ANTIALIAS_DEFAULT |

| Alpha 插值 | KEY_ALPHA_INTERPOLATION | VALUE_ALPHA_INTERPOLATION_QUALITY VALUE_ALPHA_INTERPOLATION_SPEED

VALUE_ALPHA_INTERPOLATION_DEFAULT |

| 颜色渲染 | KEY_COLOR_RENDERING | VALUE_COLOR_RENDER_QUALITY VALUE_COLOR_RENDER_SPEED

VALUE_COLOR_RENDER_DEFAULT |

| 抖动 | KEY_DITHERING | VALUE_DITHER_DISABLE VALUE_DITHER_ENABLE

VALUE_DITHER_DEFAULT |

| 分数文本度量 | KEY_FRACTIONALMETRICS | VALUE_FRACTIONALMETRICS_ON VALUE_FRACTIONALMETRICS_OFF

VALUE_FRACTIONALMETRICS_DEFAULT |

| 图像插值 | KEY_INTERPOLATION | VALUE_INTERPOLATION_BICUBIC VALUE_INTERPOLATION_BILINEAR

VALUE_INTERPOLATION_NEAREST_NEIGHBOR |

| 渲染 | KEY_RENDERING | VALUE_RENDER_QUALITY VALUE_RENDER_SPEED

VALUE_RENDER_DEFAULT |

| 笔画规范化控制 | KEY_STROKE_CONTROL | VALUE_STROKE_NORMALIZE VALUE_STROKE_DEFAULT

VALUE_STROKE_PURE |

| 文本抗锯齿 | KEY_TEXT_ANTIALIASING | VALUE_TEXT_ANTIALIAS_ON VALUE_TEXT_ANTIALIAS_OFF

VALUE_TEXT_ANTIALIAS_DEFAULT

VALUE_TEXT_ANTIALIAS_GASP

VALUE_TEXT_ANTIALIAS_LCD_HRGB

VALUE_TEXT_ANTIALIAS_LCD_HBGR

VALUE_TEXT_ANTIALIAS_LCD_VRGB

VALUE_TEXT_ANTIALIAS_LCD_VBGR

|

当提示设置为默认时，使用平台渲染默认值。

从几何原语构建复杂形状

原文：docs.oracle.com/javase/tutorial/2d/advanced/complexshapes.html

构造区域几何（CAG）是通过对现有几何形状执行布尔运算来创建新几何形状的过程。在 Java 2D API 中，Area 类实现了 Shape 接口，并支持以下布尔运算。

	并集		减法
	交集		异或 (XOR)

例子：区域

在这个例子中，Area对象从几个椭圆构建了一个梨形。

Pear.java 包含了这个小程序的完整代码。

每片叶子是通过在两个重叠圆上执行交集操作创建的。

leaf = new Ellipse2D.Double();
...
leaf1 = new Area(leaf);
leaf2 = new Area(leaf);
...
leaf.setFrame(ew-16, eh-29, 15.0, 15.0);
leaf1 = new Area(leaf);
leaf.setFrame(ew-14, eh-47, 30.0, 30.0);
leaf2 = new Area(leaf);
leaf1.intersect(leaf2);
g2.fill(leaf1);
...
leaf.setFrame(ew+1, eh-29, 15.0, 15.0);
leaf1 = new Area(leaf);
leaf2.intersect(leaf1);
g2.fill(leaf2);

重叠的圆也被用来通过减法操作构建茎。

stem = new Ellipse2D.Double();
...
stem.setFrame(ew, eh-42, 40.0, 40.0);
st1 = new Area(stem);
stem.setFrame(ew+3, eh-47, 50.0, 50.0);
st2 = new Area(stem);
st1.subtract(st2);
g2.fill(st1);

梨的主体是通过在一个圆和一个椭圆上执行并集操作构建的。

circle = new Ellipse2D.Double();
oval = new Ellipse2D.Double();
circ = new Area(circle);
ov = new Area(oval);
...
circle.setFrame(ew-25, eh, 50.0, 50.0);
oval.setFrame(ew-19, eh-20, 40.0, 70.0);
circ = new Area(circle);
ov = new Area(oval);
circ.add(ov);
g2.fill(circ);

支持用户交互

原文：docs.oracle.com/javase/tutorial/2d/advanced/user.html

为了让用户与您显示的图形进行交互，您需要能够确定用户何时点击其中一个图形。Graphics2D 类的 hit 方法提供了一种简单确定鼠标点击是否发生在特定 Shape 对象上的方法。或者，您可以获取鼠标点击的位置并在 Shape 上调用 contains 方法来确定点击是否在 Shape 的边界内。

如果您使用基本文本，可以通过获取与文本对应的轮廓 Shape，然后使用该 Shape 调用 hit 或 contains 方法来执行简单的点击测试。支持文本编辑需要更复杂的点击测试。如果要允许用户编辑文本，通常应使用 Swing 可编辑文本组件之一。如果您使用基本文本并使用 TextLayout 类来管理文本的形状和位置，则还可以使用 TextLayout 来执行文本编辑的点击测试。有关更多信息，请参阅 Java 2D 程序员指南 中的文本和字体章节，或查看下面的 HitTestSample 示例，该示例使用 TextLayout 执行简单的点击测试。

示例：ShapeMover

此小程序允许用户在小程序窗口内拖动 Shape。Shape 在每个鼠标位置重新绘制，以提供用户拖动时的反馈。

ShapeMover.java 包含了此小程序的完整代码。

当鼠标按下时，调用 contains 方法来确定光标是否在矩形的边界内。如果是，则更新矩形的位置。

public void mousePressed(MouseEvent e){
    last_x = rect.x - e.getX();
    last_y = rect.y - e.getY();
    if(rect.contains(e.getX(),
        e.getY())) updateLocation(e);
    ...

public void updateLocation(MouseEvent e){
    rect.setLocation(last_x + e.getX(),
        last_y + e.getY());
    ...
    repaint();

您可能会注意到，在每个鼠标位置重新绘制 Shape 是很慢的，因为填充的矩形每次移动时都会重新渲染。使用双缓冲可以消除这个问题。如果使用 Swing，绘图将自动双缓冲；您无需更改渲染代码。这个程序的 Swing 版本的代码是 SwingShapeMover.java。

示例：HitTestSample

这个应用程序通过在用户点击 TextLayout 上的位置绘制默认插入符来说明点击测试，如下图所示。

HitTestSample.java 包含了这个小程序的完整代码。

mouseClicked 方法使用 TextLayout.hitTestChar 返回一个包含鼠标点击位置（插入索引）的 java.awt.font.TextHitInfo 对象在 TextLayout 对象中。

TextLayout 的 getAscent、getDescent 和 getAdvance 方法返回的信息被用来计算 TextLayout 对象的原点位置，使其水平和垂直居中。

...

private Point2D computeLayoutOrigin() {
  Dimension size = getPreferredSize();
  Point2D.Float origin = new Point2D.Float();

  origin.x = (float) (size.width -
             textLayout.getAdvance()) / 2;   
  origin.y = 
    (float) (size.height -
             textLayout.getDescent() +
             textLayout.getAscent())/2;
  return origin;
}

...

public void paintComponent(Graphics g) {
  super.paintComponent(g);
  setBackground(Color.white);
  Graphics2D graphics2D = (Graphics2D) g;                
  Point2D origin = computeLayoutOrigin();
  graphics2D.translate(origin.getX(),
                       origin.getY());

  // Draw textLayout.
  textLayout.draw(graphics2D, 0, 0);

  // Retrieve caret Shapes for insertionIndex.
  Shape[] carets =
      textLayout.getCaretShapes(insertionIndex);

  // Draw the carets.  carets[0] is the strong
  // caret and carets[1] is the weak caret.   
  graphics2D.setColor(STRONG_CARET_COLOR);
  graphics2D.draw(carets[0]);                
  if (carets[1] != null) {
    graphics2D.setColor(WEAK_CARET_COLOR);
    graphics2D.draw(carets[1]);
  }       
}

...

private class HitTestMouseListener
              extends MouseAdapter {

    /**
     * Compute the character position of the
     * mouse click.
     */     
    public void mouseClicked(MouseEvent e) {

      Point2D origin = computeLayoutOrigin();

      // Compute the mouse click location
      // relative to textLayout's origin.
      float clickX =
          (float) (e.getX() - origin.getX());
      float clickY =
          (float) (e.getY() - origin.getY());

      // Get the character position of the
      // mouse click.
      TextHitInfo currentHit =
          textLayout.hitTestChar(clickX, clickY);
      insertionIndex =
          currentHit.getInsertionIndex();

      // Repaint the Component so the new
      // caret(s) will be displayed.
      hitPane.repaint();
    }

路径：声音

原文：docs.oracle.com/javase/tutorial/sound/index.html

Java Sound API 是一个低级 API，用于影响和控制声音媒体的输入和输出，包括音频和 MIDI（Musical Instrument Digital Interface）数据。 Java Sound API 提供了对通常需要的声音输入和输出功能的明确控制，以促进可扩展性和灵活性。

Java Sound API 满足了各种应用程序开发人员的需求。潜在的应用领域包括：

• 通信框架，如会议和电话会议

• 最终用户内容传递系统，如使用流媒体内容的媒体播放器和音乐

• 交互式应用程序，如使用动态内容的游戏和网站

• 内容创建和编辑

• 工具、工具包和实用程序

Java Sound API 在 Java 平台上提供了最低级别的声音支持。它为应用程序提供了对声音操作的大量控制，并且是可扩展的。例如，Java Sound API 提供了安装、访问和操作系统资源的机制，如音频混音器、MIDI 合成器、其他音频或 MIDI 设备、文件读取器和写入器以及声音格式转换器。 Java Sound API 不包括复杂的声音编辑器或图形工具，但它提供了可以构建此类程序的功能。它强调低于最终用户通常期望的低级别控制。

Java Sound API 包括对数字音频和 MIDI 数据的支持。这两个主要功能模块分别在不同的包中提供：

• javax.sound.sampled – 该包指定了用于捕获、混合和播放数字（采样）音频的接口。

• javax.sound.midi – 该包提供了用于 MIDI 合成、序列化和事件传输的接口。

另外两个包允许服务提供商（而不是应用程序开发人员）创建自定义软件组件，以扩展 Java Sound API 的实现的功能：

• javax.sound.sampled.spi

• javax.sound.midi.spi

本页介绍了采样音频系统、MIDI 系统和 SPI 包。每个包稍后在教程中进行了更详细的讨论。

注意：

还有其他 Java 平台 API 也涉及声音相关元素。Java 媒体框架 API (JMF) 是当前作为 Java 平台标准扩展可用的更高级 API。JMF 指定了用于捕获和播放基于时间的媒体的统一架构、消息协议和编程接口。JMF 为基本媒体播放器应用程序提供了更简单的解决方案，并且它实现了不同媒体类型之间的同步，例如音频和视频。另一方面，专注于声音的程序可以从 Java Sound API 中受益，特别是如果它们需要更高级的功能，例如精细控制缓冲音频播放或直接操作 MIDI 合成器。其他具有声音方面的 Java API 包括 Java 3D 和用于电话和语音的 API。这些 API 的任何实现可能在内部使用 Java Sound API 的实现，但不是必须的。

什么是采样音频？

javax.sound.sampled 包处理数字音频数据，Java Sound API 将其称为采样音频。样本 是信号的连续快照。在音频的情况下，信号是声波。麦克风将声学信号转换为相应的模拟电信号，模拟-数字转换器将该模拟信号转换为采样数字形式。以下图显示了声音录制中的一个瞬间。

采样声波

这个图表将声压（振幅）绘制在垂直轴上，时间绘制在水平轴上。模拟声波的振幅以一定速率周期性地进行测量，导致离散样本（图中的红色数据点）构成数字音频信号。中心水平线表示零振幅；线上的点为正值样本，线下的点为负值。模拟信号的数字近似精度取决于其时间分辨率（采样率）和振幅分辨率（量化），即用于表示每个样本的位数。作为参考，用于存储在光盘上的音频每秒采样 44,100 次，并以每个样本 16 位表示。

这里稍微宽松地使用了“采样音频”这个术语。声波可以在被保留为模拟形式的同时以离散间隔进行采样。然而，对于 Java Sound API 来说，“采样音频”等同于“数字音频”。

通常，计算机上的采样音频来自声音录制，但声音也可以被合成生成（例如，创建触摸电话的声音）。术语“采样音频”指的是数据类型，而不是其来源。

Java Sound API 不假设特定的音频硬件配置；它设计为允许在系统上安装不同类型的音频组件，并通过 API 访问。Java Sound API 支持常见功能，例如从声卡输入和输出（例如，用于录制和播放声音文件）以及混合多个音频流。以下是一个典型音频架构的示例：

典型音频架构

在这个例子中，像声卡这样的设备具有各种输入和输出端口，并且混音是在软件中提供的。混音器可能接收从文件中读取的数据，从网络流式传输的数据，应用程序动态生成的数据，或者由 MIDI 合成器产生的数据。混音器将所有音频输入组合成一个流，可以发送到输出设备进行渲染。

什么是 MIDI？

javax.sound.midi包含用于传输和排序 MIDI 事件以及从这些事件中合成声音的 API。

而采样音频是声音本身的直接表示，MIDI 数据可以被视为创建声音的配方，特别是音乐声音的配方。与音频数据不同，MIDI 数据不直接描述声音。相反，它描述影响由 MIDI 启用的设备或乐器执行的声音（或动作）的事件，例如合成器。 MIDI 数据类似于图形用户界面的键盘和鼠标事件。在 MIDI 的情况下，这些事件可以被视为对音乐键盘以及乐器上的各种踏板、滑块、开关和旋钮的动作。这些事件不一定实际起源于硬件乐器；它们可以在软件中模拟，并且可以存储在 MIDI 文件中。一个可以创建、编辑和执行这些文件的程序被称为序列器。许多计算机声卡包括可以通过序列器发送其 MIDI 事件的 MIDI 可控音乐合成器芯片。合成器也可以完全在软件中实现。合成器解释它们接收到的 MIDI 事件并产生音频输出。通常，从 MIDI 数据合成的声音是音乐声音（例如，与语音相对）。MIDI 合成器还能够生成各种声音效果。

一些声卡包括 MIDI 输入和输出端口，可以连接外部 MIDI 硬件设备（如键盘合成器或其他乐器）。从 MIDI 输入端口，应用程序可以接收外部 MIDI 设备生成的事件。程序可以使用计算机的内部合成器演奏音乐表演，将其保存为 MIDI 文件，或将其渲染为音乐符号。程序可以使用 MIDI 输出端口来演奏外部乐器，或控制其他外部设备，如录音设备。

以下图示了基于 Java Sound API 的可能 MIDI 配置中主要组件之间的功能关系。（与音频一样，Java Sound API 允许安装和连接各种 MIDI 软件设备。此处显示的系统只是一个潜在的场景。）组件之间的数据流由箭头表示。数据可以是标准文件格式，或者（如图示右下角的关键所示），可以是音频、原始 MIDI 字节或时间标记 MIDI 消息。

可能的 MIDI 配置

在此示例中，应用程序通过加载存储在磁盘上的标准 MIDI 文件的音乐乐谱（图中的左侧）来准备音乐表演。标准 MIDI 文件包含轨道，每个轨道都是一个时间标记 MIDI 事件列表。大多数事件代表音乐音符（音高和节奏）。这个 MIDI 文件被读取，然后由软件音序器“演奏”。音序器通过向其他设备发送 MIDI 消息来演奏音乐，例如内部或外部合成器。合成器本身可能会读取包含模拟某些乐器声音指令的声音库文件。如果没有，合成器将使用已加载的任何乐器声音来播放 MIDI 文件中存储的音符。

如图所示，MIDI 事件必须在通过 MIDI 输出端口发送到外部 MIDI 乐器之前被转换为原始（非时间标记）MIDI。同样，从外部 MIDI 源（图中的键盘乐器）进入计算机的原始 MIDI 数据被转换为可以控制合成器的时间标记 MIDI 消息，或者可以由音序器存储以供以后使用。

服务提供者接口

javax.sound.sampled.spi 和 javax.sound.midi.spi 包含的 API 允许软件开发人员创建新的音频或 MIDI 资源，可以单独提供给用户并“插入”到 Java Sound API 的现有实现中。以下是可以以这种方式添加的一些服务（资源）的示例：

• 音频混音器

• MIDI 合成器

• 一个可以读取或写入新类型音频或 MIDI 文件的文件解析器

• 在不同声音数据格式之间进行转换的转换器

在某些情况下，服务是软件接口，用于访问硬件设备的功能，比如声卡，而服务提供者可能与硬件供应商相同。在其他情况下，服务纯粹存在于软件中。例如，合成器或混音器可以是声卡上的芯片的接口，也可以在没有任何硬件支持的情况下实现。

Java Sound API 的实现包含一组基本服务，但服务提供者接口（SPI）包允许第三方创建新服务。这些第三方服务以与内置服务相同的方式集成到系统中。AudioSystem类和MidiSystem类充当协调器，让应用程序明确或隐式地访问服务。对于使用它的应用程序来说，服务的存在通常对其完全透明。服务提供者机制使基于 Java Sound API 的应用程序的用户受益，因为可以向程序添加新的声音功能，而无需新版本的 JDK 或运行时环境，甚至在许多情况下，甚至无需新版本的应用程序本身。

采样包概述

原文：docs.oracle.com/javase/tutorial/sound/sampled-overview.html

javax.sound.sampled 包主要涉及音频传输 - 换句话说，Java Sound API 专注于播放和捕获。 Java Sound API 解决的核心任务是如何将格式化音频数据的字节移入和移出系统。 这项任务涉及打开音频输入和输出设备以及管理填充实时音频数据的缓冲区。 它还可以涉及将多个音频流混合成一个流（无论是用于输入还是输出）。 当用户请求启动、暂停、恢复或停止声音流时，系统内部的声音传输必须得到正确处理。

为了支持对基本音频输入和输出的关注，Java Sound API 提供了在各种音频数据格式之间转换的方法，并且提供了读取和写入常见类型的声音文件的方法。 但是，它并不试图成为一个全面的声音文件工具包。 Java Sound API 的特定实现不必支持广泛的文件类型或数据格式转换。 第三方服务提供商可以提供模块，这些模块可以“插入”到现有实现中，以支持额外的文件类型和转换。

Java Sound API 可以以流式缓冲方式和内存中非缓冲方式处理音频传输。 这里所说的“流式”是指实时处理音频字节； 它并不是指以某种特定格式通过互联网发送音频的众所周知的情况。 换句话说，音频流只是一组连续的音频字节，它们以更多或更少的相同速率到达，以便处理（播放、录制等）。 操作在所有数据到达之前开始。 在流式模型中，特别是在音频输入而不是音频输出的情况下，您不一定事先知道声音的持续时间以及何时会完成到达。 您只需一次处理一个音频数据缓冲区，直到操作停止。 在音频输出（播放）的情况下，如果要播放的声音太大而无法一次性放入内存中，则还需要缓冲数据。 换句话说，您以块的形式将音频字节传递给声音引擎，它会在正确的时间播放每个样本。 提供了机制，使得很容易知道每个块中要传递多少数据。

Java Sound API 还允许在仅播放的情况下进行无缓冲传输，假设您已经拥有所有音频数据并且数据量不太大以适应内存。在这种情况下，应用程序无需缓冲音频，尽管如果需要，仍然可以使用缓冲的实时方法。相反，整个声音可以一次性预加载到内存中以供后续播放。由于所有声音数据都是预先加载的，因此播放可以立即开始，例如，用户点击“开始”按钮时。与缓冲模型相比，这可能是一个优势，因为在缓冲填满之前，播放必须等待第一个缓冲区。此外，内存中的无缓冲模型允许轻松循环（循环）声音或将其设置为数据中的任意位置。

使用 Java Sound API 播放或捕获声音时，您至少需要三样东西：格式化的音频数据，混音器和线路。以下是这些概念的概述。

什么是格式化音频数据？

格式化的音频数据指的是任何一种标准格式的声音。Java Sound API 区分数据格式和文件格式。

数据格式

数据格式告诉您如何解释一系列“原始”采样音频数据的字节，例如已从声音文件中读取的样本，或者已从麦克风输入捕获的样本。例如，您可能需要知道一个样本包含多少比特（表示声音的最短瞬间的表示），同样您可能需要知道声音的采样率（样本应该多快地跟随彼此）。在设置播放或捕获时，您指定正在捕获或播放的声音的数据格式。

在 Java Sound API 中，数据格式由一个AudioFormat对象表示，其中包括以下属性：

• 编码技术，通常是脉冲编码调制（PCM）

• 通道数（单声道为 1，立体声为 2，等等）

• 采样率（每秒每个通道的样本数）

• 每个样本（每个通道）的比特数

• 帧率

• 每帧大小（以字节为单位）

• 字节顺序（大端或小端）

PCM 是声波的一种编码方式。Java Sound API 包括两种使用线性幅度量化的 PCM 编码，以及带符号或无符号整数值。线性量化意味着每个样本中存储的数字与该瞬间的原始声压（除了任何失真）成正比，类似地与振动声音的扬声器或鼓膜的位移成正比，该振动声音在该瞬间发生。例如，CD 使用线性 PCM 编码的声音。 mu-law 编码和 a-law 编码是常见的非线性编码，它们提供音频数据的更紧缩版本；这些编码通常用于电话或语音录音。非线性编码将原始声音的幅度通过非线性函数映射到存储值，该函数可以设计为给予安静声音比响亮声音更多的幅度分辨率。

一个帧包含特定时间所有通道的数据。对于 PCM 编码的数据，帧只是所有通道在给定时间点的同时样本集，没有任何附加信息。在这种情况下，帧速率等于采样率，帧大小以字节为单位是通道数乘以位采样大小，再除以字节的位数。

对于其他类型的编码，一个帧可能包含除样本之外的附加信息，并且帧速率可能与采样率完全不同。例如，考虑 MP3（MPEG-1 音频第三层）编码，它在当前版本的 Java Sound API 中没有明确提到，但可以由 Java Sound API 的实现或第三方服务提供商支持。在 MP3 中，每个帧包含一系列样本的压缩数据包，而不仅仅是每个通道的一个样本。由于每个帧封装了一整个系列的样本，因此帧速率比采样率慢。帧还包含一个头部。尽管有头部，但帧的字节大小比等量的 PCM 帧的字节大小要小。（毕竟，MP3 的目的是比 PCM 数据更紧凑。）对于这种编码，采样率和采样大小指的是编码后的声音最终将被转换成的 PCM 数据，然后传递给数字模拟转换器（DAC）。

文件格式

文件格式指定了声音文件的结构，包括文件中原始音频数据的格式，以及可以存储在文件中的其他信息。声音文件有各种标准品种，如 WAVE（也称为 WAV，通常与 PC 关联）、AIFF（通常与 Macintosh 关联）和 AU（通常与 UNIX 系统关联）。不同类型的声音文件具有不同的结构。例如，它们可能在文件的“头部”中具有不同的数据排列。头部包含描述性信息，通常在文件的实际音频样本之前，尽管一些文件格式允许连续的描述性和音频数据“块”。头部包括规范用于存储声音文件中音频的数据格式。任何这些类型的声音文件都可以包含各种数据格式（尽管通常在给定文件中只有一个数据格式），并且相同的数据格式可以在具有不同文件格式的文件中使用。

在 Java Sound API 中，文件格式由一个AudioFileFormat对象表示，其中包含：

• 文件类型（WAVE、AIFF 等）

• 文件的字节长度

• 文件中包含的音频数据的帧数长度

• 一个指定文件中包含的音频数据的数据格式的 AudioFormat 对象

AudioSystem类提供了用于读取和写入不同文件格式的声音以及在不同数据格式之间转换的方法。其中一些方法允许您通过一种称为AudioInputStream的流来访问文件的内容。AudioInputStream是InputStream类的子类，封装了可以按顺序读取的一系列字节。AudioInputStream类添加了有关字节音频数据格式的知识（由AudioFormat对象表示）到其超类。通过将声音文件作为AudioInputStream读取，您可以立即访问样本，而无需担心声音文件的结构（其头部、块等）。单个方法调用将为您提供有关数据格式和文件类型的所有信息。

什么是混音器？

许多声音应用程序编程接口（API）使用音频设备的概念。设备通常是对物理输入/输出设备的软件接口。例如，声音输入设备可能代表声卡的输入功能，包括麦克风输入、线路级模拟输入，以及可能的数字音频输入。

在 Java Sound API 中，设备由Mixer对象表示。混音器的目的是处理一个或多个音频输入流和一个或多个音频输出流。在典型情况下，它实际上将多个传入流混合成一个传出流。一个Mixer对象可以表示物理设备（如声卡）的声音混合功能，该设备可能需要混合从各种输入到计算机的声音，或者从应用程序到输出的声音。

或者，一个Mixer对象可以表示完全在软件中实现的声音混合功能，而没有与物理设备的固有接口。

在 Java Sound API 中，诸如声卡上的麦克风输入之类的组件本身并不被视为设备——也就是混音器——而是混音器内或外的端口。一个端口通常提供一个音频流进入或离开混音器（尽管该流可以是多声道的，比如立体声）。混音器可能有几个这样的端口。例如，代表声卡输出功能的混音器可能将几个音频流混合在一起，然后将混合信号发送到连接到混音器的任何或所有各种输出端口。这些输出端口可以是（例如）耳机插孔、内置扬声器或线路级输出。

要理解 Java Sound API 中混音器的概念，有助于想象一个物理混音控制台，比如在现场音乐会和录音室中使用的那种。

物理混音控制台

物理混音器有“条带”（也称为“切片”），每个条带代表一个音频信号通过混音器进行处理的路径。该条带有旋钮和其他控件，通过这些控件可以控制该条带中信号的音量和声像（在立体声图像中的位置）。此外，混音器可能有一个用于混响等效果的单独总线，该总线可以连接到内部或外部混响单元。每个条带都有一个电位器，用于控制该条带信号的多少进入混响混合中。混响（“湿”）混合然后与来自条带的“干”信号混合。物理混音器将这个最终混合发送到一个输出总线，通常连接到磁带录音机（或基于磁盘的录音系统）和/或扬声器。

想象一场正在立体录制的现场音乐会。来自舞台上许多麦克风和电子乐器的电缆（或无线连接）插入混音台的输入。每个输入都进入混音器的一个单独条道，如图所示。音响工程师决定增益、声像和混响控件的设置。所有条道和混响单元的输出混合成两个声道。这两个声道进入混音器的两个输出，插入连接到立体磁带录音机输入的电缆中。这两个声道可能也通过放大器发送到大厅的扬声器，这取决于音乐类型和大厅的大小。

现在想象一个录音室，在录音室中，每个乐器或歌手都被录制到多轨磁带录音机的单独轨道上。在所有乐器和歌手都被录制后，录音工程师执行“混音”操作，将所有录制的轨道组合成可以分发到 CD 上的两声道（立体声）录音。在这种情况下，混音器条的每个输入不是麦克风，而是多轨录音的一个轨道。工程师可以再次使用条上的控件来决定每个轨道的音量、声像和混响量。混音器的输出再次进入立体录音机和立体扬声器，就像现场音乐会的例子一样。

这两个例子说明了混音器的两种不同用途：捕获多个输入通道，将它们组合成较少的轨道并保存混合物，或者播放多个轨道同时将它们混合成较少的轨道。

在 Java Sound API 中，混音器可以类似地用于输入（捕获音频）或输出（播放音频）。在输入的情况下，混音器获取音频进行混音的源是一个或多个输入端口。混音器将捕获和混合的音频流发送到其目标，这是一个带有缓冲区的对象，应用程序可以从中检索这些混合音频数据。在音频输出的情况下，情况则相反。混音器的音频源是一个或多个包含缓冲区的对象，其中一个或多个应用程序将其声音数据写入其中；混音器的目标是一个或多个输出端口。

什么是一条线？

一个物理混音台的隐喻也有助于理解 Java Sound API 对线路概念的理解。

一条线是数字音频“管道”的一个元素，即将音频移入或移出系统的路径。通常，该线路是进入或离开混音器的路径（尽管从技术上讲，混音器本身也是一种线路）。

音频输入和输出端口是线路。这些类似于连接到物理混音台的麦克风和扬声器。另一种线路是应用程序可以通过其中获取输入音频或将输出音频发送到混音器的数据路径。这些数据路径类似于连接到物理混音台的多轨录音机的轨道。

Java Sound API 中的线路与物理混音器的一个区别是，通过 Java Sound API 中的线路流动的音频数据可以是单声道或多声道（例如，立体声）。相比之下，物理混音器的每个输入和输出通常是单声道的声音。要从物理混音器获得两个或更多声道的输出，通常会使用两个或更多个物理输出（至少在模拟声音的情况下；数字输出插孔通常是多声道的）。在 Java Sound API 中，线路中的声道数由当前流经线路的数据的AudioFormat指定。

现在让我们来看一些特定类型的线路和混音器。以下图表显示了 Java Sound API 实现的简单音频输出系统中不同类型的线路：

音频输出的可能配置线路

在这个例子中，一个应用程序已经获得了音频输入混音器的一些可用输入：一个或多个片段和源数据线路。片段是一个混音器输入（一种线路），你可以在播放之前将音频数据加载到其中；源数据线路是一个接受实时音频数据流的混音器输入。应用程序将音频数据从声音文件预加载到片段中。然后，它将其他音频数据一次一个缓冲区地推送到源数据线路中。混音器从所有这些线路中读取数据，每个线路可能有自己的混响、增益和声像控制，并将干净的音频信号与湿润（混响）混合。混音器将最终输出传送到一个或多个输出端口，例如扬声器、耳机插孔和线路输出插孔。

尽管在图中各个线路被描绘为单独的矩形，但它们都是混音器的“所有权”，可以被视为混音器的组成部分。混响、增益和声像矩形代表混音器可以应用于流经线路的数据的处理控制（而不是线路）。

请注意，这只是 API 支持的可能混音器的一个示例。并非所有音频配置都具有所示的所有功能。个别源数据线路可能不支持声像控制，混音器可能不实现混响等。

一个简单的音频输入系统可能类似：

音频输入线路的可能配置

在这里，数据从一个或多个输入端口流入混音器，通常是麦克风或线路输入插孔。增益和声像被应用，混音器通过混音器的目标数据线将捕获的数据传递给应用程序。目标数据线是混音器的输出，包含流式输入声音的混合物。最简单的混音器只有一个目标数据线，但有些混音器可以同时将捕获的数据传递给多个目标数据线。

线接口层次结构

现在我们已经看到了一些关于线路和混音器的功能图片，让我们从稍微更具编程视角的角度来讨论它们。通过基本Line接口的子接口定义了几种类型的线路。接口层次结构如下所示。

线接口层次结构

基本接口Line描述了所有线路共有的最小功能：

• 控件 - 数据线和端口通常具有一组控件，影响通过线路传递的音频信号。Java Sound API 指定了可以用于操纵声音方面的控件类，例如：增益（影响信号的分贝音量）、声像（影响声音的左右定位）、混响（为声音添加混响以模拟不同种类的房间声学）和采样率（影响播放速率以及声音的音调）。

• 打开或关闭状态 - 成功打开线路保证已为线路分配了资源。混音器具有有限数量的线路，因此在某些时候，多个应用程序（或同一个应用程序）可能会竞争使用混音器的线路。关闭线路表示线路使用的任何资源现在可以被释放。

• 事件 - 当线路打开或关闭时，线路会生成事件。Line的子接口可以引入其他类型的事件。当线路生成事件时，事件会发送给所有已注册在该线路上“监听”事件的对象。应用程序可以创建这些对象，将它们注册为监听线路事件，并根据需要对事件做出反应。

现在我们将检查Line接口的子接口。

端口是用于音频输入或输出到音频设备的简单线路。如前所述，一些常见类型的端口是麦克风、线路输入、CD-ROM 驱动器、扬声器、耳机和线路输出。

Mixer接口代表一个混音器，当然，正如我们所见，它代表一个硬件或软件设备。Mixer接口提供了获取混音器线的方法。这些包括源线，将音频馈送到混音器，以及目标线，混音器将其混合音频传递给的线。对于音频输入混音器，源线是输入端口，如麦克风输入，目标线是TargetDataLines（下文描述），它会将音频传递给应用程序。另一方面，对于音频输出混音器，源线是Clips或SourceDataLines（下文描述），应用程序向其馈送音频数据，目标线是输出端口，如扬声器。

一个Mixer被定义为具有一个或多个源线和一个或多个目标线。请注意，这个定义意味着一个混音器不一定实际混合数据；它可能只有一个单一的源线。Mixer API 旨在涵盖各种设备，但典型情况下支持混音。

Mixer接口支持同步；也就是说，您可以指定一个混音器的两个或多个线被视为同步组。然后，您可以通过向组中的任何线发送单个消息来启动、停止或关闭所有这些数据线，而不必单独控制每条线。使用支持此功能的混音器，您可以在线之间获得样本精确的同步。

通用的Line接口不提供启动和停止播放或录制的方法。为此，您需要一个数据线。DataLine接口提供了以下额外的与媒体相关的功能，超出了Line的功能：

• 音频格式 – 每个数据线都有与其数据流相关联的音频格式。

• 媒体位置 – 数据线可以报告其在媒体中的当前位置，以采样帧表示。这代表自数据线打开以来捕获或渲染的采样帧数量。

• 缓冲区大小 – 这是数据线内部缓冲区的大小，以字节为单位。对于源数据线，内部缓冲区是可以写入数据的，对于目标数据线，它是可以读取数据的。

• 音量（音频信号的当前振幅）

• 启动和停止播放或捕获

• 暂停和恢复播放或捕获

• 刷新（丢弃队列中的未处理数据）

• 排空（阻塞直到队列中的所有未处理数据都被排空，并且数据线的缓冲区变为空）

• 活动状态 – 如果数据线参与从混音器捕获音频数据或向混音器捕获音频数据，则被视为活动状态。

• 事件 – START 和 STOP 事件在从数据线开始或停止活动演示或捕获数据时产生。

TargetDataLine 从混音器接收音频数据。通常，混音器从诸如麦克风之类的端口捕获音频数据；在将数据放入目标数据线缓冲区之前，它可能会处理或混合此捕获的音频。TargetDataLine 接口提供了从目标数据线缓冲区读取数据的方法，并确定当前可用于读取的数据量。

SourceDataLine 接收用于播放的音频数据。它提供了将数据写入源数据线缓冲区以进行播放的方法，并确定数据线准备接收多少数据而不会阻塞。

Clip 是一个数据线，可以在播放之前加载音频数据。由于数据是预加载而不是流式传输，因此在播放之前可以知道剪辑的持续时间，并且可以选择媒体中的任何起始位置。剪辑可以循环播放，意味着在播放时，两个指定循环点之间的所有数据将重复指定次数，或者无限循环。

本节介绍了采样音频 API 中大部分重要的接口和类。后续章节将展示如何在应用程序中访问和使用这些对象。

访问音频系统资源

原文：docs.oracle.com/javase/tutorial/sound/accessing.html

Java Sound API 对系统配置采取了灵活的方法。计算机上可以安装不同类型的音频设备（混音器）。该 API 对已安装的设备及其功能能力几乎不做任何假设。相反，它提供了系统报告可用音频组件的方法，以及您的程序访问它们的方法。

以下部分展示了您的程序如何了解计算机上已安装的采样音频资源以及如何访问可用资源。资源包括混音器和混音器拥有的各种类型的线路等。

AudioSystem 类

AudioSystem 类充当音频组件的集散地，包括来自第三方提供商的内置服务和单独安装的服务。 AudioSystem 作为应用程序访问这些已安装的采样音频资源的入口点。您可以查询 AudioSystem 以了解已安装了哪些资源，然后可以访问这些资源。例如，应用程序可能首先询问 AudioSystem 类是否有具有特定配置的混音器，例如在前面讨论线路时所示的输入或输出配置之一。然后，程序将从混音器获取数据线路，依此类推。

以下是应用程序可以从 AudioSystem 获取的一些资源：

• 混音器 — 系统通常安装了多个混音器。通常至少有一个用于音频输入和一个用于音频输出。还可能有一些混音器没有 I/O 端口，而是接受应用程序的音频并将混合后的音频传递回程序。 AudioSystem 类提供了所有已安装混音器的列表。

• 线路 — 即使每条线路都与混音器相关联，应用程序也可以直接从 AudioSystem 获取线路，而无需明确处理混音器。

• 格式转换 — 应用程序可以使用格式转换将音频数据从一种格式转换为另一种格式。

• 文件和流 — AudioSystem 类提供了在音频文件和音频流之间进行转换的方法。它还可以报告声音文件的文件格式，并且可以以不同格式写入文件。

信息对象

Java Sound API 中的几个类提供有关相关接口的有用信息。例如，Mixer.Info提供有关已安装混音器的详细信息，如混音器的供应商、名称、描述和版本。Line.Info获取特定线路的类。Line.Info的子类包括Port.Info和DataLine.Info，分别获取与特定端口和数据线相关的详细信息。这些类中的每一个在下面的适当部分中进一步描述。重要的是不要混淆Info对象与其描述的混音器或线路对象。

获取混音器

通常，使用 Java Sound API 的程序需要做的第一件事情之一是获取一个混音器，或者至少获取一个混音器的一条线路，以便将声音输入或输出计算机。您的程序可能需要特定类型的混音器，或者您可能希望显示所有可用混音器的列表，以便用户可以选择一个。在任何情况下，您需要了解安装了哪些类型的混音器。AudioSystem提供以下方法：

static Mixer.Info[] getMixerInfo()

由此方法返回的每个Mixer.Info对象标识安装的一种混音器类型。（通常系统最多只有一个给定类型的混音器。如果恰好有多个给定类型的混音器，则返回的数组仍然只有一个该类型的Mixer.Info。）应用程序可以遍历Mixer.Info对象，根据自身需求找到合适的混音器。Mixer.Info包括以下字符串来标识混音器的类型：

• 名称

• 版本

• 供应商

• 描述

这些都是任意字符串，因此需要特定混音器的应用程序必须知道可以期望什么以及将字符串与什么进行比较。提供混音器的公司应在其文档中包含此信息。或者，也许更典型的是，应用程序将向用户显示所有Mixer.Info对象的字符串，让用户选择相应的混音器。

一旦找到合适的混音器，应用程序调用以下AudioSystem方法来获取所需的混音器：

static Mixer getMixer(Mixer.Info info)

如果您的程序需要具有某些功能的混音器，但不需要特定供应商制造的特定混音器怎么办？如果您不能依赖用户知道应选择哪个混音器怎么办？在这种情况下，Mixer.Info对象中的信息将没有太大用处。相反，您可以通过调用getMixer为每个Mixer.Info对象返回的所有Mixer.Info对象迭代，获取每个混音器，并查询每个混音器的功能。例如，您可能需要一个可以将其混合音频数据同时写入一定数量的目标数据线的混音器。在这种情况下，您将使用此Mixer方法查询每个混音器：

int getMaxLines(Line.Info info)

在这里，Line.Info将指定一个TargetDataLine。Line.Info类将在下一节中讨论。

获取所需类型的线

有两种方法可以获取一条线：

• 直接从AudioSystem对象

• 从您已从AudioSystem对象获取的混音器获取

直接从AudioSystem获取一条线

假设您尚未获得混音器，并且您的程序是一个真正只需要某种类型的线的简单程序；混音器的细节对您并不重要。您可以使用AudioSystem方法：

static Line getLine(Line.Info info)

这类似于先前讨论的getMixer方法。与Mixer.Info不同，作为参数使用的Line.Info不存储文本信息以指定所需的线。相反，它存储有关所需线类的信息。

Line.Info是一个抽象类，因此您可以使用其子类(Port.Info或DataLine.Info)来获取一条线。以下代码摘录使用DataLine.Info子类来获取和打开目标数据线：

TargetDataLine line;
DataLine.Info info = new DataLine.Info(TargetDataLine.class, 
    format); // format is an AudioFormat object
if (!AudioSystem.isLineSupported(info)) {
    // Handle the error.
    }
    // Obtain and open the line.
try {
    line = (TargetDataLine) AudioSystem.getLine(info);
    line.open(format);
} catch (LineUnavailableException ex) {
        // Handle the error.
    //... 
}

此代码获取一个TargetDataLine对象，除了其类和音频格式之外，没有指定任何属性。您可以使用类似的代码来获取其他类型的线。对于SourceDataLine或Clip，只需将该类替换为TargetDataLine作为线变量的类，并且在DataLine.Info构造函数的第一个参数中也进行替换。

对于Port，您可以在以下代码中使用Port.Info的静态实例：

if (AudioSystem.isLineSupported(Port.Info.MICROPHONE)) {
    try {
        line = (Port) AudioSystem.getLine(
            Port.Info.MICROPHONE);
    }
}

请注意使用isLineSupported方法来查看混音器是否具有所需类型的线。

请记住，源线是混音器的输入，即，如果混音器代表音频输入设备，则是一个Port对象，如果混音器代表音频输出设备，则是一个SourceDataLine或Clip对象。同样，目标线是混音器的输出：对于音频输出混音器，是一个Port对象，对于音频输入混音器，是一个TargetDataLine对象。如果一个混音器根本没有连接到任何外部硬件设备怎么办？例如，考虑一个仅从应用程序获取音频并将混合音频传递回程序的内部或仅软件混音器。这种混音器的输入线有SourceDataLine或Clip对象，输出线有TargetDataLine对象。

您还可以使用以下AudioSystem方法了解任何已安装混音器支持的指定类型的源和目标线路：

static Line.Info[] getSourceLineInfo(Line.Info info)
static Line.Info[] getTargetLineInfo(Line.Info info)

请注意，每个方法返回的数组表示唯一类型的线路，不一定是所有线路。例如，如果一个混音器的两条线路，或者两个不同混音器的两条线路，具有相同的Line.Info对象，则返回的数组中只会表示一个Line.Info。

从混音器获取线路

Mixer接口包括上述AudioSystem访问方法的变体，用于源和目标线路。这些Mixer方法包括接受Line.Info参数的方法，就像AudioSystem的方法一样。但是，Mixer还包括这些不带参数的变体：

Line.Info[] getSourceLineInfo()
Line.Info[] getTargetLineInfo()

这些方法返回特定混音器的所有Line.Info对象的数组。一旦获得数组，您可以遍历它们，调用Mixer的getLine方法获取每条线路，然后调用Line的open方法为您的程序保留每条线路的使用权。

选择输入和输出端口

关于如何获取所需类型的线路的上一节也适用于端口以及其他类型的线路。您可以通过将Port.Info对象传递给接受Line.Info参数的AudioSystem（或Mixer）方法getSourceLineInfo和getTargetLineInfo来获取所有源（即输入）和目标（即输出）端口。然后，您遍历返回的对象数组并调用 Mixer 的getLine方法以获取每个端口。

然后，通过调用Line的open方法打开每个Port。打开端口意味着您打开它 - 也就是说，您允许声音进出端口。同样，您可以关闭您不希望声音通过的端口，因为有些端口可能在您获取它们之前已经打开。一些平台默认打开所有端口；或者用户或系统管理员可能已经选择使用另一个应用程序或操作系统软件打开或关闭某些端口。

警告： 如果您想选择特定端口并确保声音实际上进出该端口，可以按照描述打开端口。但是，这可能被视为对用户不友好的行为！例如，用户可能已关闭扬声器端口以免打扰同事。如果您的程序突然推翻了她的意愿并开始播放音乐，她会感到非常沮丧。另一个例子，用户可能希望确保计算机的麦克风在没有他知情的情况下永远不会打开，以避免窃听。一般来说，建议不要打开或关闭端口，除非您的程序响应用户通过用户界面表达的意图。相反，尊重用户或操作系统已选择的设置。

在连接到混音器之前，不需要打开或关闭端口才能使其正常工作。例如，即使所有输出端口关闭，您也可以开始将声音播放到音频输出混音器中。数据仍然流入混音器；播放不会被阻止。用户只是听不到任何声音。一旦用户打开输出端口，声音将通过该端口听到，从媒体播放已经到达的任何点开始。

此外，您不需要访问端口来了解混音器是否具有某些端口。例如，要了解混音器是否实际上是音频输出混音器，可以调用getTargetLineInfo来查看它是否具有输出端口。除非您想更改其设置（例如打开或关闭状态或它们可能具有的任何控件的设置），否则没有理由访问端口本身。

使用音频资源的权限

Java Sound API 包括一个AudioPermission类，指示 applet（或在安全管理器下运行的应用程序）对采样音频系统可以具有哪些访问权限。录制声音的权限是单独控制的。应谨慎授予此权限，以帮助防止未经授权的窃听等安全风险。默认情况下，applet 和应用程序被授予以下权限：

• 使用 applet 安全管理器运行的applet可以播放音频，但不能录制。

• 没有安全管理器运行的应用程序可以播放和录制音频。

• 使用默认安全管理器运行的应用程序可以播放音频，但不能录制。

一般来说，applet 在安全管理器的监督下运行，不允许录制声音。另一方面，应用程序不会自动安装安全管理器，并且可以录制声音。（但是，如果为应用程序显式调用默认安全管理器，则不允许应用程序录制声音。）

即使在安全管理器下运行，只要已被明确授予权限，applet 和应用程序都可以录制声音。

如果您的程序没有录制（或播放）声音的权限，在尝试打开线路时会抛出异常。在程序中，除了捕获异常并向用户报告问题外，您无法做任何事情，因为权限无法通过 API 更改。（如果可以的话，它们将毫无意义，因为没有任何东西是安全的！）通常，权限是在一个或多个策略配置文件中设置的，用户或系统管理员可以使用文本编辑器或策略工具程序进行编辑。

播放音频

原文：docs.oracle.com/javase/tutorial/sound/playing.html

播放有时被称为演示或渲染。这些是适用于声音以外的其他媒体的通用术语。其关键特征是一系列数据被传送到某个地方，最终由用户感知。如果数据是基于时间的，如声音，它必须以正确的速率传送。与视频相比，对于声音来说，数据流速率的维持更为重要，因为声音播放中断通常会产生响亮的点击声或刺耳的失真。Java Sound API 旨在帮助应用程序平稳连续地播放声音，即使是非常长的声音。

之前您已经看到如何从音频系统或混音器中获取线路。在这里，您将学习如何通过线路播放声音。

如您所知，有两种可以用于播放声音的线路：Clip和SourceDataLine。两者之间的主要区别在于，使用Clip时，您在播放之前一次性指定所有声音数据，而使用SourceDataLine时，在播放过程中持续写入新的数据缓冲区。虽然有许多情况可以使用Clip或SourceDataLine，但以下标准有助于确定哪种线路更适合特定情况：

• 当您有非实时声音数据可以预加载到内存中时，请使用Clip。

  例如，您可以将短声音文件读入剪辑中。如果您希望声音重复播放多次，则Clip比SourceDataLine更方便，特别是如果您希望播放循环（重复通过声音的全部或部分）。如果您需要在声音中的任意位置开始播放，Clip接口提供了一种轻松实现的方法。最后，与从SourceDataLine缓冲播放相比，从Clip播放通常具有更少的延迟。换句话说，因为声音已经预加载到剪辑中，播放可以立即开始，而不必等待缓冲区填充。

• 使用SourceDataLine来流式传输数据，比如无法一次性全部放入内存的长声音文件，或者在播放之前无法预先知道数据的声音。

  作为后一种情况的示例，假设您正在监视声音输入，即在捕获声音时播放声音。如果您没有一个可以将输入音频发送回输出端口的混音器，您的应用程序将不得不获取捕获的数据并将其发送到音频输出混音器。在这种情况下，使用SourceDataLine比使用Clip更合适。另一个无法事先知道的声音示例是当您根据用户的输入合成或操作声音数据时。例如，想象一个游戏通过在用户移动鼠标时从一个声音“变形”到另一个声音来提供听觉反馈。声音转换的动态性要求应用程序在播放过程中持续更新声音数据，而不是在播放开始之前提供所有数据。

使用 Clip

如前所述，在获取所需类型的行下获取一个Clip；用Clip.class作为第一个参数构造一个DataLine.Info对象，并将此DataLine.Info作为参数传递给AudioSystem或Mixer的getLine方法。

获取一条线只是意味着您已经找到了一个引用它的方法；getLine实际上并没有为您保留该线路。因为混音器可能只有有限数量的所需类型的线路可用，所以在您调用getLine获取剪辑后，可能会发生另一个应用程序在您准备开始播放之前抢走剪辑的情况。要实际使用剪辑，您需要通过调用以下Clip方法之一来为您的程序独占地保留它：

void open(AudioInputStream stream)
void open(AudioFormat format, byte[] data, int offset, int bufferSize)

尽管上述第二个open方法中有bufferSize参数，但Clip（不像SourceDataLine）不包括用于向缓冲区写入新数据的方法。这里的bufferSize参数只指定要加载到剪辑中的字节数组的大小。它不是一个可以随后加载更多数据的缓冲区，就像您可以使用SourceDataLine的缓冲区一样。

打开剪辑后，您可以使用Clip的setFramePosition或setMicroSecondPosition方法指定数据中应开始播放的位置。否则，它将从开头开始。您还可以使用setLoopPoints方法配置循环播放。

当您准备开始播放时，只需调用start方法。要停止或暂停剪辑，请调用stop方法，要恢复播放，请再次调用start。剪辑会记住停止播放的媒体位置，因此不需要显式的暂停和恢复方法。如果您不希望它在停止播放的位置继续播放，可以使用上述提到的帧或微秒定位方法将剪辑“倒带”到开头（或任何其他位置）。

可以通过调用DataLine方法getLevel和isActive来监视Clip的音量级别和活动状态（活动与非活动）。活动的Clip是当前正在播放声音的Clip。

使用 SourceDataLine

获取SourceDataLine类似于获取Clip。打开SourceDataLine也类似于打开Clip，因为目的再次是为了保留该线路。但是，您使用从DataLine继承的不同方法：

void open(AudioFormat format)

请注意，当您打开SourceDataLine时，尚未将任何声音数据与该线路关联，与打开Clip不同。相反，您只需指定要播放的音频数据的格式。系统会选择默认的缓冲区长度。

您还可以使用以下变体指定特定的字节缓冲区长度：

void open(AudioFormat format, int bufferSize)

为了与类似方法保持一致，bufferSize参数以字节表示，但必须对应于整数帧数。

除了使用上述描述的 open 方法，还可以使用Line的open()方法打开SourceDataLine，而无需参数。在这种情况下，该线路将以其默认音频格式和缓冲区大小打开。但是，您以后无法更改这些。如果您想知道线路的默认音频格式和缓冲区大小，甚至在线路尚未打开之前，可以调用DataLine的getFormat和getBufferSize方法。

一旦SourceDataLine打开，您就可以开始播放声音。您可以通过调用DataLine的 start 方法来实现这一点，然后将数据重复写入线路的播放缓冲区。

start 方法允许线路在其缓冲区中有任何数据时开始播放声音。您可以通过以下方法将数据放入缓冲区：

int write(byte[] b, int offset, int length)

数组中的偏移量以字节表示，数组的长度也是以字节表示。

该线路尽快将数据发送到其混音器。当混音器将数据传递给其目标时，SourceDataLine会生成START事件。 （在 Java Sound API 的典型实现中，源线将数据传递给混音器的时间延迟与混音器将数据传递给其目标的时间延迟可以忽略不计，即远小于一个样本的时间。）此START事件将发送给线路的侦听器，如下所述监视线路状态。现在该线路被视为活动的，因此DataLine的isActive方法将返回true。请注意，所有这些仅在缓冲区包含要播放的数据时才会发生，不一定在调用 start 方法时立即发生。如果您在新的SourceDataLine上调用了start但从未向缓冲区写入数据，则该线路永远不会处于活动状态，并且START事件永远不会发送。（但是，在这种情况下，DataLine的isRunning方法将返回true。）

那么你如何知道要向缓冲区写入多少数据，以及何时发送第二批数据呢？幸运的是，你不需要计时第二次调用 write 以与第一个缓冲区的结束同步！相反，你可以利用write方法的阻塞行为：

• 该方法在数据被写入缓冲区后立即返回。它不会等到缓冲区中的所有数据都播放完毕。（如果等待的话，你可能没有时间写入下一个缓冲区，从而导致音频中断。）

• 尝试写入的数据量超过缓冲区容量是可以的。在这种情况下，该方法会阻塞（不返回），直到你请求的所有数据实际上都被放入缓冲区中。换句话说，每次只会写入一个缓冲区的数据并进行播放，直到剩余数据全部适应缓冲区为止，此时该方法才会返回。无论该方法是否阻塞，它都会在此次调用中最后一个缓冲区的数据被写入时立即返回。这意味着你的代码很可能在最后一个缓冲区的数据播放完成之前就重新获得了控制权。

• 在许多情况下，写入的数据量超过缓冲区容量是可以的，但如果你想确保下一个写入不会阻塞，你可以将写入的字节数限制为DataLine的available方法返回的数量。

下面是一个示例，迭代从流中读取的数据块，一次将一个数据块写入SourceDataLine进行播放：

// read chunks from a stream and write them to a source data 
line 
line.start();
while (total < totalToRead && !stopped)}
    numBytesRead = stream.read(myData, 0, numBytesToRead);
    if (numBytesRead == -1) break;
    total += numBytesRead; 
    line.write(myData, 0, numBytesRead);

}

如果你不希望write方法阻塞，你可以首先在循环内调用available方法来查找可以无阻塞写入的字节数，然后在从流中读取之前将numBytesToRead变量限制为这个数字。然而，在给定的示例中，阻塞并不重要，因为 write 方法是在一个循环内调用的，直到最后一个缓冲区在最后一个循环迭代中被写入。无论你是否使用阻塞技术，你可能会希望在应用程序的其余部分之外的一个单独线程中调用这个播放循环，这样当播放长声音时，你的程序不会出现冻结的情况。在循环的每次迭代中，你可以测试用户是否请求停止播放。这样的请求需要将上面代码中使用的stopped布尔值设置为true。

由于write在所有数据完成播放之前返回，那么你如何知道播放实际上已经完成了呢？一种方法是在写入最后一个缓冲区数据后调用DataLine的drain方法。该方法会阻塞，直到所有数据都已经播放完毕。当控制返回到你的程序时，如果需要的话，你可以释放该线路，而不必担心会过早中断任何音频样本的播放：

line.write(b, offset, numBytesToWrite); 
//this is the final invocation of write
line.drain();
line.stop();
line.close();
line = null;

你可以有意提前停止播放，当然。例如，应用程序可能会为用户提供一个停止按钮。调用DataLine的stop方法可以立即停止播放，即使在缓冲区的中间。这会使缓冲区中的任何未播放数据保留下来，因此如果随后调用start，播放将从停止的地方恢复。如果这不是你想要发生的事情，你可以通过调用flush来丢弃缓冲区中剩余的数据。

当数据流的流动已停止时，SourceDataLine会生成一个STOP事件，无论此停止是由drain方法、stop方法、flush方法引起的，还是因为在应用程序调用write提供新数据之前已到达播放缓冲区的末尾。STOP事件并不一定意味着已调用stop方法，并且也不一定意味着随后调用isRunning将返回false。但是，它确实意味着isActive将返回false。（当调用start方法时，即使生成STOP事件，isRunning方法也将返回true，并且只有在调用stop方法后才会开始返回false。）重要的是要意识到START和STOP事件对应于isActive，而不是isRunning。

监控线路的状态

一旦开始播放声音，如何确定何时完成？我们在上面看到了一种解决方案，在写入最后一个数据缓冲区后调用drain方法，但这种方法仅适用于SourceDataLine。另一种途径，适用于SourceDataLines和Clips，是注册以接收线路在改变其状态时发出的通知。这些通知以LineEvent对象的形式生成，其中有四种类型：OPEN、CLOSE、START和STOP。

在程序中实现LineListener接口的任何对象都可以注册以接收此类通知。要实现LineListener接口，对象只需要一个接受LineEvent参数的update方法。要将此对象注册为线路的侦听器之一，您需要调用以下Line方法：

public void addLineListener(LineListener listener)

每当线路打开、关闭、启动或停止时，它会向所有侦听器发送一个update消息。您的对象可以查询接收到的LineEvent。首先，您可能会调用LineEvent.getLine来确保停止的线路是您关心的线路。在我们讨论的情况下，您想知道声音是否已完成，因此您可以查看LineEvent是否为STOP类型。如果是，您可以检查声音的当前位置，该位置也存储在LineEvent对象中，并将其与声音的长度（如果已知）进行比较，以查看是否已达到结束并且没有被其他方式停止（例如用户点击停止按钮，尽管您可能能够在代码的其他地方确定该原因）。

同样，如果您需要知道何时打开、关闭或启动线路，可以使用相同的机制。LineEvents由不同类型的线路生成，不仅仅是Clips和SourceDataLines。但是，在Port的情况下，您不能指望获得事件来了解线路的打开或关闭状态。例如，当创建Port时，可能会最初打开Port，因此您不会调用open方法，而Port也不会生成OPEN事件。 (请参阅之前关于选择输入和输出端口的讨论。)

同步多条线路的播放

如果您同时播放多个音轨，您可能希望它们都在完全相同的时间开始和停止。一些混音器通过其synchronize方法促进此行为，该方法允许您对一组数据线应用操作，如open、close、start和stop，而不是必须单独控制每条线路。此外，可以控制对线路应用操作的精度程度。

要了解特定数据线组的特定混音器是否提供此功能，调用Mixer接口的isSynchronizationSupported方法：

boolean isSynchronizationSupported(Line[] lines, boolean  maintainSync)

第一个参数指定了一组特定的数据线，第二个参数表示必须保持同步的精度。如果第二个参数是true，则查询是在询问混音器是否能够始终在所有时间内保持对指定线路的样本精确控制；否则，精确同步仅在启动和停止操作期间需要，而不是在整个播放过程中。

处理传出音频

一些源数据线具有信号处理控件，如增益、声像、混响和采样率控件。类似的控件，尤其是增益控件，也可能存在于输出端口上。有关如何确定一条线路是否具有此类控件以及如何在有此类控件的情况下使用它们的更多信息，请参阅使用控件处理音频。

音频捕获

原文：docs.oracle.com/javase/tutorial/sound/capturing.html

捕获指的是从计算机外部获取信号的过程。音频捕获的常见应用是录音，比如将麦克风输入录制到声音文件中。然而，捕获并不等同于录制，因为录制意味着应用程序始终保存正在输入的声音数据。捕获音频的应用程序不一定存储音频。相反，它可能在音频到达时对数据进行处理，比如将语音转录为文本，但在完成对每个缓冲区的处理后立即丢弃每个缓冲区的音频。

如示例包概述中所讨论的，在 Java Sound API 的实现中，典型的音频输入系统包括：

1. 一个输入端口，比如麦克风端口或线路输入端口，将其传入的音频数据输入到：

2. 一个混音器，将输入数据放入其中：

3. 一个或多个目标数据线，应用程序可以从中检索数据。

通常情况下，一次只能打开一个输入端口，但也可以有一个混音器，从多个端口混合音频。另一种情况是一个没有端口的混音器，而是通过网络获取音频输入。

TargetDataLine接口在线接口层次结构下简要介绍过。TargetDataLine与SourceDataLine接口直接类似，后者在播放音频中有详细讨论。回想一下，SourceDataLine接口包括：

• 一个write方法将音频发送到混音器

• 一个available方法，用于确定可以向缓冲区写入多少数据而不会阻塞

同样，TargetDataLine包括：

• 一个read方法从混音器获取音频

• 一个available方法，用于确定可以从缓冲区读取多少数据而不会阻塞

设置 TargetDataLine

获取目标数据线的过程在访问音频系统资源中已经描述，但为了方便起见，我们在这里重复一遍：

TargetDataLine line;
DataLine.Info info = new DataLine.Info(TargetDataLine.class, 
    format); // format is an AudioFormat object
if (!AudioSystem.isLineSupported(info)) {
    // Handle the error ... 

}
// Obtain and open the line.
try {
    line = (TargetDataLine) AudioSystem.getLine(info);
    line.open(format);
} catch (LineUnavailableException ex) {
    // Handle the error ... 
}

你可以调用Mixer的getLine方法，而不是AudioSystem的。

正如本例所示，一旦获得目标数据线，您可以通过调用SourceDataLine方法open来为应用程序保留它的使用权，就像在播放音频中描述的那样。open方法的单参数版本使线的缓冲区具有默认大小。您可以通过调用两个参数版本根据应用程序的需要设置缓冲区大小：

void open(AudioFormat format, int bufferSize)

从 TargetDataLine 读取数据

一旦线路打开，它就准备开始捕获数据，但它还没有激活。要实际开始音频捕获，使用DataLine的start方法。这将开始将输入音频数据传递到线路的缓冲区，以供您的应用程序读取。只有当应用程序准备好从线路读取时，应用程序才应该调用 start；否则，将浪费大量处理时间来填充捕获缓冲区，只会导致溢出（即，丢弃数据）。

要开始从缓冲区检索数据，请调用TargetDataLine的read方法：

int read(byte[] b, int offset, int length)

这种方法尝试将length字节的数据读入数组b，从数组中的字节位置offset开始。该方法返回实际读取的字节数。

与SourceDataLine的write方法一样，您可以请求比缓冲区实际容量更多的数据，因为该方法会阻塞，直到请求的数据量已经传递，即使您请求了许多缓冲区的数据量。

为了避免在录制过程中使您的应用程序挂起，您可以在循环中调用 read 方法，直到检索到所有音频输入，就像这个例子中所示的那样：

// Assume that the TargetDataLine, line, has already
// been obtained and opened.
ByteArrayOutputStream out  = new ByteArrayOutputStream();
int numBytesRead;
byte[] data = new byte[line.getBufferSize() / 5];

// Begin audio capture.
line.start();

// Here, stopped is a global boolean set by another thread.
while (!stopped) {
   // Read the next chunk of data from the TargetDataLine.
   numBytesRead =  line.read(data, 0, data.length);
   // Save this chunk of data.
   out.write(data, 0, numBytesRead);
}     

请注意，在这个例子中，将数据读入的字节数组的大小设置为线路缓冲区大小的五分之一。如果您将其设置为与线路缓冲区一样大，并尝试读取整个缓冲区，您需要在时间上非常准确，因为如果混音器需要在您从中读取数据时向线路传递数据，数据将被丢弃。通过使用线路缓冲区大小的一部分，如此处所示，您的应用程序将更成功地与混音器共享对线路缓冲区的访问。

TargetDataLine的read方法接受三个参数：一个字节数组，一个数组中的偏移量，以及您想要读取的输入数据的字节数。在这个例子中，第三个参数就是你的字节数组的长度。read方法返回实际读取到数组中的字节数。

通常，您会像这个例子中一样在循环中从线路中读取数据。在while循环中，每个检索到的数据块都会根据应用程序的适当方式进行处理——在这里，它被写入ByteArrayOutputStream。这里没有显示的是使用单独的线程来设置布尔值stopped，该值在循环终止时终止。当用户点击停止按钮时，该布尔值的值可能被设置为true，并且当监听器从线路接收到CLOSE或STOP事件时也是如此。监听器对于CLOSE事件是必需的，对于STOP事件是推荐的。否则，如果线路在没有将stopped设置为true的情况下以某种方式停止，while循环将在每次迭代中捕获零字节，运行速度快，浪费 CPU 周期。一个更全面的代码示例将展示如果捕获再次激活，则重新进入循环。

与源数据线一样，可以排空或清空目标数据线。例如，如果您正在将输入录制到文件中，当用户点击停止按钮时，您可能希望调用drain方法。drain方法将导致混音器的剩余数据传递到目标数据线的缓冲区。如果您不排空数据，捕获的声音可能在末尾被截断。

也许有一些情况下，您希望清空数据。无论如何，如果您既不清空也不排空数据，数据将保留在混音器中。这意味着当重新开始捕获时，新录音的开头会有一些残留声音，这可能是不希望的。因此，在重新开始捕获之前清空目标数据线可能是有用的。

监控线路状态

因为TargetDataLine接口扩展了DataLine，目标数据线生成事件的方式与源数据线相同。您可以注册一个对象，以便在目标数据线打开、关闭、启动或停止时接收事件。有关更多信息，请参阅之前关于监控线路状态的讨论。

处理传入音频

像一些源数据线一样，一些混音器的目标数据线具有信号处理控件，例如增益、声像、混响或采样率控件。输入端口可能具有类似的控件，特别是增益控件。在下一节中，您将学习如何确定一条线是否具有这些控件，以及如何在有这些控件的情况下使用它们。

使用控件处理音频

原文：docs.oracle.com/javase/tutorial/sound/controls.html

先前的部分已经讨论了如何播放或捕获音频样本。隐含的目标是尽可能忠实地传递样本，而不进行修改（除了可能将样本与其他音频线路的样本混合）。然而，有时您可能希望能够修改信号。用户可能希望声音听起来更响亮、更安静、更丰满、更具混响、音高更高或更低等。本页讨论了提供这些类型信号处理的 Java Sound API 功能。

有两种应用信号处理的方式：

• 您可以通过查询Control对象并根据用户的需求设置控件来使用混音器或其组件线路支持的任何处理。混音器和线路通常支持的控件包括增益、声像和混响控件。

• 如果混音器或其线路提供的处理方式不符合您的需求，您的程序可以直接操作音频字节，根据需要进行操作。

本页更详细地讨论了第一种技术，因为第二种技术没有专门的 API。

控件介绍

混音器的某些或所有线路上可以有各种信号处理控件。例如，用于音频捕获的混音器可能具有带增益控制的输入端口，以及带增益和声像控制的目标数据线。用于音频播放的混音器可能在其源数据线上具有采样率控制。在每种情况下，所有控件都通过Line接口的方法访问。

因为Mixer接口扩展了Line，混音器本身可以具有自己的一组控件。这些控件可能作为主控件，影响所有混音器的源或目标线路。例如，混音器可能具有主增益控制，其分贝值会添加到其目标线路上各个增益控制的值中。

混音器的其他控件可能会影响一个特殊的线路，既不是源也不是目标，混音器在内部用于其处理。例如，全局混响控制可能选择应用于输入信号混合的混响类型，这个“湿”（混响）信号会在传递到混音器的目标线路之前混合回“干”信号中。

如果混音器或其任何线路具有控件，则您可能希望通过程序用户界面中的图形对象公开控件，以便用户可以根据需要调整音频特性。这些控件本身并不是图形化的；它们只是允许您检索和更改其设置。由您决定在程序中使用何种图形表示（滑块、按钮等）。

所有控件都作为抽象类Control的具体子类实现。许多典型的音频处理控件可以通过基于数据类型（如布尔值、枚举值或浮点数）的Control的抽象子类来描述。例如，布尔控件代表二进制状态控件，如静音或混响的开/关控件。另一方面，浮点控件非常适合表示连续可变控件，如声道、平衡或音量。

Java 音频 API 指定了以下Control的抽象子类：

• BooleanControl — 代表二进制状态（真或假）控件。例如，静音、独奏和开/关开关都是BooleanControls的良好候选。

• FloatControl — 提供对一系列浮点值的控制的数据模型。例如，音量和声道是可以通过旋钮或滑块操作的FloatControls。

• EnumControl — 提供从一组对象中进行选择的选项。例如，您可以将用户界面中的一组按钮与EnumControl关联起来，以选择几个预设混响设置中的一个。

• CompoundControl — 提供对一组相关项目的访问，其中每个项目本身都是Control子类的实例。CompoundControls代表多控件模块，如图形均衡器。（图形均衡器通常由一组滑块表示，每个滑块影响一个FloatControl。）

上述每个Control的子类都有适用于其基础数据类型的方法。大多数类包括设置和获取控件当前值的方法，获取控件标签等。

当然，每个类都有特定于它和类所代表的数据模型的方法。例如，EnumControl有一个方法让您获取其可能值的集合，而FloatControl允许您获取其最小和最大值，以及控件的精度（增量或步长）。

每个Control的子类都有一个对应的Control.Type子类，其中包括标识特定控件的静态实例。

以下表格显示了每个Control子类、其对应的Control.Type子类以及指示特定控件类型的静态实例：

| FloatControl | FloatControl.Type | AUX_RETURN – 线路上的辅助返回增益 AUX_SEND – 线路上的辅助发送增益

BALANCE – 左右音量平衡

MASTER_GAIN – 线路上的总增益

PAN – 左右位置

REVERB_RETURN – 线路上的后混响增益

REVERB_SEND – 线路上的前混响增益

SAMPLE_RATE – 播放采样率

VOLUME – 线路上的音量 |

Java Sound API 的实现可以在其混音器和线路上提供任何或所有这些控件类型。它还可以提供 Java Sound API 中未定义的其他控件类型。这些控件类型可以通过这四个抽象子类的具体子类或不继承这四个抽象子类的其他 Control 子类来实现。应用程序可以查询每条线路以查找它支持的控件。

获取具有所需控件的线路

在许多情况下，应用程序将简单地显示该线路支持的任何控件。如果线路没有任何控件，那就算了。但是如果重要的是找到具有特定控件的线路呢？在这种情况下，您可以使用 Line.Info 来获取具有正确特征的线路，如之前在 获取所需类型的线路 中描述的。

例如，假设您希望有一个输入端口，让用户设置声音输入的音量。以下代码摘录显示了如何查询默认混音器以确定它是否具有所需的端口和控件：

Port lineIn;
FloatControl volCtrl;
try {
  mixer = AudioSystem.getMixer(null);
  lineIn = (Port)mixer.getLine(Port.Info.LINE_IN);
  lineIn.open();
  volCtrl = (FloatControl) lineIn.getControl(

      FloatControl.Type.VOLUME);

  // Assuming getControl call succeeds, 
  // we now have our LINE_IN VOLUME control.
} catch (Exception e) {
  System.out.println("Failed trying to find LINE_IN"
    + " VOLUME control: exception = " + e);
}
if (volCtrl != null)
  // ...

从线路获取控件

一个需要在其用户界面中公开控件的应用程序可能只需查询可用的线路和控件，然后为感兴趣的每条线路上的每个控件显示适当的用户界面元素。在这种情况下，程序的唯一任务是为用户提供对控件的“处理”，而不是知道这些控件对音频信号做了什么。只要程序知道如何将线路的控件映射到用户界面元素，Java Sound API 的 Mixer、Line 和 Control 架构通常会处理其余部分。

例如，假设您的程序播放声音。您正在使用一个 SourceDataLine，如之前在 获取所需类型的线路 中描述的那样获取。您可以通过调用以下 Line 方法来访问线路的控件：

Control[] getControls()

然后，对于返回的数组中的每个控件，您可以使用以下 Control 方法来获取控件的类型：

Control.Type getType()

知道特定的Control.Type实例后，您的程序可以显示相应的用户界面元素。当然，为特定的Control.Type选择“相应的用户界面元素”取决于您的程序采取的方法。一方面，您可能会使用相同类型的元素来表示同一类别的所有Control.Type实例。这将需要您使用例如Object.getClass方法查询Control.Type实例的类。假设结果匹配了BooleanControl.Type。在这种情况下，您的程序可能会显示一个通用的复选框或切换按钮，但如果其类匹配了FloatControl.Type，那么您可能会显示一个图形滑块。

另一方面，您的程序可能会区分不同类型的控件，甚至是同一类别的控件，并为每个控件使用不同的用户界面元素。这将需要您测试Control's getType方法返回的实例。然后，例如，如果类型匹配了BooleanControl.Type.APPLY_REVERB，您的程序可能会显示一个复选框；而如果类型匹配了BooleanControl.Type.MUTE，您可能会显示一个切换按钮。

使用控件更改音频信号

现在您知道如何访问控件并确定其类型，本节将描述如何使用Controls来更改音频信号的各个方面。本节不涵盖所有可用的控件；相反，它提供了一些示例，以展示如何入门。这些示例包括：

• 控制线的静音状态

• 更改线路的音量

• 在各种混响预设中进行选择

假设您的程序已经访问了所有的混音器、它们的线路以及这些线路上的控件，并且它有一个数据结构来管理控件与其对应的用户界面元素之间的逻辑关联。那么，将用户对这些控件的操作转换为相应的Control方法就变得相当简单。

以下各小节描述了必须调用的一些方法，以影响特定控件的更改。

控制线的静音状态

控制任何线的静音状态只需调用以下BooleanControl方法：

void setValue(boolean value)

（可以假设程序通过引用其控件管理数据结构知道，静音是BooleanControl的一个实例。）为了使通过线路传递的信号静音，程序调用上述方法，指定值为true。要关闭静音，允许信号通过线路流动，程序调用该方法并将参数设置为false。

更改线路的音量

假设您的程序将特定的图形滑块与特定线路的音量控制相关联。音量控制的值（即FloatControl.Type.VOLUME）是使用以下FloatControl方法设置的：

void setValue(float newValue)

检测到用户移动滑块后，程序会获取滑块的当前值，并将其作为参数newValue传递给上述方法。这会改变通过拥有该控件的线路流动的信号的音量。

在各种混响预设中进行选择

假设我们的程序有一个带有类型为EnumControl.Type.REVERB的控件的混音器。调用EnumControl方法：

java.lang.Objects[] getValues()

在该控件上会生成一个ReverbType对象数组。如果需要，可以使用以下ReverbType方法访问每个对象的特定参数设置：

int getDecayTime() 
int getEarlyReflectionDelay() 
float getEarlyReflectionIntensity() 
int getLateReflectionDelay() 
float getLateReflectionIntensity() 

例如，如果一个程序只想要一个听起来像洞穴的混响设置，它可以迭代ReverbType对象，直到找到一个getDecayTime返回大于 2000 的值。有关这些方法的详细解释，包括代表性返回值表，请参阅javax.sound.sampled.ReverbType的 API 参考文档。

通常，程序会为getValues方法返回的数组中的每个ReverbType对象创建一个用户界面元素，例如单选按钮。当用户点击其中一个单选按钮时，程序会调用EnumControl方法。

void setValue(java.lang.Object value) 

其中value设置为与新选择的按钮对应的ReverbType。通过拥有此EnumControl的线路发送的音频信号将根据构成控件当前ReverbType（即setValue方法的value参数中指定的特定ReverbType）的参数设置而产生混响效果。

因此，从我们应用程序的角度来看，让用户从一个混响预设（即 ReverbType）移动到另一个只是将getValues返回的数组的每个元素连接到不同的单选按钮。

直接操作音频数据

Control API 允许 Java Sound API 的实现或混音器的第三方提供商通过控件提供任意类型的信号处理。但是如果没有混音器提供所需类型的信号处理怎么办？这需要更多的工作，但您可能可以在程序中实现信号处理。因为 Java Sound API 允许您将音频数据作为字节数组访问，您可以以任何您选择的方式修改这些字节。

如果您正在处理传入的声音，您可以从TargetDataLine中读取字节，然后对其进行操作。一个算法上微不足道但可以产生引人入胜结果的例子是通过将其帧按相反顺序排列来倒放声音。这个微不足道的例子可能对您的程序没有太大用处，但有许多复杂的数字信号处理（DSP）技术可能更合适。一些例子包括均衡、动态范围压缩、峰值限制、时间拉伸或压缩，以及延迟、合唱、混响、失真等特效。

要播放处理过的声音，您可以将处理后的字节数组放入SourceDataLine或Clip中。当然，字节数组不一定需要来自现有的声音。您可以从头开始合成声音，尽管这需要一些声学知识或者访问声音合成函数。无论是处理还是合成，您可能需要查阅音频 DSP 教科书以获取您感兴趣的算法，或者将第三方信号处理函数库导入到您的程序中。对于合成声音的播放，考虑一下javax.sound.midi包中的Synthesizer API 是否符合您的需求。稍后在合成声音下您将了解更多关于javax.sound.midi的内容。

使用文件和格式转换器

原文：docs.oracle.com/javase/tutorial/sound/converters.html

大多数处理声音的应用程序需要读取声音文件或音频流。这是常见的功能，无论程序随后对读取的数据做什么（如播放、混合或处理）。同样，许多程序需要写入声音文件（或流）。在某些情况下，已读取的数据（或将要写入的数据）需要转换为不同的格式。

正如在访问音频系统资源中简要提到的，Java Sound API 为应用程序开发人员提供了各种设施，用于文件输入/输出和格式转换。应用程序可以读取、写入和在各种声音文件格式和音频数据格式之间进行转换。

采样包概述介绍了与声音文件和音频数据格式相关的主要类。作为回顾：

• 从文件中读取或写入的音频数据流由AudioInputStream对象表示。（AudioInputStream继承自java.io.InputStream。）

• 此音频数据的格式由AudioFormat对象表示。

  此格式指定了音频样本本身的排列方式，但不指定它们可能存储在的文件的结构。换句话说，AudioFormat描述了“原始”音频数据，例如系统在从麦克风输入捕获或从声音文件解析后可能传递给程序的数据。AudioFormat包括编码、字节顺序、通道数、采样率和每个样本的位数等信息。

• 有几种众所周知的标准声音文件格式，如 WAV、AIFF 或 AU。不同类型的声音文件具有不同的存储音频数据以及存储有关音频数据的描述信息的结构。Java Sound API 中通过AudioFileFormat对象表示声音文件格式。AudioFileFormat包括一个AudioFormat对象来描述文件中存储的音频数据的格式，还包括有关文件类型和文件中数据长度的信息。

• AudioSystem类提供了方法，用于将来自AudioInputStream的音频数据流存储到特定类型的音频文件中（换句话说，写入文件），从音频文件中提取音频字节流（AudioInputStream）（换句话说，读取文件），以及将音频数据从一种数据格式转换为另一种数据格式。本页分为三个部分，解释了这三种活动。

注意：

Java Sound API 的实现不一定提供全面的设施来读取、写入和转换不同数据和文件格式的音频。它可能仅支持最常见的数据和文件格式。然而，服务提供者可以开发和分发扩展这一集合的转换服务，正如你稍后将在提供采样音频服务中看到的那样。AudioSystem类提供了允许应用程序了解可用转换的方法，稍后在转换文件和数据格式下描述。

读取声音文件

AudioSystem类提供了两种类型的文件读取服务：

• 存储在声音文件中的音频数据格式的信息

• 可从声音文件中读取的格式化音频数据流

第一个是getAudioFileFormat方法的三个变体：

    static AudioFileFormat getAudioFileFormat (java.io.File file)
    static AudioFileFormat getAudioFileFormat(java.io.InputStream stream)
    static AudioFileFormat getAudioFileFormat (java.net.URL url)

如上所述，返回的AudioFileFormat对象告诉你文件类型、文件中数据的长度、编码、字节顺序、通道数、采样率和每个样本的位数。

第二种文件读取功能由这些AudioSystem方法提供。

    static AudioInputStream getAudioInputStream (java.io.File file)
    static AudioInputStream getAudioInputStream (java.net.URL url)
    static AudioInputStream getAudioInputStream (java.io.InputStream stream)

这些方法给你一个对象（一个AudioInputStream），让你使用AudioInputStream的读取方法读取文件的音频数据。我们马上会看到一个例子。

假设你正在编写一个声音编辑应用程序，允许用户从文件中加载声音数据，显示相应的波形图或频谱图，编辑声音，播放编辑后的数据，并将结果保存在新文件中。或者你的程序将读取文件中存储的数据，应用某种信号处理（例如减慢声音而不改变音调的算法），然后播放处理后的音频。在任何情况下，你需要访问音频文件中包含的数据。假设你的程序提供了一些方式让用户选择或指定输入声音文件，读取该文件的音频数据涉及三个步骤：

1. 从文件中获取一个AudioInputStream对象。

2. 创建一个字节数组，用于存储文件中连续的数据块。

3. 重复从音频输入流中读取字节到数组中。在每次迭代中，对数组中的字节执行一些有用的操作（例如，你可以播放它们、过滤它们、分析它们、显示它们或将它们写入另一个文件）。

以下代码片段概述了这些步骤：

int totalFramesRead = 0;
File fileIn = new File(somePathName);
// somePathName is a pre-existing string whose value was
// based on a user selection.
try {
  AudioInputStream audioInputStream = 
    AudioSystem.getAudioInputStream(fileIn);
  int bytesPerFrame = 
    audioInputStream.getFormat().getFrameSize();
    if (bytesPerFrame == AudioSystem.NOT_SPECIFIED) {
    // some audio formats may have unspecified frame size
    // in that case we may read any amount of bytes
    bytesPerFrame = 1;
  } 
  // Set an arbitrary buffer size of 1024 frames.
  int numBytes = 1024 * bytesPerFrame; 
  byte[] audioBytes = new byte[numBytes];
  try {
    int numBytesRead = 0;
    int numFramesRead = 0;
    // Try to read numBytes bytes from the file.
    while ((numBytesRead = 
      audioInputStream.read(audioBytes)) != -1) {
      // Calculate the number of frames actually read.
      numFramesRead = numBytesRead / bytesPerFrame;
      totalFramesRead += numFramesRead;
      // Here, do something useful with the audio data that's 
      // now in the audioBytes array...
    }
  } catch (Exception ex) { 
    // Handle the error...
  }
} catch (Exception e) {
  // Handle the error...
}

让我们看看上面代码示例中发生了什么。首先，外部的try子句通过调用AudioSystem.getAudioInputStream(File)方法实例化了一个AudioInputStream对象。此方法透明地执行了所有必要的测试，以确定指定的文件实际上是 Java Sound API 支持的声音文件类型。如果正在检查的文件（例如此示例中的fileIn）不是声音文件，或者是某种不受支持的声音文件类型，将抛出UnsupportedAudioFileException异常。这种行为很方便，因为应用程序员不需要测试文件属性，也不需要遵守任何文件命名约定。相反，getAudioInputStream方法负责处理验证输入文件所需的所有底层解析和验证。然后，外部的try子句创建了一个名为audioBytes的字节数组，长度是任意固定的。我们确保其字节长度等于整数帧数，这样我们就不会最终只读取部分帧或更糟糕的是只读取部分样本。这个字节数组将作为一个缓冲区，临时保存从流中读取的一块音频数据。如果我们知道我们将只读取非常短的声音文件，我们可以使此数组与文件中的数据长度相同，通过从AudioInputStream的getFrameLength方法返回的帧数长度来推导其字节长度。（实际上，我们可能会使用Clip对象。）但为了避免在一般情况下耗尽内存，我们会一次读取一个缓冲区的文件。

内部的try子句包含一个while循环，在这里我们将音频数据从AudioInputStream读入字节数组中。您应该在此循环中添加代码，以适当处理此数组中的音频数据，以满足程序的需求。如果您对数据应用某种信号处理，您可能需要进一步查询AudioInputStream的AudioFormat，以了解每个样本的位数等信息。

注意，方法AudioInputStream.read(byte[])返回读取的字节数，而不是样本数或帧数。当没有更多数据可读取时，此方法返回-1。一旦检测到这种情况，我们就会跳出while循环。

写入声音文件

前一节描述了读取声音文件的基础知识，使用了AudioSystem和AudioInputStream类的特定方法。本节描述了如何将音频数据写入新文件。

以下AudioSystem方法创建指定文件类型的磁盘文件。该文件将包含指定AudioInputStream中的音频数据：

static int write(AudioInputStream in, 
  AudioFileFormat.Type fileType, File out)

请注意，第二个参数必须是系统支持的文件类型之一（例如，AU、AIFF 或 WAV），否则write方法将抛出IllegalArgumentException。为了避免这种情况，您可以通过调用此AudioSystem方法来测试特定AudioInputStream是否可以写入特定类型的文件：

static boolean isFileTypeSupported
  (AudioFileFormat.Type fileType, AudioInputStream stream)

只有在支持特定组合时才会返回true。

更一般地，您可以通过调用这些AudioSystem方法来了解系统可以写入哪些类型的文件：

static AudioFileFormat.Type[] getAudioFileTypes() 
static AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) 

其中第一个返回系统可以写入的所有文件类型，第二个仅返回系统可以从给定音频输入流写入的文件类型。

以下摘录演示了使用上述提到的write方法从AudioInputStream创建输出文件的一种技术。

File fileOut = new File(someNewPathName);
AudioFileFormat.Type fileType = fileFormat.getType();
if (AudioSystem.isFileTypeSupported(fileType, 
    audioInputStream)) {
  AudioSystem.write(audioInputStream, fileType, fileOut);
}

上面的第一个语句创建了一个新的File对象fileOut，带有用户或程序指定的路径名。第二个语句从名为fileFormat的预先存在的AudioFileFormat对象中获取文件类型，该对象可能已从其他声音文件（例如，在上面的读取声音文件中读取的文件）中获取。 （您可以选择提供您想要的任何支持的文件类型，而不是从其他地方获取文件类型。例如，您可以删除第二个语句，并将上面代码中的其他两个fileType出现替换为AudioFileFormat.Type.WAVE。）

第三个语句测试指定类型的文件是否可以从所需的AudioInputStream写入。与文件格式一样，此流可能是先前读取的声音文件派生而来的。（如果是这样，那么您可能以某种方式处理或更改了其数据，否则有更简单的方法可以简单地复制文件。）或者也许该流包含从麦克风输入中新捕获的字节。

最后，流、文件类型和输出文件被传递给AudioSystem.write方法，以实现写入文件的目标。

转换文件和数据格式

请回想一下什么是格式化音频数据？，Java Sound API 区分音频文件格式和音频数据格式。这两者或多或少是独立的。粗略地说，数据格式指的是计算机表示每个原始数据点（样本）的方式，而文件格式指的是存储在磁盘上的声音文件的组织方式。每种声音文件格式都有一个定义文件头中存储信息的特定结构。在某些情况下，文件格式还包括包含某种形式元数据的结构，除了实际的“原始”音频样本。本页的其余部分将探讨 Java Sound API 的方法，这些方法使得可以进行各种文件格式和数据格式的转换。

从一种文件格式转换为另一种

本节介绍了在 Java Sound API 中转换音频文件类型的基础知识。再次，我们提出一个假设的程序，其目的是从任意输入文件中读取音频数据并将其写入类型为 AIFF 的文件中。当然，输入文件必须是系统能够读取的类型，输出文件必须是系统能够写入的类型。（在此示例中，我们假设系统能够写入 AIFF 文件。）示例程序不执行任何数据格式转换。如果输入文件的数据格式无法表示为 AIFF 文件，则程序简单地通知用户存在问题。另一方面，如果输入音频文件已经是 AIFF 文件，则程序会通知用户无需转换。

以下函数实现了刚才描述的逻辑：

public void ConvertFileToAIFF(String inputPath, 
  String outputPath) {
  AudioFileFormat inFileFormat;
  File inFile;
  File outFile;
  try {
    inFile = new File(inputPath);
    outFile = new File(outputPath);     
  } catch (NullPointerException ex) {
    System.out.println("Error: one of the 
      ConvertFileToAIFF" +" parameters is null!");
    return;
  }
  try {
    // query file type
    inFileFormat = AudioSystem.getAudioFileFormat(inFile);
    if (inFileFormat.getType() != AudioFileFormat.Type.AIFF) 
    {
      // inFile is not AIFF, so let's try to convert it.
      AudioInputStream inFileAIS = 
        AudioSystem.getAudioInputStream(inFile);
      inFileAIS.reset(); // rewind
      if (AudioSystem.isFileTypeSupported(
             AudioFileFormat.Type.AIFF, inFileAIS)) {
         // inFileAIS can be converted to AIFF. 
         // so write the AudioInputStream to the
         // output file.
         AudioSystem.write(inFileAIS,
           AudioFileFormat.Type.AIFF, outFile);
         System.out.println("Successfully made AIFF file, "
           + outFile.getPath() + ", from "
           + inFileFormat.getType() + " file, " +
           inFile.getPath() + ".");
         inFileAIS.close();
         return; // All done now
       } else
         System.out.println("Warning: AIFF conversion of " 
           + inFile.getPath()
           + " is not currently supported by AudioSystem.");
    } else
      System.out.println("Input file " + inFile.getPath() +
          " is AIFF." + " Conversion is unnecessary.");
  } catch (UnsupportedAudioFileException e) {
    System.out.println("Error: " + inFile.getPath()
        + " is not a supported audio file type!");
    return;
  } catch (IOException e) {
    System.out.println("Error: failure attempting to read " 
      + inFile.getPath() + "!");
    return;
  }
}

如前所述，此示例函数ConvertFileToAIFF的目的是查询输入文件，以确定它是否是 AIFF 音频文件，如果不是，则尝试将其转换为 AIFF 格式，生成一个新的副本，其路径名由第二个参数指定。（作为练习，您可以尝试使此函数更通用，以便不总是转换为 AIFF，而是根据新的函数参数指定的文件类型进行转换。）请注意，副本的音频数据格式——即新文件模仿原始输入文件的音频数据格式。

大部分此函数是不言自明的，并且与 Java Sound API 无关。然而，例程中使用了一些 Java Sound API 方法，这些方法对于音频文件类型转换至关重要。这些方法调用都在上面的第二个try子句中找到，包括以下内容：

• AudioSystem.getAudioFileFormat：在此处用于确定输入文件是否已经是 AIFF 类型。如果是，则函数会快速返回；否则，转换尝试继续进行。

• AudioSystem.isFileTypeSupported：指示系统是否可以写入包含来自指定AudioInputStream的音频数据的指定类型文件。在我们的示例中，如果指定的音频输入文件可以转换为 AIFF 音频文件格式，则此方法返回true。如果不支持AudioFileFormat.Type.AIFF，ConvertFileToAIFF会发出警告，指出无法转换输入文件，然后返回。

• AudioSystem.write：在此处用于将inFileAIS的音频数据从AudioInputStream写入到输出文件outFile中。

这些方法中的第二个isFileTypeSupported方法有助于在写入之前确定特定输入音频文件是否可以转换为特定输出音频文件类型。在下一节中，我们将看到如何通过对ConvertFileToAIFF示例例程进行一些修改，可以转换音频数据格式以及音频文件类型。

在不同数据格式之间转换音频

前一节展示了如何使用 Java Sound API 将文件从一种文件格式（即一种声音文件类型）转换为另一种。本节探讨了一些方法，这些方法使音频数据格式转换成为可能。

在前一节中，我们从一个任意类型的文件中读取数据，并将其保存在一个 AIFF 文件中。请注意，尽管我们改变了用于存储数据的文件类型，但我们并没有改变音频数据本身的格式。（大多数常见的音频文件类型，包括 AIFF，可以包含各种格式的音频数据。）因此，如果原始文件包含 CD 音质音频数据（16 位样本大小、44.1kHz 采样率和两个声道），那么我们的输出 AIFF 文件也会包含相同的数据。

现在假设我们想要指定输出文件的数据格式，以及文件类型。例如，也许我们正在保存许多长文件以供在互联网上使用，并且担心我们的文件所需的磁盘空间和下载时间。我们可能选择创建包含低分辨率数据的较小的 AIFF 文件-例如，具有 8 位样本大小、8kHz 采样率和单声道的数据。

不像之前那样详细地进行编码，让我们探讨一些用于数据格式转换的方法，并考虑我们需要对ConvertFileToAIFF函数进行的修改以实现新目标。

音频数据转换的主要方法再次在AudioSystem类中找到。这个方法是getAudioInputStream的一个变体：

AudioInputStream getAudioInputStream(AudioFormat
    format, AudioInputStream stream)

此函数返回一个AudioInputStream，该流是使用指定的AudioFormat``format转换stream的结果。如果AudioSystem不支持转换，此函数会抛出IllegalArgumentException。

为了避免这种情况，我们可以首先通过调用这个AudioSystem方法来检查系统是否可以执行所需的转换：

boolean isConversionSupported(AudioFormat targetFormat,
    AudioFormat sourceFormat)

在这种情况下，我们将stream.getFormat()作为第二个参数传递。

要创建一个特定的AudioFormat对象，我们使用下面显示的两个AudioFormat构造函数之一，要么：

AudioFormat(float sampleRate, int sampleSizeInBits,
    int channels, boolean signed, boolean bigEndian)

使用线性 PCM 编码和给定参数构造一个AudioFormat，或者：

AudioFormat(AudioFormat.Encoding encoding, 
    float sampleRate, int sampleSizeInBits, int channels,
    int frameSize, float frameRate, boolean bigEndian) 

还构造了一个AudioFormat，但允许您指定编码、帧大小和帧速率，除了其他参数。

现在，有了上面的方法，让我们看看如何扩展我们的ConvertFileToAIFF函数以执行所需的“低分辨率”音频数据格式转换。首先，我们将构造一个描述所需输出音频数据格式的AudioFormat对象。以下语句就足够了，并且可以插入到函数的顶部附近：

AudioFormat outDataFormat = new AudioFormat((float) 8000.0,
(int) 8, (int) 1, true, false);

由于上面的AudioFormat构造函数描述了一个具有 8 位样本的格式，因此构造函数的最后一个参数，指定样本是大端还是小端，是无关紧要的。（大端与小端只有在样本大小大于一个字节时才是一个问题。）

以下示例展示了我们如何使用这个新的AudioFormat来转换我们从输入文件创建的AudioInputStream，inFileAIS：

AudioInputStream lowResAIS;         
  if (AudioSystem.isConversionSupported(outDataFormat,   
    inFileAIS.getFormat())) {
    lowResAIS = AudioSystem.getAudioInputStream
      (outDataFormat, inFileAIS);
  }

不管我们在何处插入这段代码，只要它在构建inFileAIS之后即可。如果没有isConversionSupported测试，如果请求的特定转换不受支持，调用将失败并抛出IllegalArgumentException。（在这种情况下，控制将转移到我们函数中适当的catch子句。）

因此，在这个过程中，我们将产生一个新的AudioInputStream，这是通过将原始输入文件（以其AudioInputStream形式）转换为由outDataFormat定义的所需低分辨率音频数据格式而产生的。

生成所需的低分辨率 AIFF 声音文件的最后一步是将AudioSystem.write调用中的AudioInputStream参数（即第一个参数）替换为我们转换后的流lowResAIS，如下所示：

AudioSystem.write(lowResAIS, AudioFileFormat.Type.AIFF, 
  outFile);

对我们之前的函数进行这几处修改，可以产生一个能够转换任何指定输入文件的音频数据和文件格式的东西，前提是系统支持转换。

学习可用的转换方式

几个AudioSystem方法会测试它们的参数，以确定系统是否支持特定的数据格式转换或文件写入操作。（通常，每个方法都与另一个方法配对，执行数据转换或写入文件。）其中一个查询方法AudioSystem.isFileTypeSupported在我们的示例函数ConvertFileToAIFF中被使用，以确定系统是否能够将音频数据写入 AIFF 文件。相关的AudioSystem方法getAudioFileTypes(AudioInputStream)返回给定流支持的所有文件类型的完整列表，作为AudioFileFormat.Type实例的数组。该方法：BEGINCODE boolean isConversionSupported(AudioFormat.Encoding encoding，

AudioFormat 格式）

用于确定是否可以从具有指定音频格式的音频输入流中获取具有指定编码的音频输入流。类似地，该方法：

boolean isConversionSupported(AudioFormat newFormat,
                              AudioFormat oldFormat) 

告诉我们是否可以通过将具有音频格式oldFormat的AudioInputStream转换为具有指定音频格式newFormat的AudioInputStream来获得AudioInputStream。（这个方法在前一节代码片段中被调用，用于创建低分辨率音频输入流lowResAIS。）

这些与格式相关的查询有助于在尝试使用 Java Sound API 执行格式转换时防止错误。

MIDI 包概述

原文：docs.oracle.com/javase/tutorial/sound/overview-MIDI.html

介绍简要介绍了 Java Sound API 的 MIDI 功能。接下来的讨论更详细地介绍了通过javax.sound.midi包访问的 Java Sound API 的 MIDI 架构。解释了一些 MIDI 本身的基本特性，作为一个复习或介绍，以便将 Java Sound API 的 MIDI 功能放入上下文中。然后继续讨论 Java Sound API 对 MIDI 的处理，为后续部分中解释的编程任务做准备。对 MIDI API 的讨论分为两个主要领域：数据和设备。

MIDI 复习：线缆和文件

音乐器数字接口（MIDI）标准定义了一种用于电子音乐设备（如电子键盘乐器和个人计算机）的通信协议。MIDI 数据可以在现场表演期间通过特殊电缆传输，并且还可以存储在标准类型的文件中以供以后播放或编辑。

本节回顾了一些 MIDI 基础知识，不涉及 Java Sound API。这个讨论旨在为熟悉 MIDI 的读者提供一个复习，为不熟悉的读者提供一个简要介绍，为随后讨论 Java Sound API 的 MIDI 包提供背景。如果您对 MIDI 有深入了解，可以安全地跳过本节。在编写大量 MIDI 应用程序之前，不熟悉 MIDI 的程序员可能需要比本教程中包含的更详细的 MIDI 描述。请参阅仅在硬拷贝中提供的完整 MIDI 1.0 详细规范，可从www.midi.org获取（尽管您可能会在网上找到改写或摘要版本）。

MIDI 既是硬件规范，也是软件规范。要理解 MIDI 的设计，了解其历史是有帮助的。MIDI 最初是为了在电子键盘乐器（如合成器）之间传递音乐事件（如按键）而设计的。被称为音序器的硬件设备存储了可以控制合成器的音符序列，允许音乐表演被录制并随后播放。后来，开发了连接 MIDI 乐器与计算机串口的硬件接口，允许音序器在软件中实现。最近，计算机声卡已经整合了用于 MIDI I/O 和合成音乐声音的硬件。如今，许多 MIDI 用户只使用声卡，从不连接外部 MIDI 设备。CPU 已经足够快，以至于合成器也可以在软件中实现。只有在音频 I/O 和在某些应用中与外部 MIDI 设备通信时才需要声卡。

MIDI 规范的简要硬件部分规定了 MIDI 电缆的引脚排列方式以及这些电缆插入的插孔。这部分内容不需要我们关心。因为最初需要硬件的设备，如音序器和合成器，现在可以在软件中实现，也许大多数程序员需要了解 MIDI 硬件设备的唯一原因只是为了理解 MIDI 中的隐喻。然而，外部 MIDI 硬件设备对于一些重要的音乐应用仍然至关重要，因此 Java Sound API 支持 MIDI 数据的输入和输出。

MIDI 规范的软件部分非常广泛。这部分内容涉及 MIDI 数据的结构以及合成器等设备应如何响应该数据。重要的是要理解 MIDI 数据可以流式传输或序列化。这种二元性反映了 Complete MIDI 1.0 详细规范的两个不同部分：

• MIDI 1.0

• 标准 MIDI 文件

通过检查 MIDI 规范的这两个部分的目的，我们将解释流式传输和序列化的含义。

MIDI 线协议中的流数据

MIDI 规范的这两个部分中的第一个描述了非正式称为“MIDI 线协议”的内容。 MIDI 线协议，即原始 MIDI 协议，基于这样一个假设，即 MIDI 数据正在通过 MIDI 电缆（“线”）发送。电缆将数字数据从一个 MIDI 设备传输到另一个 MIDI 设备。每个 MIDI 设备可能是乐器或类似设备，也可能是配备有 MIDI 功能的声卡或 MIDI 到串口接口的通用计算机。

MIDI 数据，根据 MIDI 线协议定义，被组织成消息。不同类型的消息由消息中的第一个字节区分，称为状态字节。（状态字节是唯一一个最高位设置为 1 的字节。）在消息中跟随状态字节的字节称为数据字节。某些 MIDI 消息，称为通道消息，具有包含四位用于指定通道消息类型和另外四位用于指定通道号的状态字节。因此有 16 个 MIDI 通道；接收 MIDI 消息的设备可以设置为响应所有或仅一个这些虚拟通道上的通道消息。通常，每个 MIDI 通道（不应与音频通道混淆）用于发送不同乐器的音符。例如，两个常见的通道消息是 Note On 和 Note Off，分别启动音符发声并停止它。这两个消息各自需要两个数据字节：第一个指定音符的音高，第二个指定其“速度”（假设键盘乐器正在演奏音符时按下或释放键的速度）。

MIDI 传输协议为 MIDI 数据定义了一个流模型。该协议的一个核心特点是 MIDI 数据的字节是实时传递的，换句话说，它们是流式传输的。数据本身不包含时间信息；每个事件在接收时被处理，并假定它在正确的时间到达。如果音符是由现场音乐家生成的，那么这种模型是可以接受的，但如果您想要存储音符以便以后播放，或者想要在实时之外进行组合，那么这是不够的。当您意识到 MIDI 最初是为音乐表演而设计的，作为键盘音乐家在许多音乐家使用计算机之前控制多个合成器的一种方式时，这种限制是可以理解的。（规范的第一个版本于 1984 年发布。）

标准 MIDI 文件中的序列化数据

MIDI 规范的标准 MIDI 文件部分解决了 MIDI 传输协议中的时间限制。标准 MIDI 文件是一个包含 MIDI 事件 的数字文件。一个事件简单地是一个 MIDI 消息，如 MIDI 传输协议中定义的，但附加了一个指定事件时间的额外信息。（还有一些事件不对应 MIDI 传输协议消息，我们将在下一节中看到。）额外的时间信息是一系列字节，指示何时执行消息描述的操作。换句话说，标准 MIDI 文件不仅指定要播放哪些音符，而且确切地指定何时播放每一个音符。这有点像一个乐谱。

标准 MIDI 文件中的信息被称为序列。标准 MIDI 文件包含一个或多个轨道。每个轨道通常包含一个乐器会演奏的音符，如果音乐由现场音乐家演奏。一个序列器是一个可以读取序列并在正确时间传递其中包含的 MIDI 消息的软件或硬件设备。一个序列器有点像一个管弦乐队指挥：它拥有所有音符的信息，包括它们的时间，然后告诉其他实体何时演奏这些音符。

Java Sound API 对 MIDI 数据的表示

现在我们已经勾勒出 MIDI 规范对流式和序列化音乐数据的处理方式，让我们来看看 Java Sound API 如何表示这些数据。

MIDI 消息

MidiMessage 是表示“原始” MIDI 消息的抽象类。一个“原始” MIDI 消息通常是由 MIDI 传输协议定义的消息。它也可以是标准 MIDI 文件规范中定义的事件之一，但没有事件的时间信息。在 Java Sound API 中，有三类原始 MIDI 消息，分别由这三个相应的 MidiMessage 子类表示：

• ShortMessages是最常见的消息，状态字节后最多有两个数据字节。通道消息，如 Note On 和 Note Off，都是短消息，还有一些其他消息也是短消息。

• SysexMessages包含系统专用的 MIDI 消息。它们可能有许多字节，并且通常包含制造商特定的指令。

• MetaMessages出现在 MIDI 文件中，但不出现在 MIDI 线协议中。元消息包含数据，例如歌词或速度设置，这对于音序器可能很有用，但通常对合成器没有意义。

MIDI 事件

正如我们所见，标准 MIDI 文件包含用于包装“原始”MIDI 消息以及时间信息的事件。Java Sound API 的MidiEvent类的实例代表了一个类似于标准 MIDI 文件中存储的事件。

MidiEvent的 API 包括设置和获取事件的时间值的方法。还有一个方法用于检索其嵌入的原始 MIDI 消息，这是MidiMessage子类的实例，接下来会讨论。（嵌入的原始 MIDI 消息只能在构造MidiEvent时设置。）

序列和轨道

如前所述，标准 MIDI 文件存储被安排到轨道中的事件。通常文件代表一个音乐作品，通常每个轨道代表一个部分，例如可能由单个乐器演奏。乐器演奏的每个音符至少由两个事件表示：开始音符的 Note On 和结束音符的 Note Off。轨道还可能包含不对应音符的事件，例如元事件（如上所述）。

Java Sound API 将 MIDI 数据组织成三部分层次结构：

• Sequence

• Track

• MidiEvent

Track是MidiEvents的集合，Sequence是Tracks的集合。这种层次结构反映了标准 MIDI 文件规范中的文件、轨道和事件。（注意：这是一种包含和拥有的层次结构；这不是一种继承的类层次结构。这三个类直接继承自java.lang.Object。）

Sequences可以从 MIDI 文件中读取，也可以从头开始创建并通过向Sequence添加Tracks（或删除它们）进行编辑。同样，MidiEvents可以添加到序列中的轨道中，也可以从中删除。

Java Sound API 对 MIDI 设备的表示

前一节解释了 MIDI 消息在 Java Sound API 中的表示方式。然而，MIDI 消息并不是独立存在的。它们通常从一个设备发送到另一个设备。使用 Java Sound API 的程序可以从头开始生成 MIDI 消息，但更常见的情况是这些消息是由软件设备（如序列器）创建的，或者通过 MIDI 输入端口从计算机外部接收。这样的设备通常会将这些消息发送到另一个设备，比如合成器或 MIDI 输出端口。

MidiDevice 接口

在外部 MIDI 硬件设备的世界中，许多设备可以将 MIDI 消息传输到其他设备，并从其他设备接收消息。同样，在 Java Sound API 中，实现MidiDevice接口的软件对象可以传输和接收消息。这样的对象可以纯粹在软件中实现，也可以作为硬件的接口，比如声卡的 MIDI 功能。基本的MidiDevice接口提供了 MIDI 输入或输出端口通常所需的所有功能。然而，合成器和序列器进一步实现了MidiDevice的子接口之一：Synthesizer或Sequencer。

MidiDevice接口包括用于打开和关闭设备的 API。它还包括一个名为MidiDevice.Info的内部类，提供设备的文本描述，包括其名称、供应商和版本。如果您已经阅读了本教程的采样音频部分，那么这个 API 可能会听起来很熟悉，因为其设计类似于javax.sampled.Mixer接口，代表音频设备，并且具有类似的内部类Mixer.Info。

发送器和接收器

大多数 MIDI 设备都能够发送MidiMessages、接收它们，或两者兼而有之。设备发送数据的方式是通过它“拥有”的一个或多个发送器对象。同样，设备接收数据的方式是通过一个或多个接收器对象。发送器对象实现了Transmitter接口，而接收器实现了Receiver接口。

每个发送器一次只能连接到一个接收器，反之亦然。一个设备如果同时向多个其他设备发送其 MIDI 消息，则通过拥有多个发送器，每个发送器连接到不同设备的接收器来实现。同样，一个设备如果要同时从多个来源接收 MIDI 消息，则必须通过多个接收器来实现。

序列器

一个序列器是一种捕获和播放 MIDI 事件序列的设备。它具有发射器，因为它通常将存储在序列中的 MIDI 消息发送到另一个设备，例如合成器或 MIDI 输出端口。它还具有接收器，因为它可以捕获 MIDI 消息并将其存储在序列中。在其超接口MidiDevice中，Sequencer添加了用于基本 MIDI 序列操作的方法。序列器可以从 MIDI 文件加载序列，查询和设置序列的速度，并将其他设备与其同步。应用程序可以注册一个对象，以便在序列器处理某些类型的事件时收到通知。

合成器

Synthesizer是一种产生声音的设备。它是javax.sound.midi包中唯一产生音频数据的对象。合成器设备控制一组 MIDI 通道对象 - 通常是 16 个，因为 MIDI 规范要求有 16 个 MIDI 通道。这些 MIDI 通道对象是实现MidiChannel接口的类的实例，其方法代表 MIDI 规范的“通道音频消息”和“通道模式消息”。

应用程序可以通过直接调用合成器的 MIDI 通道对象的方法来生成声音。然而，更常见的情况是，合成器响应发送到其一个或多个接收器的消息而生成声音。例如，这些消息可能是由序列器或 MIDI 输入端口发送的。合成器解析其接收器接收到的每条消息，并通常根据事件中指定的 MIDI 通道号将相应的命令（如noteOn或controlChange）发送到其一个MidiChannel对象。

MidiChannel使用这些消息中的音符信息来合成音乐。例如，noteOn消息指定了音符的音高和“速度”（音量）。然而，音符信息是不够的；合成器还需要关于如何为每个音符创建音频信号的精确指令。这些指令由一个Instrument表示。每个Instrument通常模拟不同的真实乐器或音效。Instruments可能作为合成器的预设提供，也可能从声音库文件中加载。在合成器中，Instruments按照银行号（可以将其视为行）和程序号（列）进行排列。

本节为理解 MIDI 数据提供了背景，并介绍了与 Java Sound API 中的 MIDI 相关的一些重要接口和类。后续章节将展示如何在应用程序中访问和使用这些对象。

访问 MIDI 系统资源

原文：docs.oracle.com/javase/tutorial/sound/accessing-MIDI.html

Java Sound API 为 MIDI 系统配置提供了灵活的模型，就像为采样音频系统配置一样。Java Sound API 的实现本身可以提供不同类型的 MIDI 设备，并且服务提供者和用户可以提供并安装其他设备。您可以编写程序，使其对计算机上安装的具体 MIDI 设备做出少量假设。相反，程序可以利用 MIDI 系统的默认设置，或者允许用户从可用设备中选择。

本节展示了您的程序如何了解已安装的 MIDI 资源，以及如何访问所需的资源。在访问并打开设备之后，您可以将它们连接在一起，如后面的 传输和接收 MIDI 消息 中所讨论的。

MidiSystem 类

Java Sound API 的 MIDI 包中的 MidiSystem 类的作用与采样音频包中的 AudioSystem 类的作用直接类似。MidiSystem 充当访问已安装 MIDI 资源的中转站。

您可以查询MidiSystem以了解安装了什么类型的设备，然后可以遍历可用设备并访问所需设备。例如，一个应用程序可能首先询问MidiSystem有哪些合成器可用，然后显示一个列表，用户可以从中选择一个。一个更简单的应用程序可能只使用系统的默认合成器。

MidiSystem 类还提供了在 MIDI 文件和Sequences之间进行转换的方法。它可以报告 MIDI 文件的文件格式，并且可以写入不同类型的文件。

应用程序可以从MidiSystem获取以下资源：

• 顺序器

• 合成器

• 发射器（例如与 MIDI 输入端口相关联的发射器）

• 接收器（例如与 MIDI 输出端口相关联的接收器）

• 来自标准 MIDI 文件的数据

• 来自声音库文件的数据

本页重点介绍了这些类型资源中的前四种。其他类型将在本教程的后面讨论。

获取默认设备

使用 Java Sound API 的典型 MIDI 应用程序程序首先获取所需的设备，这些设备可以包括一个或多个顺序器、合成器、输入端口或输出端口。

有一个默认的合成器设备，一个默认的定序器设备，一个默认的传输设备和一个默认的接收设备。后两个设备通常代表系统上可用的 MIDI 输入和输出端口，如果有的话。（在这里很容易混淆方向性。将端口的传输或接收视为与软件相关，而不是与连接到物理端口的任何外部物理设备相关。MIDI 输入端口传输来自外部设备的数据到 Java Sound API 的Receiver，同样，MIDI 输出端口接收来自软件对象的数据并将数据中继到外部设备。）

一个简单的应用程序可能只使用默认设备而不探索所有安装的设备。MidiSystem类包括以下方法来检索默认资源：

static Sequencer getSequencer()
static Synthesizer getSynthesizer()
static Receiver getReceiver()
static Transmitter getTransmitter()

前两种方法获取系统的默认排序和合成资源，这些资源可以代表物理设备或完全在软件中实现。getReceiver方法获取一个Receiver对象，该对象接收发送给它的 MIDI 消息并将其中继到默认接收设备。类似地，getTransmitter方法获取一个 Transmitter 对象，该对象可以代表默认传输设备向某个接收设备发送 MIDI 消息。

学习安装了哪些设备

与使用默认设备不同，更彻底的方法是从系统上安装的所有设备中选择所需的设备。应用程序可以通过编程方式选择所需的设备，或者可以显示可用设备列表，让用户选择要使用的设备。MidiSystem类提供了一个方法来了解安装了哪些设备，以及一个相应的方法来获取给定类型的设备。

以下是学习已安装设备的方法：

 static MidiDevice.Info[] getMidiDeviceInfo()

如您所见，它返回一个信息对象数组。每个返回的MidiDevice.Info对象标识已安装的一种类型的定序器、合成器、端口或其他设备。（通常系统最多只有一个给定类型的实例。例如，来自某个供应商的特定型号的合成器只会安装一次。）MidiDevice.Info包括以下字符串来描述设备：

• 名称

• 版本号

• 厂商（创建设备的公司）

• 设备的描述

您可以在用户界面中显示这些字符串，让用户从设备列表中进行选择。

然而，要在程序中使用字符串来选择设备（而不是向用户显示字符串），你需要事先知道可能的字符串是什么。每个提供设备的公司应该在其文档中包含这些信息。需要或偏好特定设备的应用程序可以利用这些信息来定位该设备。这种方法的缺点是将程序限制在事先知道的设备实现上。

另一种更一般的方法是继续遍历MidiDevice.Info对象，获取每个相应的设备，并以编程方式确定是否适合使用（或至少适合包含在用户可以选择的列表中）。下一节将介绍如何执行此操作。

获取所需设备

一旦找到适当设备的信息对象，应用程序调用以下MidiSystem方法来获取相应的设备本身：

static MidiDevice getMidiDevice(MidiDevice.Info info)

如果您已经找到描述所需设备的信息对象，可以使用此方法。但是，如果无法解释getMidiDeviceInfo返回的信息对象以确定所需设备，且不想向用户显示所有设备的信息，您可以尝试以下操作：遍历getMidiDeviceInfo返回的所有MidiDevice.Info对象，使用上述方法获取相应设备，并测试每个设备以查看其是否合适。换句话说，您可以在将设备包含在向用户显示的列表中之前，查询每个设备的类和功能，或者以编程方式决定设备而不涉及用户。例如，如果您的程序需要合成器，可以获取每个已安装的设备，查看哪些是实现Synthesizer接口的类的实例，然后将它们显示在用户可以选择的列表中，如下所示：

// Obtain information about all the installed synthesizers.
Vector synthInfos;
MidiDevice device;
MidiDevice.Info[] infos = MidiSystem.getMidiDeviceInfo();
for (int i = 0; i < infos.length; i++) {
    try {
        device = MidiSystem.getMidiDevice(infos[i]);
    } catch (MidiUnavailableException e) {
          // Handle or throw exception...
    }
    if (device instanceof Synthesizer) {
        synthInfos.add(infos[i]);
    }
}
// Now, display strings from synthInfos list in GUI.    

作为另一个示例，您可以以编程方式选择设备，而不涉及用户。假设您想获取可以同时播放最多音符的合成器。您遍历所有MidiDevice.Info对象，如上所述，但在确定设备是合成器后，通过调用Synthesizer的getMaxPolyphony方法查询其功能。您保留具有最大音色的合成器，如下一节所述。即使您不要求用户选择合成器，您可能仍然显示所选MidiDevice.Info对象的字符串，仅供用户参考。

打开设备

前一节展示了如何获取已安装的设备。然而，设备可能已安装但不可用。例如，另一个应用程序可能独占使用它。要为您的程序实际保留设备，您需要使用MidiDevice方法open：

if (!(device.isOpen())) {
    try {
      device.open();
  } catch (MidiUnavailableException e) {
          // Handle or throw exception...
  }
}

一旦您访问了设备并通过打开它来预留了它，您可能希望将其连接到一个或多个其他设备，以便让 MIDI 数据在它们之间流动。这个过程在传输和接收 MIDI 消息中有描述。

当完成对设备的操作后，通过调用MidiDevice的close方法释放它，以便其他程序可以使用。

传输和接收 MIDI 消息

原文：docs.oracle.com/javase/tutorial/sound/MIDI-messages.html

理解设备、发射器和接收器

Java Sound API 为 MIDI 数据指定了一种灵活且易于使用的消息路由架构，一旦理解其工作原理，就会变得灵活且易于使用。该系统基于模块连接设计：不同的模块，每个模块执行特定任务，可以相互连接（组网），使数据能够从一个模块流向另一个模块。

Java Sound API 的消息系统中的基本模块是MidiDevice接口。MidiDevices包括序列器（记录、播放、加载和编辑时间戳 MIDI 消息序列）、合成器（触发 MIDI 消息时生成声音）以及 MIDI 输入和输出端口，通过这些端口数据来自外部 MIDI 设备并传输到外部 MIDI 设备。通常所需的 MIDI 端口功能由基本的MidiDevice接口描述。Sequencer和Synthesizer接口扩展了MidiDevice接口，分别描述了 MIDI 序列器和合成器的附加功能。作为序列器或合成器的具体类应实现这些接口。

一个MidiDevice通常拥有一个或多个实现Receiver或Transmitter接口的辅助对象。这些接口代表连接设备的“插头”或“门户”，允许数据流入和流出。通过将一个MidiDevice的Transmitter连接到另一个MidiDevice的Receiver，可以创建一个模块网络，其中数据从一个模块流向另一个模块。

MidiDevice接口包括用于确定设备可以同时支持多少个发射器和接收器对象的方法，以及用于访问这些对象的其他方法。MIDI 输出端口通常至少有一个Receiver，通过该接收器可以接收传出消息；同样，合成器通常会响应发送到其Receiver或Receivers的消息。MIDI 输入端口通常至少有一个Transmitter，用于传播传入消息。功能齐全的序列器支持在录制过程中接收消息的Receivers和在播放过程中发送消息的Transmitters。

Transmitter接口包括用于设置和查询发射器发送其MidiMessages的接收器的方法。设置接收器建立了两者之间的连接。Receiver接口包含一个将MidiMessage发送到接收器的方法。通常，此方法由Transmitter调用。Transmitter和Receiver接口都包括一个close方法，用于释放先前连接的发射器或接收器，使其可用于不同的连接。

现在我们将讨论如何使用发射器和接收器。在涉及连接两个设备的典型情况之前（例如将一个音序器连接到合成器），我们将研究一个更简单的情况，即直接从应用程序向设备发送 MIDI 消息。研究这种简单的情况应该会更容易理解 Java Sound API 如何安排在两个设备之间发送 MIDI 消息。

发送消息到接收器而不使用发射器

假设你想从头开始创建一个 MIDI 消息，然后将其发送到某个接收器。你可以创建一个新的空白ShortMessage，然后使用以下ShortMessage方法填充它的 MIDI 数据：

void setMessage(int command, int channel, int data1,
         int data2) 

一旦您准备好发送消息，您可以使用这个Receiver方法将其发送到一个Receiver对象：

void send(MidiMessage message, long timeStamp)

时间戳参数将在稍后解释。现在，我们只会提到，如果您不关心指定精确时间，则其值可以设置为-1。在这种情况下，接收消息的设备将尽快响应消息。

应用程序可以通过调用设备的getReceiver方法来获取MidiDevice的接收器。如果设备无法向程序提供接收器（通常是因为设备的所有接收器已经在使用中），则会抛出MidiUnavailableException。否则，此方法返回的接收器可立即供程序使用。当程序使用完接收器后，应调用接收器的close方法。如果程序在调用close后尝试在接收器上调用方法，则可能会抛出IllegalStateException。

作为一个发送消息而不使用发射器的具体简单示例，让我们向默认接收器发送一个 Note On 消息，通常与设备（如 MIDI 输出端口或合成器）相关联。我们通过创建一个合适的ShortMessage并将其作为参数传递给Receiver的send方法来实现这一点：

  ShortMessage myMsg = new ShortMessage();
  // Start playing the note Middle C (60), 
  // moderately loud (velocity = 93).
  myMsg.setMessage(ShortMessage.NOTE_ON, 0, 60, 93);
  long timeStamp = -1;
  Receiver       rcvr = MidiSystem.getReceiver();
  rcvr.send(myMsg, timeStamp);

此代码使用ShortMessage的静态整数字段，即NOTE_ON，用作 MIDI 消息的状态字节。 MIDI 消息的其他部分作为参数给出了setMessage方法的显式数值。零表示音符将使用 MIDI 通道号 1 播放；60 表示中央 C 音符；93 是一个任意的按键按下速度值，通常表示最终播放音符的合成器应该以相当大的音量播放它。（MIDI 规范将速度的确切解释留给合成器对其当前乐器的实现。）然后将此 MIDI 消息以时间戳 -1 发送到接收器。现在我们需要仔细研究时间戳参数的确切含义，这是下一节的主题。

理解时间戳

正如您已经知道的，MIDI 规范有不同的部分。一部分描述了 MIDI "线"协议（实时设备之间发送的消息），另一部分描述了标准 MIDI 文件（作为"序列"中事件存储的消息）。在规范的后半部分，存储在标准 MIDI 文件中的每个事件都标记有指示何时播放该事件的时间值。相比之下，MIDI 传输协议中的消息总是应立即处理，一旦被设备接收，因此它们没有附带的时间值。

Java Sound API 添加了一个额外的变化。毫不奇怪，MidiEvent 对象中存在时间值，这些对象存储在序列中（可能是从 MIDI 文件中读取的），就像标准 MIDI 文件规范中一样。但是在 Java Sound API 中，甚至在设备之间发送的消息——换句话说，对应 MIDI 传输协议的消息——也可以被赋予时间值，称为时间戳。我们关心的是这些时间戳。

发送到设备的消息上的时间戳

Java Sound API 中在设备之间发送的消息上可选附带的时间戳与标准 MIDI 文件中的时间值有很大不同。 MIDI 文件中的时间值通常基于音乐概念，如拍子和速度，每个事件的时间度量了自上一个事件以来经过的时间。相比之下，发送到设备的Receiver对象的消息上的时间戳始终以微秒为单位测量绝对时间。具体来说，它测量了自拥有接收器的设备打开以来经过的微秒数。

这种时间戳旨在帮助补偿操作系统或应用程序引入的延迟。重要的是要意识到，这些时间戳用于对时间进行微小调整，而不是实现可以在完全任意时间安排事件的复杂队列（就像MidiEvent的时间值那样）。

发送到设备（通过Receiver）的消息上的时间戳可以为设备提供精确的时间信息。设备在处理消息时可能会使用这些信息。例如，它可能通过几毫秒来调整事件的时间以匹配时间戳中的信息。另一方面，并非所有设备都支持时间戳，因此设备可能会完全忽略消息的时间戳。

即使设备支持时间戳，也可能不会按照您请求的时间安排事件。您不能期望发送一个时间戳在未来很远处的消息，并让设备按照您的意图处理它，当然也不能期望设备正确安排一个时间戳在过去的消息！设备决定如何处理时间戳偏离太远或在过去的消息。发送方不知道设备认为什么是太远，或者设备是否对时间戳有任何问题。这种无知模仿了外部 MIDI 硬件设备的行为，它们发送消息而从不知道是否被正确接收。（MIDI 线协议是单向的。）

一些设备通过Transmitter发送带有时间戳的消息。例如，MIDI 输入端口发送的消息可能会标记上消息到达端口的时间。在某些系统中，事件处理机制会导致在对消息进行后续处理过程中丢失一定量的时间精度。消息的时间戳允许保留原始的时间信息。

要了解设备是否支持时间戳，请调用MidiDevice的以下方法：

    long getMicrosecondPosition()

如果设备忽略时间戳，则此方法返回-1。否则，它将返回设备当前的时间概念，您作为发送方可以在确定随后发送的消息的时间戳时使用它作为偏移量。例如，如果您想发送一个时间戳为未来五毫秒的消息，您可以获取设备当前的微秒位置，加上 5000 微秒，并将其用作时间戳。请记住，MidiDevice对时间的概念总是将时间零放在设备打开时的时间。

现在，有了时间戳的背景解释，让我们回到Receiver的send方法：

void send(MidiMessage message, long timeStamp)

timeStamp 参数以微秒为单位表示，根据接收设备对时间的概念。如果设备不支持时间戳，它会简单地忽略 timeStamp 参数。您不需要为发送给接收器的消息加时间戳。您可以使用 -1 作为 timeStamp 参数，表示您不关心调整确切的时间；您只是让接收设备尽快处理消息。然而，不建议在发送给同一接收器的某些消息中使用 -1，而在其他消息中使用显式时间戳。这样做可能会导致结果时间的不规则性。

连接发射器到接收器

我们已经看到您可以直接向接收器发送 MIDI 消息，而不使用发射器。现在让我们看看更常见的情况，即您不是从头开始创建 MIDI 消息，而是简单地连接设备在一起，以便其中一个可以向另一个发送 MIDI 消息。

连接到单个设备

我们将以连接序列器到合成器作为我们的第一个示例。一旦建立了这种连接，启动序列器将导致合成器从序列器当前序列中的事件生成音频。现在，我们将忽略将序列从 MIDI 文件加载到序列器中的过程。此外，我们不会涉及播放序列的机制。加载和播放序列在播放、录制和编辑 MIDI 序列中有详细讨论。加载乐器到合成器在合成声音中有讨论。现在，我们只关心如何连接序列器和合成器。这将作为连接一个设备的发射器到另一个设备的接收器的更一般过程的示例。

为简单起见，我们将使用默认的序列器和默认的合成器。

    Sequencer           seq;
    Transmitter         seqTrans;
    Synthesizer         synth;
    Receiver         synthRcvr;
    try {
          seq     = MidiSystem.getSequencer();
          seqTrans = seq.getTransmitter();
          synth   = MidiSystem.getSynthesizer();
          synthRcvr = synth.getReceiver(); 
          seqTrans.setReceiver(synthRcvr);      
    } catch (MidiUnavailableException e) {
          // handle or throw exception
    }

一个实现实际上可能有一个既是默认序列器又是默认合成器的单个对象。换句话说，实现可能使用一个同时实现 Sequencer 接口和 Synthesizer 接口的类。在这种情况下，可能不需要像上面的代码中所做的显式连接。但出于可移植性考虑，最好不要假设这样的配置。如果需要，当然可以测试这种情况：

if (seq instanceof Synthesizer)

尽管上面的显式连接应该在任何情况下都能工作。

连接到多个设备

前面的代码示例说明了发射器和接收器之间的一对一连接。但是，如果您需要将相同的 MIDI 消息发送到多个接收器怎么办？例如，假设您希望从外部设备捕获 MIDI 数据以驱动内部合成器，同时将数据录制到序列中。这种连接形式有时被称为“分流”或“分配器”，很简单。以下语句显示了如何创建一个分流连接，通过该连接，到达 MIDI 输入端口的 MIDI 消息被发送到一个Synthesizer对象和一个Sequencer对象。我们假设您已经获取并打开了三个设备：输入端口、序列器和合成器。（要获取输入端口，您需要遍历MidiSystem.getMidiDeviceInfo返回的所有项目。）

    Synthesizer  synth;
    Sequencer    seq;
    MidiDevice   inputPort;
    // [obtain and open the three devices...]
    Transmitter   inPortTrans1, inPortTrans2;
    Receiver            synthRcvr;
    Receiver            seqRcvr;
    try {
          inPortTrans1 = inputPort.getTransmitter();
          synthRcvr = synth.getReceiver(); 
          inPortTrans1.setReceiver(synthRcvr);
          inPortTrans2 = inputPort.getTransmitter();
          seqRcvr = seq.getReceiver(); 
          inPortTrans2.setReceiver(seqRcvr);
    } catch (MidiUnavailableException e) {
          // handle or throw exception
    }

此代码介绍了MidiDevice.getTransmitter方法的双重调用，将结果分配给inPortTrans1和inPortTrans2。如前所述，设备可以拥有多个发射器和接收器。每次为给定设备调用MidiDevice.getTransmitter()时，都会返回另一个发射器，直到没有更多可用为止，此时将抛出异常。

要了解设备支持多少个发射器和接收器，您可以使用以下MidiDevice方法：

    int getMaxTransmitters()
    int getMaxReceivers()

这些方法返回设备拥有的总数，而不是当前可用的数量。

发射器一次只能向一个接收器传输 MIDI 消息。（每次调用Transmitter的setReceiver方法时，如果存在现有的Receiver，则会被新指定的替换。您可以通过调用Transmitter.getReceiver来判断发射器当前是否有接收器。）但是，如果设备有多个发射器，它可以同时向多个设备发送数据，通过将每个发射器连接到不同的接收器，就像我们在上面的输入端口的情况中看到的那样。

同样，设备可以使用其多个接收器同时从多个设备接收。所需的多接收器代码很简单，直接类似于上面的多发射器代码。一个单一接收器也可以同时从多个发射器接收消息。

关闭连接

一旦完成连接，您可以通过调用每个已获取的发射器和接收器的close方法来释放其资源。Transmitter和Receiver接口各自都有一个close方法。请注意，调用Transmitter.setReceiver不会关闭发射器当前的接收器。接收器保持打开状态，仍然可以接收来自任何连接到它的其他发射器的消息。

如果您也完成了设备的使用，可以通过调用MidiDevice.close()将它们提供给其他应用程序。关闭设备会自动关闭其所有发射器和接收器。

介绍 Sequencers

原文：docs.oracle.com/javase/tutorial/sound/MIDI-seq-intro.html

在 MIDI 世界中，sequencer是任何能精确播放或记录一系列时间戳 MIDI 消息的硬件或软件设备。同样，在 Java Sound API 中，Sequencer抽象接口定义了可以播放和记录MidiEvent对象序列的对象的属性。Sequencer通常从标准 MIDI 文件加载这些MidiEvent序列或将它们保存到这样的文件中。序列也可以进行编辑。以下页面解释了如何使用Sequencer对象以及相关的类和接口来完成这些任务。

要对Sequencer是什么有直观的理解，可以将其类比为磁带录音机，在许多方面Sequencer与磁带录音机相似。磁带录音机播放音频，而Sequencer播放 MIDI 数据。一个序列是多轨、线性、按时间顺序记录的 MIDI 音乐数据，Sequencer可以以不同速度播放，倒带，定位到特定点，录制或复制到文件进行存储。

传输和接收 MIDI 消息解释了设备通常具有Receiver对象、Transmitter对象或两者。为了播放音乐，设备通常通过Receiver接收MidiMessages，而Receiver通常是从属于Sequencer的Transmitter接收这些消息。拥有这个Receiver的设备可能是一个Synthesizer，它将直接生成音频，或者可能是一个 MIDI 输出端口，通过物理电缆将 MIDI 数据传输到外部设备。类似地，为了录制音乐，一系列带有时间戳的MidiMessages通常被发送到Sequencer拥有的Receiver中，然后将它们放入Sequence对象中。通常发送消息的对象是与硬件输入端口相关联的Transmitter，端口通过物理电缆中继从外部设备获取的 MIDI 数据。然而，负责发送消息的设备可能是其他Sequencer，或者任何具有Transmitter的设备。此外，如前所述，程序可以在完全不使用任何Transmitter的情况下发送消息。

一个Sequencer本身既有Receivers又有Transmitters。在录制时，它实际上通过其Receivers获取MidiMessages。在播放时，它使用其Transmitters发送存储在其记录的Sequence中的MidiMessages（或从文件中加载）。

在 Java Sound API 中，将Sequencer的角色视为MidiMessages的聚合器和“解聚器”的一种方式。一系列独立的MidiMessages被发送到Sequencer，每个MidiMessages都有自己的时间戳，标记了音乐事件的时间。这些MidiMessages被封装在MidiEvent对象中，并通过Sequencer.record方法在Sequence对象中收集。Sequence是一个包含MidiEvents聚合的数据结构，通常代表一系列音符，通常是整首歌曲或作品。在播放时，Sequencer再次从Sequence中的MidiEvent对象中提取MidiMessages，然后将它们传输到一个或多个设备，这些设备将把它们渲染成声音，保存它们，修改它们，或将它们传递给其他设备。

一些音序器可能既没有发射器也没有接收器。例如，它们可能会根据键盘或鼠标事件从头开始创建MidiEvents，而不是通过Receivers接收MidiMessages。同样，它们可能通过直接与内部合成器（实际上可能是与音序器相同的对象）通信来演奏音乐，而不是将MidiMessages发送到与另一个对象关联的Receiver。

何时使用音序器

应用程序可以直接向设备发送 MIDI 消息，而不使用音序器，就像在传输和接收 MIDI 消息中描述的那样。程序只需在想要发送消息时调用Receiver.send方法。这是一种直接的方法，当程序本身实时创建消息时非常有用。例如，考虑一个程序，让用户通过点击屏幕上的钢琴键盘来演奏音符。当程序接收到鼠标按下事件时，立即向合成器发送适当的 Note On 消息。

如前所述，程序可以在发送到设备的接收器的每个 MIDI 消息中包含时间戳。然而，这些时间戳仅用于微调时间，以纠正处理延迟。调用者通常不能设置任意时间戳；传递给Receiver.send的时间值必须接近当前时间，否则接收设备可能无法正确安排消息。这意味着，如果应用程序想要提前为整首音乐创建一个 MIDI 消息队列（而不是对实时事件做出响应时创建每个消息），它必须非常小心地安排每次调用Receiver.send几乎正确的时间。

幸运的是，大多数应用程序不必担心这种调度问题。程序可以使用Sequencer对象来管理 MIDI 消息队列，而不是自己调用Receiver.send。Sequencer负责调度和发送消息，换句话说，以正确的时间播放音乐。通常，在需要将非实时 MIDI 消息序列转换为实时序列（如播放）或反之（如录制）时，使用Sequencer是有利的。Sequencer最常用于播放来自 MIDI 文件的数据和从 MIDI 输入端口录制数据。

理解序列数据

在查看SequencerAPI 之前，了解存储在序列中的数据类型是有帮助的。

序列和轨道

在 Java Sound API 中，Sequencer在组织记录的 MIDI 数据方面紧密遵循标准 MIDI 文件规范。如上所述，Sequence是按时间组织的MidiEvents的聚合。但Sequence比仅仅是线性MidiEvents序列更具结构：Sequence实际上包含全局时间信息以及一组Tracks，而Tracks本身保存MidiEvent数据。因此，由Sequencer播放的数据由三级对象层次结构组成：Sequencer，Track和MidiEvent。

在这些对象的常规使用中，Sequence代表完整的音乐作品或作品的一部分，每个Track对应于合奏中的一个声音或演奏者。在这个模型中，特定Track上的所有数据也因此被编码到为该声音或演奏者保留的特定 MIDI 通道中。

这种数据组织方式便于编辑序列，但请注意，这只是一种使用Tracks的常规方式。Track类的定义中没有任何限制它只能包含不同 MIDI 通道上的MidiEvents的内容。例如，整个多通道 MIDI 作品可以混合录制到一个Track上。此外，Type 0 标准 MIDI 文件（与 Type 1 和 Type 2 相对）根据定义只包含一个轨道；因此，从这样的文件中读取的Sequence必然只有一个Track对象。

MidiEvents 和 Ticks

如 Java Sound API 概述中所讨论的，Java Sound API 包括与组成大多数标准 MIDI 消息的原始两个或三字节序列对应的MidiMessage对象。MidiEvent只是一个MidiMessage的打包，以及指定事件发生时间的伴随时间值。（我们可能会说序列实际上包含四或五级数据层次，而不是三级，因为表面上最低级别的MidiEvent实际上包含一个更低级别的MidiMessage，同样MidiMessage对象包含一个组成标准 MIDI 消息的字节数组。）

在 Java Sound API 中，MidiMessages可以与定时值关联的另一种方式有两种。 其中一种是上面提到的“何时使用 Sequencer”。 这种技术在不使用 Transmitter 向接收器发送消息和理解时间戳下有详细描述。 在那里，我们看到Receiver的send方法接受一个MidiMessage参数和一个时间戳参数。 那种时间戳只能用微秒表示。

MidiMessage可以指定其定时的另一种方式是通过封装在MidiEvent中。 在这种情况下，定时以稍微更抽象的单位称为ticks来表示。

一个 tick 的持续时间是多少？ 它可以在序列之间变化（但不会在序列内部变化），其值存储在标准 MIDI 文件的头部中。 一个 tick 的大小以两种类型的单位给出：

• 每四分音符的脉冲（ticks），缩写为 PPQ

• 每帧的 ticks，也称为 SMPTE 时间码（由电影和电视工程师协会采用的标准）

如果单位是 PPQ，一个 tick 的大小被表示为四分音符的一部分，这是一个相对的，而不是绝对的时间值。 四分音符是一个音乐持续时间值，通常对应于音乐中的一个节拍（4/4 拍子中的四分之一）。 四分音符的持续时间取决于速度，如果序列包含速度变化事件，则音乐中的四分音符的持续时间可能会在音乐过程中变化。 因此，如果序列的定时增量（ticks）发生，比如每四分音符发生 96 次，那么每个事件的定时值都以音乐术语来衡量该事件的位置，而不是绝对时间值。

另一方面，在 SMPTE 的情况下，单位度量绝对时间，而速度的概念不适用。 实际上有四种不同的 SMPTE 约定可用，它们指的是每秒的电影帧数。 每秒的帧数可以是 24、25、29.97 或 30。 使用 SMPTE 时间码，一个 tick 的大小被表示为帧的一部分。

在 Java Sound API 中，您可以调用Sequence.getDivisionType来了解特定序列中使用的单位类型，即 PPQ 或 SMPTE 单位之一。 然后在调用Sequence.getResolution之后可以计算一个 tick 的大小。 如果分割类型是 PPQ，则后一种方法返回每四分音符的 ticks 数，或者如果分割类型是 SMPTE 约定之一，则返回每个 SMPTE 帧的 ticks 数。 在 PPQ 的情况下，可以使用以下公式来获取一个 tick 的大小：

ticksPerSecond =  
    resolution * (currentTempoInBeatsPerMinute / 60.0);
tickSize = 1.0 / ticksPerSecond;

以及在 SMPTE 的情况下的这个公式：

framesPerSecond = 
  (divisionType == Sequence.SMPTE_24 ? 24
    : (divisionType == Sequence.SMPTE_25 ? 25
      : (divisionType == Sequence.SMPTE_30 ? 30
        : (divisionType == Sequence.SMPTE_30DROP ?

            29.97))));
ticksPerSecond = resolution * framesPerSecond;
tickSize = 1.0 / ticksPerSecond;

Java Sound API 中对序列中时间的定义与标准 MIDI 文件规范相似。然而，有一个重要的区别。MidiEvents中包含的 tick 值衡量的是累积时间，而不是增量时间。在标准 MIDI 文件中，每个事件的时间信息衡量的是自上一个事件开始以来经过的时间。这被称为增量时间。但在 Java Sound API 中，ticks 不是增量值；它们是前一个事件的时间值加上增量值。换句话说，在 Java Sound API 中，每个事件的时间值始终大于序列中前一个事件的时间值（或者相等，如果事件应该同时发生）。每个事件的时间值衡量的是自序列开始以来经过的时间。

总结一下，Java Sound API 以 MIDI ticks 或微秒表示时间信息。MidiEvents以 MIDI ticks 形式存储时间信息。一个 tick 的持续时间可以从Sequence的全局时间信息以及（如果序列使用基于速度的时间）当前的音乐速度计算出来。另一方面，发送给Receiver的MidiMessage的时间戳总是以微秒表示。

这种设计的一个目标是避免时间概念的冲突。Sequencer的工作是解释其MidiEvents中的时间单位，这些单位可能是 PPQ 单位，并将其转换为以微秒为单位的绝对时间，考虑到当前的速度。序列器还必须相对于接收消息的设备打开时的时间表达微秒。请注意，一个序列器可以有多个发射器，每个发射器将消息传递给一个可能与完全不同设备关联的不同接收器。因此，您可以看到，序列器必须能够同时执行多个转换，确保每个设备接收适合其时间概念的时间戳。

更复杂的是，不同设备可能基于不同来源（如操作系统的时钟或声卡维护的时钟）更新其时间概念。这意味着它们的时间可能相对于序列器的时间会有偏移。为了与序列器保持同步，一些设备允许自己成为序列器时间概念的“从属”。设置主从关系将在稍后的MidiEvent中讨论。

使用Sequencer方法

原文：docs.oracle.com/javase/tutorial/sound/MIDI-seq-methods.html

Sequencer接口提供了几个类别的方法：

• 从 MIDI 文件或Sequence对象加载序列数据，并将当前加载的序列数据保存到 MIDI 文件。

• 类似于磁带录音机的传输功能的方法，用于停止和开始播放和录制，启用和禁用特定轨道上的录制，并在Sequence中快进/快退当前播放或录制位置。

• 高级方法用于查询和设置对象的同步和定时参数。Sequencer可以以不同的速度播放，一些Tracks静音，并且与其他对象处于各种同步状态。

• 高级方法用于注册“监听器”对象，当Sequencer处理某些类型的 MIDI 事件时通知它们。

无论您将调用哪些Sequencer方法，第一步都是从系统获取Sequencer设备并为程序使用保留它。

获取一个Sequencer

应用程序不会实例化Sequencer；毕竟，Sequencer只是一个接口。相反，像 Java Sound API 的 MIDI 包中的所有设备一样，Sequencer通过静态的MidiSystem对象访问。如前面在访问 MIDI 系统资源中提到的，可以使用以下MidiSystem方法获取默认的Sequencer：

static Sequencer getSequencer()

以下代码片段获取默认的Sequencer，获取其所需的任何系统资源，并使其可操作：

Sequencer sequencer;
// Get default sequencer.
sequencer = MidiSystem.getSequencer(); 
if (sequencer == null) {
    // Error -- sequencer device is not supported.
    // Inform user and return...
} else {
    // Acquire resources and make operational.
    sequencer.open();
}

调用open保留了Sequencer设备供程序使用。想象共享一个Sequencer并没有太多意义，因为它一次只能播放一个序列。当使用完Sequencer后，可以通过调用close使其可供其他程序使用。

可以按照访问 MIDI 系统资源中描述的方式获取非默认的Sequencer。

加载一个序列

从系统获取并保留了一个Sequencer后，您需要加载Sequencer应该播放的数据。有三种典型的方法可以实现这一点：

• 从 MIDI 文件中读取序列数据

• 通过从另一个设备（如 MIDI 输入端口）接收 MIDI 消息实时录制

• 通过向空序列添加轨道和向这些轨道添加MidiEvent对象来以编程方式构建它

现在我们将看一下获取序列数据的这种方式中的第一种。 （其他两种方式分别在录制和保存序列和编辑序列下描述。）这种方式实际上包括两种略有不同的方法。一种方法是将 MIDI 文件数据提供给InputStream，然后通过Sequencer.setSequence(InputStream)直接将其读取到sequencer中。使用此方法，您不需要显式创建Sequence对象。实际上，Sequencer实现甚至可能不会在幕后创建Sequence，因为一些sequencers具有处理直接从文件中处理数据的内置机制。

另一种方法是显式创建Sequence。如果要在播放之前编辑序列数据，则需要使用此方法。使用此方法，您调用MidiSystem的重载方法getSequence。该方法能够从InputStream、File或URL获取序列。该方法返回一个Sequence对象，然后可以将其加载到Sequencer中进行播放。在上面的代码摘录中，这是一个从File获取Sequence对象并将其加载到我们的sequencer的示例：

try {
    File myMidiFile = new File("seq1.mid");
    // Construct a Sequence object, and
    // load it into my sequencer.
    Sequence mySeq = MidiSystem.getSequence(myMidiFile);
    sequencer.setSequence(mySeq);
} catch (Exception e) {
   // Handle error and/or return
}

与MidiSystem的getSequence方法一样，setSequence可能会抛出InvalidMidiDataException，在InputStream变体的情况下，还可能会抛出IOException，如果遇到任何问题。

播放一个序列

使用以下方法可以启动和停止Sequencer：

    void start()

和

    void stop()

Sequencer.start方法开始播放序列。请注意，播放从序列中的当前位置开始。使用上面描述的setSequence方法加载现有序列会将sequencer的当前位置初始化为序列的开头。stop方法停止sequencer，但不会自动倒带当前Sequence。在不重置位置的情况下启动已停止的Sequence只是从当前位置恢复播放序列。在这种情况下，stop方法充当了暂停操作。但是，在开始播放之前，有各种Sequencer方法可将当前序列位置设置为任意值。（我们将在下面讨论这些方法。）

正如前面提到的，Sequencer通常具有一个或多个Transmitter对象，通过这些对象向Receiver发送MidiMessages。通过这些Transmitters，Sequencer播放Sequence，通过发出与当前Sequence中包含的MidiEvents相对应的适时MidiMessages。因此，播放Sequence的设置过程的一部分是在Sequencer的Transmitter对象上调用setReceiver方法，实际上将其输出连接到将使用播放数据的设备。有关Transmitters和Receivers的更多详细信息，请参考传输和接收 MIDI 消息。

录制和保存序列

要将 MIDI 数据捕获到Sequence，然后保存到文件，需要执行一些除上述描述之外的额外步骤。以下概述显示了设置录制到Sequence中的Track所需的步骤：

1. 使用MidiSystem.getSequencer获取一个新的用于录制的序列器，如上所述。

2. 设置 MIDI 连接的“连线”。传输要录制的 MIDI 数据的对象应通过其setReceiver方法配置，以将数据发送到与录制Sequencer相关联的Receiver。

3. 创建一个新的Sequence对象，用于存储录制的数据。创建Sequence对象时，必须为序列指定全局时间信息。例如：

         Sequence mySeq;
         try{
             mySeq = new Sequence(Sequence.PPQ, 10);
         } catch (Exception ex) { 
             ex.printStackTrace(); 
         }
   
   

   Sequence的构造函数接受divisionType和时间分辨率作为参数。divisionType参数指定分辨率参数的单位。在这种情况下，我们指定正在创建的Sequence的时间分辨率为每四分音符 10 脉冲。Sequence构造函数的另一个可选参数是轨道数参数，这将导致初始序列以指定数量的（最初为空）Tracks开始。否则，Sequence将创建为没有初始Tracks；它们可以根据需要随后添加。

4. 在Sequence中创建一个空的Track，使用Sequence.createTrack。如果Sequence是使用初始Tracks创建的，则此步骤是不必要的。

5. 使用Sequencer.setSequence，选择我们的新Sequence来接收录制。setSequence方法将现有的Sequence与Sequencer绑定，这在某种程度上类似于将磁带加载到磁带录音机上。

6. 对于每个要录制的Track，调用Sequencer.recordEnable。如果需要，在Sequence中通过调用Sequence.getTracks获取可用的Tracks的引用。

7. 在Sequencer上调用startRecording。

8. 完成录制后，调用Sequencer.stop或Sequencer.stopRecording。

9. 使用MidiSystem.write将录制的Sequence保存到 MIDI 文件中。MidiSystem的write方法将Sequence作为其参数之一，并将该Sequence写入流或文件。

编辑序列

许多应用程序允许通过从文件加载来创建序列，并且有相当多的应用程序也允许通过从实时 MIDI 输入（即录制）捕获来创建序列。然而，一些程序将需要从头开始创建 MIDI 序列，无论是以编程方式还是响应用户输入。功能齐全的序列程序允许用户手动构建新序列，以及编辑现有序列。

在 Java Sound API 中，这些数据编辑操作不是通过Sequencer方法实现的，而是通过数据对象本身的方法实现：Sequence、Track和MidiEvent。你可以使用Sequence构造函数之一创建一个空序列，然后通过调用以下Sequence方法向其添加轨道：

    Track createTrack() 

如果你的程序允许用户编辑序列，你将需要这个Sequence方法来移除轨道：

    boolean deleteTrack(Track track) 

一旦序列包含轨道，你可以通过调用Track类的方法来修改轨道的内容。Track中包含的MidiEvents以java.util.Vector的形式存储在Track对象中，而Track提供了一组方法来访问、添加和移除列表中的事件。add和remove方法相当直观，用于向Track中添加或移除指定的MidiEvent。提供了一个get方法，它接受一个索引，返回存储在那里的MidiEvent。此外，还有size和tick方法，分别返回轨道中的MidiEvents数量和轨道的持续时间，以总Ticks数表示。

在将事件添加到轨道之前创建新事件时，当然会使用MidiEvent构造函数。要指定或修改嵌入在事件中的 MIDI 消息，可以调用适当的MidiMessage子类（ShortMessage、SysexMessage或MetaMessage）的setMessage方法。要修改事件应发生的时间，调用MidiEvent.setTick。

综合起来，这些低级方法为完整功能的音序器程序所需的编辑功能提供了基础。

使用高级音序器功能

译文：docs.oracle.com/javase/tutorial/sound/MIDI-seq-adv.html

到目前为止，我们专注于简单的 MIDI 数据播放和录制。本节将简要描述通过Sequencer接口和Sequence类的方法可用的一些更高级功能。

移动到序列中的任意位置

有两个Sequencer方法可以获取序列中音序器的当前位置。其中的第一个：

long getTickPosition()

返回从序列开始测量的 MIDI 滴答位置。第二种方法：

long getMicrosecondPosition()

返回当前位置的微秒数。此方法假定序列以存储在 MIDI 文件或Sequence中的默认速率播放。如果您按照下面描述的方式更改了播放速度，则它不会返回不同的值。

您也可以根据一个单位或另一个单位设置音序器的当前位置：

void setTickPosition(long tick)

或

void setMicrosecondPosition(long microsecond)

更改播放速度

如前所述，序列的速度由其速度确定，可以在序列的过程中变化。序列可以包含封装标准 MIDI 速度变化消息的事件。当音序器处理此类事件时，它会根据指定的速度更改播放速度。此外，您可以通过调用任何这些Sequencer方法来以编程方式更改速度：

    public void setTempoInBPM(float bpm)
    public void setTempoInMPQ(float mpq)
    public void setTempoFactor(float factor)

这些方法中的前两种分别设置每分钟的节拍数或每个四分音符的微秒数的速度。速度将保持在指定值，直到再次调用其中一种方法，或者在序列中遇到速度变化事件，此时当前速度将被新指定的速度覆盖。

第三种方法，setTempoFactor，性质不同。它会按比例缩放音序器设置的任何速度（无论是通过速度变化事件还是通过上述前两种方法之一）。默认比例为 1.0（无变化）。尽管此方法会导致播放或录制速度比标称速度快或慢（除非因子为 1.0），但不会改变标称速度。换句话说，getTempoInBPM和getTempoInMPQ返回的速度值不受速度因子影响，尽管速度因子会影响实际播放或录制速率。此外，如果速度通过速度变化事件或前两种方法之一更改，它仍会按上次设置的速度因子进行缩放。但是，如果加载新序列，则速度因子将重置为 1.0。

请注意，当序列的分割类型为 SMPTE 类型之一而不是 PPQ 时，所有这些速度变化指令都无效。

静音或独奏序列中的单独轨道

对于音序器的用户来说，通常可以方便地关闭某些轨道，以更清楚地听到音乐中发生的情况。一个功能齐全的音序器程序允许用户在播放过程中选择哪些轨道应该发声。（更准确地说，由于音序器实际上不会自己发声，用户选择哪些轨道将为音序器产生的 MIDI 消息流做出贡献。）通常，每个轨道上都有两种类型的图形控件：一个静音按钮和一个独奏按钮。如果激活了静音按钮，那个轨道在任何情况下都不会发声，直到静音按钮被停用。独奏是一个不太为人知的功能。它大致相当于静音的反义词。如果任何轨道上的独奏按钮被激活，只有那些独奏按钮被激活的轨道才会发声。这个功能让用户可以快速试听少量轨道，而无需将所有其他轨道静音。静音按钮通常优先于独奏按钮：如果两者都被激活，那个轨道不会发声。

使用Sequencer方法，静音或独奏轨道（以及查询轨道当前的静音或独奏状态）是很容易实现的。假设我们已经获得了默认的Sequencer并且已经将序列数据加载到其中。要静音序列中的第五个轨道，可以按照以下步骤进行：

    sequencer.setTrackMute(4, true);
    boolean muted = sequencer.getTrackMute(4);
    if (!muted) { 
        return;         // muting failed
    }

有几点需要注意上面的代码片段。首先，序列的轨道编号从 0 开始，以总轨道数减 1 结束。此外，setTrackMute的第二个参数是一个布尔值。如果为 true，则请求是将轨道静音；否则请求是取消静音指定的轨道。最后，为了测试静音是否生效，我们调用Sequencer getTrackMute方法，将要查询的轨道号传递给它。如果它返回true，正如我们在这种情况下所期望的那样，那么静音请求成功。如果返回false，则请求失败。

静音请求可能因各种原因而失败。例如，setTrackMute调用中指定的轨道号可能超过了总轨道数，或者音序器可能不支持静音。通过调用getTrackMute，我们可以确定我们的请求是成功还是失败。

顺便说一句，getTrackMute返回的布尔值确实可以告诉我们是否发生了失败，但它无法告诉我们失败的原因。我们可以测试看看失败是否是由于将无效的轨道号传递给setTrackMute方法引起的。为此，我们可以调用Sequence的getTracks方法，该方法返回一个包含序列中所有轨道的数组。如果在setTrackMute调用中指定的轨道号超过了此数组的长度，则我们知道我们指定了一个无效的轨道号。

如果静音请求成功，那么在我们的示例中，当序列播放时第五个轨道将不会发声，当前静音的任何其他轨道也不会发声。

独奏轨道的方法和技巧与静音非常相似。要独奏一个轨道，调用Sequence的setTrackSolo方法：

void setTrackSolo(int track, boolean bSolo)

与setTrackMute相同，第一个参数指定基于零的轨道编号，第二个参数如果为true，则指定该轨道应处于独奏模式；否则该轨道不应处于独奏状态。

默认情况下，轨道既不静音也不独奏。

与其他 MIDI 设备同步

Sequencer有一个名为Sequencer.SyncMode的内部类。SyncMode对象代表 MIDI 序列器的时间概念如何与主设备或从设备同步的一种方式。如果序列器正在与主设备同步，序列器会根据来自主设备的某些 MIDI 消息调整其当前时间。如果序列器有一个从设备，序列器同样会发送 MIDI 消息来控制从设备的定时。

有三种预定义模式指定了序列器可能的主设备：INTERNAL_CLOCK、MIDI_SYNC和MIDI_TIME_CODE。后两种模式在序列器接收来自另一设备的 MIDI 消息时起作用。在这两种模式下，序列器的时间会根据系统实时定时时钟消息或 MIDI 时间码（MTC）消息进行重置。 （有关这些消息类型的更多信息，请参阅 MIDI 规范。）这两种模式也可以用作从模式，此时序列器会向其接收器发送相应类型的 MIDI 消息。第四种模式NO_SYNC用于指示序列器不应向其接收器发送定时信息。

通过调用带有支持的SyncMode对象作为参数的setMasterSyncMode方法，您可以指定序列器的定时如何受控。同样，setSlaveSyncMode方法确定序列器将向其接收器发送哪些定时信息。这些信息控制使用序列器作为主定时源的设备的定时。

指定特殊事件监听器

序列的每个轨道可以包含许多不同类型的MidiEvents。这些事件包括音符开和音符关消息、程序更改、控制更改和元事件。Java Sound API 为最后两种事件类型（控制更改事件和元事件）指定了“监听器”接口。您可以使用这些接口在播放序列时接收这些事件发生时的通知。

支持ControllerEventListener接口的对象可以在Sequencer处理特定控制变化消息时接收通知。控制变化消息是一种标准的 MIDI 消息类型，代表了 MIDI 控制器值的变化，比如音高弯曲轮或数据滑块。 （请参阅 MIDI 规范获取控制变化消息的完整列表。）当在序列播放过程中处理这样的消息时，消息指示任何设备（可能是合成器）从序列器接收数据以更新某些参数的值。该参数通常控制声音合成的某些方面，比如如果控制器是音高弯曲轮，则控制当前发声音符的音高。当录制序列时，控制变化消息意味着在创建消息的外部物理设备上移动了一个控制器，或者在软件中模拟了这样的移动。

这里是ControllerEventListener接口的使用方法。假设你已经开发了一个实现ControllerEventListener接口的类，意味着你的类包含以下方法：

    void controlChange(ShortMessage msg)

假设你已经创建了一个类的实例，并将其赋给一个名为myListener的变量。如果你在程序的某个地方包含以下语句：

    int[] controllersOfInterest = { 1, 2, 4 };
    sequencer.addControllerEventListener(myListener,
        controllersOfInterest);

那么你的类的controlChange方法将在Sequencer处理 MIDI 控制器编号为 1、2 或 4 的控制变化消息时被调用。换句话说，当Sequencer处理设置任何已注册控制器的值的请求时，Sequencer将调用你的类的controlChange方法。（请注意，将 MIDI 控制器编号分配给特定控制设备的详细信息在 MIDI 1.0 规范中有详细说明。）

controlChange方法接收一个包含受影响的控制器编号和控制器设置的新值的ShortMessage。你可以使用ShortMessage.getData1方法获取控制器编号，并使用ShortMessage.getData2方法获取控制器值的新设置。

另一种特殊事件监听器的类型由MetaEventListener接口定义。根据标准 MIDI 文件 1.0 规范，元消息是不在 MIDI 线协议中存在但可以嵌入到 MIDI 文件中的消息。它们对合成器没有意义，但可以被序列器解释。元消息包括指令（如变速命令）、歌词或其他文本以及其他指示（如音轨结束）。

MetaEventListener机制类似于ControllerEventListener。在任何需要在Sequencer处理MetaMessage时收到通知的类中实现MetaEventListener接口。这涉及向类中添加以下方法：

void meta(MetaMessage msg)

通过将此类的实例作为参数传递给Sequencer addMetaEventListener方法来注册该类的实例：

boolean b = sequencer.addMetaEventListener
        (myMetaListener);

这与ControllerEventListener接口所采取的方法略有不同，因为您必须注册以接收所有MetaMessages，而不仅仅是感兴趣的部分。如果顺序器在其序列中遇到MetaMessage，它将调用myMetaListener.meta，并将遇到的MetaMessage传递给它。meta方法可以调用其MetaMessage参数上的getType，以获取一个从 0 到 127 的整数，该整数表示消息类型，如标准 MIDI 文件 1.0 规范所定义。

合成声音

原文：docs.oracle.com/javase/tutorial/sound/MIDI-synth.html

大多数使用 Java Sound API 的 MIDI 包的程序都是用来合成声音。之前讨论过的整个 MIDI 文件、事件、序列和序列器的装置几乎总是最终将音乐数据发送到合成器以转换为音频。（可能的例外包括将 MIDI 转换为音乐符号的程序，可以被音乐家阅读，以及向外部 MIDI 控制设备发送消息的程序，如混音台。）

因此，Synthesizer接口对于 MIDI 包至关重要。本页展示了如何操作合成器播放声音。许多程序将简单地使用序列器将 MIDI 文件数据发送到合成器，并且不需要直接调用许多Synthesizer方法。然而，也可以直接控制合成器，而不使用序列器甚至MidiMessage对象，如本页末尾所述。

对于不熟悉 MIDI 的读者来说，合成架构可能看起来很复杂。其 API 包括三个接口：

• 合成器

• Midi 通道

• 声音库

和四个类：

• 乐器

• 补丁

• 声音库资源

• VoiceStatus

作为对所有这些 API 的定位，下一节解释了一些 MIDI 合成的基础知识以及它们如何在 Java Sound API 中反映。随后的部分将更详细地查看 API。

理解 MIDI 合成

合成器是如何产生声音的？根据其实现方式，它可能使用一种或多种声音合成技术。例如，许多合成器使用波表合成。波表合成器从内存中读取存储的音频片段，以不同的采样率播放它们，并循环播放它们以创建不同音高和持续时间的音符。例如，要合成萨克斯风演奏 C#4 音符（MIDI 音符号 61）的声音，合成器可能会访问从萨克斯风演奏中音符中央 C（MIDI 音符号 60）的录音中提取的一个非常短的片段，然后以比录制时略快的采样率不断循环播放这个片段，从而创建一个略高音高的长音符。其他合成器使用诸如频率调制（FM）、加法合成或物理建模等技术，这些技术不使用存储的音频，而是使用不同的算法从头开始生成音频。

乐器

所有合成技术共同之处在于能够创造许多种声音。不同的算法，或者同一算法内不同参数的设置，会产生不同的声音结果。一个乐器是合成某种类型声音的规范。该声音可能模拟传统乐器，如钢琴或小提琴；也可能模拟其他类型的声源，例如电话或直升机；或者根本不模拟任何“现实世界”的声音。一个名为通用 MIDI 的规范定义了一个标准的 128 种乐器列表，但大多数合成器也允许使用其他乐器。许多合成器提供一系列内置乐器，始终可供使用；一些合成器还支持加载额外乐器的机制。

一个乐器可能是特定供应商的——换句话说，仅适用于一个合成器或同一供应商的几个型号。当两个不同的合成器使用不同的声音合成技术，或者即使基本技术相同，但使用不同的内部算法和参数时，就会出现不兼容性。由于合成技术的细节通常是专有的，因此不兼容性是常见的。Java Sound API 包括检测给定合成器是否支持给定乐器的方法。

一个乐器通常可以被视为一个预设；你不必了解产生其声音的合成技术的细节。然而，你仍然可以改变其声音的各个方面。每个 Note On 消息指定一个单独音符的音高和音量。你还可以通过其他 MIDI 命令如控制器消息或系统专用消息来改变声音。

通道

许多合成器是多音轨（有时称为多音色），意味着它们可以同时演奏不同乐器的音符。 (音色是使听众能够区分一种乐器与其他乐器的特征音质。) 多音轨合成器可以模拟整个真实乐器的合奏，而不仅仅是一次一个乐器。 MIDI 合成器通常通过利用 MIDI 规范允许数据传输的不同 MIDI 通道来实现此功能。在这种情况下，合成器实际上是一组发声单元，每个单元模拟不同的乐器，并独立响应在不同 MIDI 通道上接收到的消息。由于 MIDI 规范仅提供 16 个通道，典型的 MIDI 合成器可以同时演奏多达 16 种不同的乐器。合成器接收一系列 MIDI 命令，其中许多是通道命令。 (通道命令针对特定的 MIDI 通道；有关更多信息，请参阅 MIDI 规范。) 如果合成器是多音轨的，它会根据命令中指示的通道号将每个通道命令路由到正确的发声单元。

在 Java Sound API 中，这些发声单元是实现MidiChannel接口的类的实例。一个synthesizer对象至少有一个MidiChannel对象。如果合成器是多音轨的，通常有多个，通常是 16 个。每个MidiChannel代表一个独立的发声单元。

因为合成器的MidiChannel对象更多或更少是独立的，将乐器分配给通道不必是唯一的。例如，所有 16 个通道都可以演奏钢琴音色，就好像有一个由 16 台钢琴组成的合奏团。任何分组都是可能的—例如，通道 1、5 和 8 可以演奏吉他声音，而通道 2 和 3 演奏打击乐，通道 12 有低音音色。在给定的 MIDI 通道上演奏的乐器可以动态更改；这被称为程序更改。

尽管大多数合成器一次只能激活 16 个或更少的乐器，但这些乐器通常可以从更大的选择中选择，并根据需要分配到特定的通道。

声音库和音色

在合成器中，乐器按照银行号和程序号进行层次化组织。银行和程序可以被视为乐器的二维表中的行和列。一个银行是一个程序的集合。 MIDI 规范允许一个银行中最多有 128 个程序，最多有 128 个银行。然而，特定的合成器可能仅支持一个银行，或几个银行，并且可能支持每个银行少于 128 个程序。

在 Java Sound API 中，层次结构中有一个更高级别的部分：声音库。声音库可以包含多达 128 个银行，每个银行包含多达 128 个乐器。一些合成器可以将整个声音库加载到内存中。

要从当前声音库中选择一个乐器，您需要指定一个银行号和一个程序号。MIDI 规范通过两个 MIDI 命令实现了这一点：银行选择和程序更改。在 Java Sound API 中，银行号和程序号的组合封装在一个Patch对象中。通过指定一个新的 patch，您可以更改 MIDI 通道的当前乐器。该 patch 可以被视为当前声音库中乐器的二维索引。

您可能想知道声音库是否也是按数字索引的。答案是否定的；MIDI 规范没有提供这一点。在 Java Sound API 中，可以通过读取声音库文件来获取Soundbank对象。如果合成器支持声音库，它的乐器可以根据需要单独加载到合成器中，或者一次性全部加载。许多合成器都有一个内置或默认的声音库；该声音库中包含的乐器始终对合成器可用。

声音

区分合成器可以同时播放的音色数量和音符数量是很重要的。前者在“通道”下面已经描述过。同时播放多个音符的能力被称为复音。即使一个合成器不是多音色的，通常也可以同时播放多个音符（所有音符具有相同的音色，但不同的音高）。例如，播放任何和弦，比如 G 大三和弦或 B 小七和弦，都需要复音。任何实时生成声音的合成器都有一个限制，即它可以同时合成的音符数量。在 Java Sound API 中，合成器通过getMaxPolyphony方法报告这个限制。

声音是一系列单音符，比如一个人可以唱的旋律。复音包括多个声音，比如合唱团唱的部分。例如，一个 32 声音的合成器可以同时播放 32 个音符。（然而，一些 MIDI 文献使用“声音”一词的含义不同，类似于“乐器”或“音色”的含义。）

将传入的 MIDI 音符分配给特定声音的过程称为声音分配。合成器维护一个声音列表，跟踪哪些声音是活动的（意味着它们当前有音符在响）。当一个音符停止响时，声音变为非活动状态，意味着它现在可以接受合成器接收到的下一个音符请求。一个传入的 MIDI 命令流很容易请求比合成器能够生成的更多同时音符。当所有合成器的声音都是活动的时，下一个 Note On 请求应该如何处理？合成器可以实现不同的策略：最近请求的音符可以被忽略；或者通过停止另一个音符，比如最近启动的音符，来播放它。

尽管 MIDI 规范并不要求这样做，合成器可以公开每个声音的内容。Java Sound API 包括一个VoiceStatus类来实现这一目的。

一个VoiceStatus报告了声音当前的活动或非活动状态，MIDI 通道，银行和程序号，MIDI 音符号，以及 MIDI 音量。

有了这个背景，让我们来看一下 Java Sound API 合成的具体细节。

管理乐器和音色库

在许多情况下，一个程序可以使用Synthesizer对象而几乎不需要显式调用任何合成 API。例如，假设你正在播放一个标准的 MIDI 文件。你将其加载到一个Sequence对象中，通过让一个序列器将数据发送到默认的合成器来播放。序列中的数据按照预期控制合成器，按时播放所有正确的音符。

然而，有些情况下这种简单的情景是不够的。序列包含正确的音乐，但乐器听起来全错了！这种不幸的情况可能是因为 MIDI 文件的创建者心目中的乐器与当前加载到合成器中的乐器不同。

MIDI 1.0 规范提供了银行选择和程序更改命令，这些命令影响每个 MIDI 通道上当前播放的乐器。然而，该规范并未定义每个补丁位置（银行和程序号）应该放置什么乐器。较新的 General MIDI 规范通过定义一个包含 128 个与特定乐器声音对应的程序的银行来解决这个问题。General MIDI 合成器使用 128 个与指定集合匹配的乐器。即使播放应该是相同乐器的不同 General MIDI 合成器听起来可能会有很大不同。然而，一个 MIDI 文件在大多数情况下应该听起来相似（即使不完全相同），无论哪个 General MIDI 合成器在播放它。

尽管如此，并非所有的 MIDI 文件创建者都希望受限于 General MIDI 定义的 128 种音色。本节展示如何更改合成器附带的默认乐器集合。（如果没有默认设置，意味着在访问合成器时没有加载任何乐器，那么无论如何你都必须使用这个 API 开始。）

了解加载的乐器

要了解当前加载到合成器中的乐器是否符合你的要求，可以调用这个Synthesizer方法：

Instrument[] getLoadedInstruments() 

并遍历返回的数组，查看当前加载的确切乐器。很可能，你会在用户界面中显示乐器的名称（使用Instrument的getName方法），让用户决定是否使用这些乐器或加载其他乐器。Instrument API 包括一个报告乐器属于哪个声音库的方法。声音库的名称可能帮助你的程序或用户确定乐器的确切信息。

这个Synthesizer方法：

Soundbank getDefaultSoundbank() 

给出默认的声音库。Soundbank API 包括检索声音库名称、供应商和版本号的方法，通过这些信息，程序或用户可以验证库的身份。然而，当你第一次获得一个合成器时，不能假设默认声音库中的乐器已经被加载到合成器中。例如，一个合成器可能有大量内置乐器可供使用，但由于其有限的内存，它可能不会自动加载它们。

加载不同的乐器

用户可能决定加载与当前乐器不同的乐器（或者你可能以编程方式做出这个决定）。以下方法告诉你合成器附带哪些乐器（而不必从声音库文件加载）：

Instrument[] getAvailableInstruments()

你可以通过调用以下方法加载任何这些乐器：

boolean loadInstrument(Instrument instrument) 

乐器被加载到合成器中，位置由乐器的Patch对象指定（可以使用Instrument的getPatch方法检索）。

要从其他声音库加载乐器，首先调用Synthesizer的isSupportedSoundbank方法，确保声音库与此合成器兼容（如果不兼容，可以遍历系统的合成器尝试找到支持声音库的合成器）。然后可以调用这些方法之一从声音库加载乐器：

boolean loadAllInstruments(Soundbank soundbank) 
boolean loadInstruments(Soundbank soundbank, 
  Patch[] patchList) 

正如名称所示，第一个加载给定声音库中的所有乐器，第二个加载声音库中选择的乐器。你也可以使用Soundbank的getInstruments方法访问所有乐器，然后遍历它们，并使用loadInstrument逐个加载选择的乐器。

不需要加载的所有乐器来自同一个声音库。您可以使用loadInstrument或loadInstruments从一个声音库加载某些乐器，从另一个声音库加载另一组乐器，依此类推。

每个乐器都有自己的Patch对象，指定了乐器应加载到合成器的位置。该位置由银行号和程序号定义。没有 API 可以通过更改补丁的银行或程序号来更改位置。

然而，可以使用Synthesizer的以下方法将乐器加载到除其补丁指定位置之外的位置：

boolean remapInstrument(Instrument from, Instrument to) 

此方法从合成器中卸载其第一个参数，并将其第二个参数放置在第一个参数占用的合成器补丁位置。

卸载乐器

将乐器加载到程序位置会自动卸载该位置已经加载的任何乐器，如果有的话。您还可以显式卸载乐器，而不一定要用新的替换它们。Synthesizer包括三个与三个加载方法对应的卸载方法。如果合成器接收到选择当前未加载任何乐器的程序位置的程序更改消息，则在发送程序更改消息的 MIDI 通道上不会有任何声音。

访问声音库资源

一些合成器在其声音库中存储除乐器之外的其他信息。例如，波表合成器存储一个或多个乐器可以访问的音频样本。因为样本可能被多个乐器共享，它们独立于任何乐器存储在声音库中。Soundbank接口和Instrument类都提供一个名为getSoundbankResources的方法调用，返回一个SoundbankResource对象列表。这些对象的细节特定于为其设计声音库的合成器。在波表合成的情况下，资源可能是一个封装自音频录音片段的一系列音频样本的对象。使用其他合成技术的合成器可能在合成器的SoundbankResources数组中存储其他类型的对象。

查询合成器的功能和当前状态

Synthesizer接口包括返回有关合成器功能的信息的方法：

    public long getLatency()
    public int getMaxPolyphony()

延迟度量了传递 MIDI 消息到合成器并合成器实际产生相应结果之间的最坏情况延迟。例如，合成器在接收到音符开启事件后可能需要几毫秒才开始生成音频。

getMaxPolyphony 方法指示合成器可以同时发出多少音符，如前面在 Voices 下讨论的那样。如同在同一讨论中提到的，合成器可以提供关于其音色的信息。这是通过以下方法实现的：

public VoiceStatus[] getVoiceStatus()

返回的数组中的每个 VoiceStatus 报告了音色的当前活动或非活动状态、MIDI 通道、银行和程序号、MIDI 音符号码和 MIDI 音量。数组的长度通常应该与 getMaxPolyphony 返回的相同数量一样。如果合成器没有播放，所有其 VoiceStatus 对象的 active 字段都设置为 false。

您可以通过检索其 MidiChannel 对象并查询其状态来了解有关合成器当前状态的其他信息。这将在下一节中更详细地讨论。

使用通道

有时访问合成器的 MidiChannel 对象直接是有用或必要的。本节讨论了这种情况。

在不使用序列器的情况下控制合成器

当使用序列器时，比如从 MIDI 文件中读取的序列，您不需要自己向合成器发送 MIDI 命令。相反，您只需将序列加载到序列器中，将序列器连接到合成器，并让其运行。序列器负责安排事件的时间表，结果是可预测的音乐表现。当所需音乐事先已知时，这种情况是有效的，这在从文件中读取时是正确的。

然而，在某些情况下，音乐是在播放时即时生成的。例如，用户界面可能会显示一个音乐键盘或吉他指板，并允许用户通过鼠标点击随意弹奏音符。另一个例子，一个应用程序可能使用合成器不是为了演奏音乐本身，而是为了根据用户的操作生成音效。这种情况在游戏中很典型。最后一个例子，应用程序可能确实正在播放从文件中读取的音乐，但用户界面允许用户与音乐互动，动态地改变它。在所有这些情况下，应用程序直接向合成器发送命令，因为 MIDI 消息需要立即传递，而不是被安排在将来的某个确定时间点。

有至少两种方法可以将 MIDI 消息发送到合成器而不使用序列器。第一种方法是构造一个 MidiMessage 并通过 Receiver 的 send 方法将其传递给合成器。例如，要在 MIDI 通道 5（从 1 开始计数）上立即产生中央 C（MIDI 音符号码 60），可以执行以下操作：

    ShortMessage myMsg = new ShortMessage();
    // Play the note Middle C (60) moderately loud
    // (velocity = 93)on channel 4 (zero-based).
    myMsg.setMessage(ShortMessage.NOTE_ON, 4, 60, 93); 
    Synthesizer synth = MidiSystem.getSynthesizer();
    Receiver synthRcvr = synth.getReceiver();
    synthRcvr.send(myMsg, -1); // -1 means no time stamp

第二种方法是完全绕过消息传递层（即 MidiMessage 和 Receiver API），直接与合成器的 MidiChannel 对象交互。您首先需要检索合成器的 MidiChannel 对象，使用以下 Synthesizer 方法：

public MidiChannel[] getChannels()

之后，您可以直接调用所需的MidiChannel方法。这比将相应的MidiMessages发送到合成器的Receiver并让合成器处理与其自己的MidiChannels的通信更直接。例如，前面示例对应的代码将是：

    Synthesizer synth = MidiSystem.getSynthesizer();
    MidiChannel chan[] = synth.getChannels(); 
    // Check for null; maybe not all 16 channels exist.
    if (chan[4] != null) {
         chan[4].noteOn(60, 93); 
    }

获取通道的当前状态

MidiChannel接口提供了与 MIDI 规范中定义的每个“通道音频”或“通道模式”消息一一对应的方法。我们在前面的示例中看到了使用 noteOn 方法的情况。但是，除了这些经典方法之外，Java Sound API 的MidiChannel接口还添加了一些“get”方法，用于检索最近由相应的音频或模式“set”方法设置的值：

    int       getChannelPressure()
    int       getController(int controller)
    boolean   getMono()
    boolean   getOmni() 
    int       getPitchBend() 
    int       getPolyPressure(int noteNumber)
    int       getProgram()

这些方法可能对向用户显示通道状态或决定随后发送给通道的值很有用。

静音和独奏通道

Java Sound API 添加了每个通道独奏和静音的概念，这不是 MIDI 规范所要求的。这类似于 MIDI 序列轨道上的独奏和静音。

如果静音打开，该通道将不会发声，但其他通道不受影响。如果独奏打开，该通道和任何其他独奏的通道将会发声（如果它没有被静音），但其他通道不会发声。同时被独奏和静音的通道将不会发声。MidiChannel API 包括四种方法：

    boolean      getMute() 
    boolean      getSolo()
    void         setMute(boolean muteState) 
    void         setSolo(boolean soloState)

允许播放合成声音

任何已安装的 MIDI 合成器产生的音频通常会通过采样音频系统路由。如果您的程序没有权限播放音频，则合成器的声音将听不到，并且会抛出安全异常。有关音频权限的更多信息，请参阅之前关于使用音频资源的权限使用音频资源的权限的讨论。

服务提供者接口简介

原文：docs.oracle.com/javase/tutorial/sound/SPI-intro.html

什么是服务？

服务是声音处理功能单元，当应用程序使用 Java Sound API 的实现时自动可用。它们由执行读取、写入、混合、处理和转换音频和 MIDI 数据工作的对象组成。Java Sound API 的实现通常提供一组基本服务，但 API 中也包含机制，支持第三方开发人员（或实现供应商自身）开发新声音服务。这些新服务可以“插入”到现有安装的实现中，扩展其功能而不需要发布新版本。在 Java Sound API 架构中，第三方服务被集成到系统中，以便应用程序的接口与“内置”服务的接口相同。在某些情况下，使用 javax.sound.sampled 和 javax.sound.midi 包的应用程序开发人员甚至可能不知道他们正在使用第三方服务。

潜在的第三方采样音频服务示例包括：

• 声音文件读取器和写入器

• 在不同音频数据格式之间转换的转换器

• 新的音频混音器和输入/输出设备，无论是纯粹在软件中实现，还是在硬件中具有软件接口

第三方 MIDI 服务可能包括：

• MIDI 文件读取器和写入器

• 用于各种类型声音库文件的读取器（通常特定于特定合成器）

• 受 MIDI 控制的声音合成器、音序器和 I/O 端口，无论是纯粹在软件中实现，还是在硬件中具有软件接口

服务如何工作

javax.sound.sampled 和 javax.sound.midi 包为希望在其应用程序中包含声音服务的应用程序开发人员提供功能。这些包是声音服务的消费者，提供接口以获取有关音频和 MIDI 服务的信息、控制和访问。此外，Java Sound API 还提供了两个定义抽象类的包，供声音服务的提供者使用：javax.sound.sampled.spi 和 javax.sound.midi.spi 包。

新声音服务的开发人员实现 SPI 包中适当类的具体子类。这些子类以及支持新服务所需的任何其他类都放在一个包含所包含服务描述的 Java 存档（JAR）存档文件中。当此 JAR 文件安装在用户的 CLASSPATH 中时，运行时系统会自动使新服务可用，扩展 Java 平台运行时系统的功能。

一旦安装了新服务，它就可以像以前安装的任何服务一样访问。服务的消费者可以通过调用javax.sound.sampled和javax.sound.midi包中的AudioSystem和MidiSystem类的方法来获取有关新服务的信息，或获取新服务类的实例，以返回有关新服务的信息，或返回新的或现有服务类的实例。应用程序无需直接引用 SPI 包（及其子类）中的类来使用已安装的服务。

例如，假设一个名为 Acme Software, Inc.的假想服务提供商有兴趣提供一个允许应用程序读取新格式声音文件的包（但其音频数据是标准数据格式的）。SPI 类AudioFileReader可以被子类化为一个名为AcmeAudioFileReader的类。在新的子类中，Acme 将提供AudioFileReader中定义的所有方法的实现；在这种情况下，只有两个方法（带参数变体），getAudioFileFormat和getAudioInputStream。然后，当应用程序尝试读取一个恰好是 Acme 文件格式的声音文件时，它会调用javax.sound.sampled中的AudioSystem类的方法来访问文件和有关文件的信息。方法AudioSystem.getAudioInputStream和AudioSystem.getAudioFileFormat提供了一个标准的 API 来读取音频流；安装了AcmeAudioFileReader类后，此接口会被扩展以透明地支持新文件类型。应用程序开发人员不需要直接访问新注册的 SPI 类：AudioSystem对象方法会将查询传递给已安装的AcmeAudioFileReader类。

为什么要有这些“工厂”类？为什么不允许应用程序开发人员直接访问新提供的服务？这是一种可能的方法，但通过门卫系统对象管理和实例化所有服务可以使应用程序开发人员免于了解已安装服务的身份。应用程序开发人员只需使用对他们有价值的服务，甚至可能都没有意识到。同时，这种架构允许服务提供者有效地管理其包中的可用资源。

通常，新声音服务的使用对应用程序是透明的。例如，想象一种情况，应用程序开发人员想要从文件中读取音频流。假设thePathName标识了一个音频输入文件，程序会这样做：

    File theInFile = new File(thePathName);
    AudioInputStream theInStream = AudioSystem.getAudioInputStream(theInFile); 

在幕后，AudioSystem确定了哪个已安装的服务可以读取文件，并要求其提供音频数据作为AudioInputStream对象。开发人员可能不知道或甚至不关心输入音频文件是某种新文件格式（例如 Acme 的格式），这些格式由已安装的第三方服务支持。程序与流的第一次接触是通过AudioSystem对象，其后所有对流及其属性的访问都是通过AudioInputStream的方法。这两者都是javax.sound.sampled API 中的标准对象；新文件格式可能需要的特殊处理完全被隐藏起来。

服务提供者如何准备新服务

服务提供者以特殊格式的 JAR 文件提供其新服务，这些文件将被安装在用户系统中 Java 运行时将找到的目录中。JAR 文件是存档文件，每个文件包含一组文件，这些文件可能在存档中的分层目录结构中组织。关于放入这些存档的类文件的准备细节将在接下来的几页中讨论，这些页面描述了音频和 MIDI SPI 包的具体内容；在这里，我们只是概述 JAR 文件创建的过程。

新服务或服务的 JAR 文件应包含 JAR 文件中支持的每个服务的类文件。遵循 Java 平台的约定，每个类文件都具有新定义类的名称，这是一个抽象服务提供者类的具体子类。JAR 文件还必须包含新服务实现所需的任何支持类。为了使运行时系统的服务提供者机制能够定位新服务，JAR 文件还必须包含特殊文件（下文描述），将 SPI 类名称映射到正在定义的新子类。

继续我们上面的例子，假设 Acme Software, Inc.正在分发一套新的采样音频服务包。假设这个包包含两个新服务：

• AcmeAudioFileReader类，如上所述，是AudioFileReader的子类

• 一个名为AcmeAudioFileWriter的AudioFileWriter子类，将以 Acme 的新格式编写声音文件

从一个任意目录开始——我们称之为/devel——我们创建子目录并将新的类文件放入其中，以一种组织方式来给出新类将被引用的期望路径名：

    com/acme/AcmeAudioFileReader.class
    com/acme/AcmeAudioFileWriter.class

此外，对于每个新的 SPI 类的子类，我们在一个名为META-INF/services的特殊命名目录中创建一个映射文件。文件的名称是被子类化的 SPI 类的名称，文件包含该 SPI 抽象类的新子类的名称。

我们创建文件

  META-INF/services/javax.sound.sampled.spi.AudioFileReader

包括

    # Providers of sound file-reading services 
    # (a comment line begins with a pound sign)
    com.acme.AcmeAudioFileReader

以及文件

  META-INF/services/javax.sound.sampled.spi.AudioFileWriter

包括

    # Providers of sound file-writing services 
    com.acme.AcmeAudioFileWriter

现在我们在任何目录中运行jar命令行：

jar cvf acme.jar -C /devel .

-C选项会导致jar切换到/devel目录，而不是使用执行命令的目录。最后的句点参数指示jar归档该目录的所有内容（即/devel），但不包括目录本身。

这次运行将创建文件acme.jar，其中包含以下内容：

com/acme/AcmeAudioFileReader.class
com/acme/AcmeAudioFileWriter.class
META-INF/services/javax.sound.sampled.spi.AudioFileReader
META-INF/services/javax.sound.sampled.spi.AudioFileWriter
META-INF/Manifest.mf

文件Manifest.mf是由jar工具本身生成的，其中列出了存档中包含的所有文件。

用户如何安装新服务

对于希望通过他们的应用程序获得新服务访问权限的最终用户（或系统管理员），安装是简单的。他们将提供的 JAR 文件放在他们的CLASSPATH中的一个目录中。在执行时，Java 运行时会在需要时找到引用的类。

安装同一服务的多个提供者并不是错误。例如，两个不同的服务提供者可能提供支持读取相同类型的声音文件。在这种情况下，系统会任意选择一个提供者。在意识到哪个提供者被选择的用户应该只安装所需的那个。

提供采样音频服务

原文：docs.oracle.com/javase/tutorial/sound/SPI-providing-sampled.html

正如你所知，Java Sound API 包括两个包，javax.sound.sampled.spi 和 javax.sound.midi.spi，它们定义了抽象类，供声音服务的开发者使用。通过实现并安装这些抽象类的子类，服务提供者可以注册新服务，扩展运行时系统的功能。本页面告诉你如何使用 javax.sound.sampled.spi 包来提供处理采样音频的新服务。

javax.sound.sampled.spi 包中有四个抽象类，代表着你可以为采样音频系统提供的四种不同类型的服务：

• AudioFileWriter 提供音频文件写入服务。这些服务使应用程序能够将音频数据流写入特定类型的文件。

• AudioFileReader 提供文件读取服务。这些服务使应用程序能够确定音频文件的特性，并获取一个流，从中可以读取文件的音频数据。

• FormatConversionProvider 提供音频数据格式转换服务。这些服务允许应用程序将音频流从一种数据格式转换为另一种。

• MixerProvider 提供特定类型混音器的管理。这种机制允许应用程序获取关于给定类型混音器的信息，并访问实例。

总结之前的讨论，服务提供者可以扩展运行时系统的功能。典型的 SPI 类有两种类型的方法：一种是响应关于特定提供者提供的服务类型的查询，另一种是直接执行新服务，或返回实际提供服务的对象实例。运行时环境的服务提供者机制提供了已安装服务与音频系统的注册，以及新服务提供者类的管理。

本质上，服务实例与应用程序开发人员之间存在双重隔离。应用程序从不直接创建服务对象的实例，例如混音器或格式转换器，以用于其音频处理任务。程序甚至不会直接从管理它们的 SPI 类中请求这些对象。应用程序向javax.sound.sampled包中的AudioSystem对象发出请求，AudioSystem反过来使用 SPI 对象来处理这些查询和服务请求。

新音频服务的存在对用户和应用程序员可能是完全透明的。所有应用程序引用都通过javax.sound.sampled包的标准对象，主要是AudioSystem，新服务可能提供的特殊处理通常是完全隐藏的。

在本讨论中，我们将继续使用类似AcmeMixer和AcmeMixerProvider的名称来指代新的 SPI 子类。

提供音频文件写入服务

让我们从AudioFileWriter开始，这是较简单的 SPI 类之一。

实现AudioFileWriter方法的子类必须提供一组方法的实现，以处理关于类支持的文件格式和文件类型的查询，以及提供实际将提供的音频数据流写入File或OutputStream的方法。

AudioFileWriter包括两个在基类中具有具体实现的方法：

boolean isFileTypeSupported(AudioFileFormat.Type fileType) 
boolean isFileTypeSupported(AudioFileFormat.Type fileType, AudioInputStream stream) 

这些方法中的第一个方法通知调用者，此文件写入器是否可以写入指定类型的声音文件。这个方法是一个一般性的查询，如果文件写入器可以写入那种类型的文件，它将返回true，假设文件写入器被提供适当的音频数据。然而，写入文件的能力可能取决于传递给文件写入器的特定音频数据的格式。文件写入器可能不支持每种音频数据格式，或者约束可能由文件格式本身施加。（并非所有类型的音频数据都可以写入所有类型的声音文件。）因此，第二个方法更具体，询问特定的AudioInputStream是否可以写入特定类型的文件。

通常情况下，您不需要覆盖这两个具体方法。每个方法只是调用两个其他查询方法之一并遍历返回的结果的包装器。这两个其他查询方法是抽象的，因此需要在子类中实现：

abstract AudioFileFormat.Type[] getAudioFileTypes() 
abstract AudioFileFormat.Type[] getAudioFileTypes(AudioInputStream stream) 

这些方法直接对应于前两个方法。每个方法返回所有支持的文件类型的数组-在第一个方法的情况下，通常是所有一般支持的，在第二个方法的情况下，是特定音频流支持的所有文件类型。第一个方法的典型实现可能简单地返回一个由文件写入器构造函数初始化的数组。第二个方法的实现可能测试流的AudioFormat对象，以查看请求的文件类型是否支持该数据格式。

AudioFileWriter的最后两个方法执行实际的文件写入工作：

abstract int write(AudioInputStream stream, 
     AudioFileFormat.Type fileType, java.io.File out) 
abstract int write(AudioInputStream stream, 
     AudioFileFormat.Type fileType, java.io.OutputStream out) 

这些方法将代表音频数据的字节流写入到第三个参数指定的流或文件中。如何完成这项工作的细节取决于指定类型文件的结构。write方法必须按照该格式声音文件的规定方式写入文件的头部和音频数据（无论是标准类型的声音文件还是新的、可能是专有的类型）。

提供音频文件读取服务

AudioFileReader类由六个抽象方法组成，您的子类需要实现这些方法-实际上，两个不同的重载方法，每个方法都可以接受File、URL或InputStream参数。这两个重载方法中的第一个接受有关指定文件格式的查询：

abstract AudioFileFormat getAudioFileFormat(java.io.File file) 
abstract AudioFileFormat getAudioFileFormat(java.io.InputStream stream) 
abstract AudioFileFormat getAudioFileFormat(java.net.URL url) 

getAudioFileFormat方法的典型实现读取并解析声音文件的头部，以确定其文件格式。查看AudioFileFormat类的描述，了解需要从头部读取哪些字段，并参考特定文件类型的规范，以了解如何解析头部。

因为调用者将流作为参数提供给此方法，希望该方法不改变流，文件读取器通常应该从标记流开始。在读取到头部结束后，应该将流重置到其原始位置。

另一个重载的AudioFileReader方法提供文件读取服务，通过返回一个AudioInputStream，从中可以读取文件的音频数据：

abstract AudioInputStream getAudioInputStream(java.io.File file) 
abstract AudioInputStream getAudioInputStream(java.io.InputStream stream) 
abstract AudioInputStream getAudioInputStream(java.net.URL url) 

通常，getAudioInputStream的实现返回一个绕到文件数据块（在头部之后）开头的AudioInputStream，准备好进行读取。然而，可以想象，文件读取器返回的AudioInputStream可能表示一种从文件中包含的内容解码出来的数据流。重要的是，该方法返回一个格式化的流，从中可以读取文件中包含的音频数据。返回的AudioInputStream对象中封装的AudioFormat将告知调用者有关流的数据格式，通常情况下，但不一定是文件本身的数据格式。

通常，返回的流是AudioInputStream的一个实例；您不太可能需要对AudioInputStream进行子类化。

提供格式转换服务

FormatConversionProvider子类将具有一个音频数据格式的AudioInputStream转换为具有另一种格式的AudioInputStream。前者（输入）流被称为源流，后者（输出）流被称为目标流。回想一下，AudioInputStream包含一个AudioFormat，而AudioFormat又包含一种特定类型的数据编码，由AudioFormat.Encoding对象表示。源流中的格式和编码称为源格式和源编码，目标流中的格式和编码同样被称为目标格式和目标编码。

转换工作是在FormatConversionProvider的重载抽象方法getAudioInputStream中执行的。该类还具有用于了解所有支持的目标和源格式和编码的抽象查询方法。有具体的包装方法用于查询特定的转换。

getAudioInputStream的两个变体是：

abstract AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding, 
     AudioInputStream sourceStream) 

和

abstract AudioInputStream getAudioInputStream(AudioFormat targetFormat, 
     AudioInputStream sourceStream) 

这些根据调用者是指定完整目标格式还是只是格式的编码而有所不同的第一个参数。

getAudioInputStream的典型实现通过返回一个围绕原始（源）AudioInputStream的新的AudioInputStream子类来工作，并在调用read方法时对其数据应用数据格式转换。例如，考虑一个名为AcmeCodec的新FormatConversionProvider子类的情况，它与一个名为AcmeCodecStream的新AudioInputStream子类一起工作。

AcmeCodec的第二个getAudioInputStream方法的实现可能是：

public AudioInputStream getAudioInputStream
      (AudioFormat outputFormat, AudioInputStream stream) {
        AudioInputStream cs = null;
        AudioFormat inputFormat = stream.getFormat();
        if (inputFormat.matches(outputFormat) ) {
            cs = stream;
        } else {
            cs = (AudioInputStream)
                (new AcmeCodecStream(stream, outputFormat));
            tempBuffer = new byte[tempBufferSize];
        }
        return cs;
    }

实际的格式转换发生在返回的AcmeCodecStream的新read方法中，它是AudioInputStream的子类。同样，访问这个返回的AcmeCodecStream的应用程序只需将其视为AudioInputStream进行操作，而不需要了解其实现的细节。

FormatConversionProvider的其他方法都允许查询对象支持的输入和输出编码和格式。以下四个方法是抽象的，需要被实现：

abstract AudioFormat.Encoding[] getSourceEncodings() 
abstract AudioFormat.Encoding[] getTargetEncodings() 
abstract AudioFormat.Encoding[] getTargetEncodings(
    AudioFormat sourceFormat) 
abstract  AudioFormat[] getTargetFormats(
    AudioFormat.Encoding targetEncoding, 
    AudioFormat sourceFormat) 

与上面讨论的AudioFileReader类的查询方法一样，这些查询通常通过检查对象的私有数据，并且对于后两种方法，将它们与参数进行比较来处理。

剩下的四个FormatConversionProvider方法是具体的，通常不需要被重写：

boolean isConversionSupported(
    AudioFormat.Encoding targetEncoding,
    AudioFormat sourceFormat) 
boolean isConversionSupported(AudioFormat targetFormat, 
    AudioFormat sourceFormat) 
boolean isSourceEncodingSupported(
    AudioFormat.Encoding sourceEncoding) 
boolean isTargetEncodingSupported(
    AudioFormat.Encoding targetEncoding) 

与AudioFileWriter.isFileTypeSupported()类似，这些方法的默认实现本质上是调用其他查询方法之一并遍历返回的结果的包装器。

提供新类型的混音器

正如其名称所示，MixerProvider提供混音器的实例。每个具体的MixerProvider子类都充当应用程序使用的Mixer对象的工厂。当然，只有在定义一个或多个新的Mixer接口的实现时，定义新的MixerProvider才有意义。就像上面的FormatConversionProvider示例中，我们的getAudioInputStream方法返回了一个执行转换的AudioInputStream子类一样，我们的新类AcmeMixerProvider有一个getMixer方法，返回实现Mixer接口的另一个新类的实例。我们将后者称为AcmeMixer。特别是如果混音器是硬件实现的，提供者可能仅支持所请求设备的一个静态实例。如果是这样，它应该在每次调用getMixer时返回这个静态实例。

由于AcmeMixer支持Mixer接口，应用程序不需要任何额外的信息来访问其基本功能。然而，如果AcmeMixer支持Mixer接口中未定义的功能，并且供应商希望使这些扩展功能对应用程序可访问，那么混音器当然应该被定义为一个公共类，具有额外的、有文档记录的公共方法，以便希望利用这些扩展功能的程序可以导入AcmeMixer并将getMixer返回的对象转换为这种类型。

另外两种MixerProvider的方法是：

abstract Mixer.Info[] getMixerInfo() 

和

boolean isMixerSupported(Mixer.Info info) 

这些方法允许音频系统确定这个特定的提供者类是否可以提供应用程序需要的设备。换句话说，AudioSystem对象可以迭代所有已安装的MixerProviders，看看哪些，如果有的话，可以提供应用程序请求的AudioSystem的设备。getMixerInfo方法返回一个包含有关此提供程序对象提供的混音器类型信息的对象数组。系统可以将这些信息对象与其他提供程序的信息一起传递给应用程序。

一个MixerProvider可以提供多种类型的混音器。当系统调用MixerProvider的getMixerInfo方法时，它会得到一个信息对象列表，标识此提供程序支持的不同类型的混音器。然后系统可以调用MixerProvider.getMixer(Mixer.Info)来获取每个感兴趣的混音器。

你的子类需要实现getMixerInfo，因为它是抽象的。isMixerSupported方法是具体的，通常不需要被覆盖。默认实现只是将提供的Mixer.Info与getMixerInfo返回的数组中的每一个进行比较。

提供 MIDI 服务

原文：docs.oracle.com/javase/tutorial/sound/SPI-providing-MIDI.html

服务提供者接口简介 解释了javax.sound.sampled.spi和javax.sound.midi.spi包定义了供声音服务开发人员使用的抽象类。通过实现这些抽象类的子类，服务提供者可以创建一个扩展运行时系统功能的新服务。前一节介绍了如何使用javax.sound.sampled.spi包。本节讨论如何使用javax.sound.midi.spi包为处理 MIDI 设备和文件提供新服务。

javax.sound.midi.spi 包中有四个抽象类，代表着你可以为 MIDI 系统提供的四种不同类型的服务：

• MidiFileWriter 提供了 MIDI 文件写入服务。这些服务使应用程序能够将其生成或处理的 MIDI Sequence 保存到 MIDI 文件中。

• MidiFileReader 提供了从 MIDI 文件中返回 MIDI Sequence 供应用程序使用的文件读取服务。

• MidiDeviceProvider 提供了一个或多个特定类型的 MIDI 设备实例，可能包括硬件设备。

• SoundbankReader 提供了声音库文件读取服务。SoundbankReader的具体子类解析给定的声音库文件，生成一个可以加载到Synthesizer中的Soundbank对象。

应用程序不会直接创建服务对象的实例，无论是提供者对象，比如MidiDeviceProvider，还是由提供者对象提供的对象，比如Synthesizer。程序也不会直接引用 SPI 类。相反，应用程序会向javax.sound.midi包中的MidiSystem对象发出请求，而MidiSystem又会使用javax.sound.midi.spi类的具体子类来处理这些请求。

提供 MIDI 文件写入服务

有三种标准的 MIDI 文件格式，Java Sound API 的实现都可以支持：Type 0、Type 1 和 Type 2。这些文件格式在文件中的 MIDI 序列数据的内部表示上有所不同，并且适用于不同类型的序列。如果一个实现本身不支持所有三种类型，服务提供者可以为未实现的类型提供支持。还有标准 MIDI 文件格式的变体，其中一些是专有的，同样可以由第三方供应商支持。

写入 MIDI 文件的能力由MidiFileWriter的具体子类提供。这个抽象类直接类比于javax.sampled.spi.AudioFileWriter。同样，方法被分组为查询方法，用于了解可以写入哪些类型的文件，以及用于实际写入文件的方法。与AudioFileWriter一样，其中两个查询方法是具体的：

boolean isFileTypeSupported(int fileType)
boolean isFileTypeSupported(int fileType, Sequence sequence) 

其中第一个提供关于文件写入器是否可以写入指定类型的 MIDI 文件类型的一般信息。第二个方法更具体：它询问特定 Sequence 是否可以写入指定类型的 MIDI 文件。通常情况下，您不需要覆盖这两个具体方法中的任何一个。在默认实现中，每个方法调用另外两个相应的查询方法之一，并遍历返回的结果。作为抽象方法，这另外两个查询方法需要在子类中实现：

abstract int[] getMidiFileTypes() 
abstract int[] getMidiFileTypes(Sequence sequence) 

其中第一个返回一个数组，其中包含一般支持的所有文件类型。一个典型的实现可能会在文件写入器的构造函数中初始化数组，并从这个方法返回数组。从文件类型集中，第二个方法找到文件写入器可以写入给定 Sequence 的子集。根据 MIDI 规范，不是所有类型的序列都可以写入所有类型的 MIDI 文件。

MidiFileWriter子类的write方法执行将给定Sequence中的数据编码为请求的 MIDI 文件类型的正确数据格式，将编码流写入文件或输出流的操作：

abstract int write(Sequence in, int fileType, 
                   java.io.File out) 
abstract int write(Sequence in, int fileType, 
                   java.io.OutputStream out) 

为了实现这一点，write方法必须通过迭代Sequence的轨道来解析Sequence，构建适当的文件头，并将头部和轨道写入输出。当然，MIDI 文件的头部格式由 MIDI 规范定义。它包括诸如标识这是 MIDI 文件的“魔数”，头部长度，轨道数以及序列的定时信息（分频类型和分辨率）等信息。MIDI 文件的其余部分由轨道数据组成，格式由 MIDI 规范定义。

让我们简要地看一下应用程序、MIDI 系统和服务提供者如何合作编写 MIDI 文件。在典型情况下，一个应用程序有一个特定的 MIDI Sequence要保存到文件中。程序查询MidiSystem对象，看看对于手头的特定Sequence支持哪些 MIDI 文件格式（如果有的话），然后尝试写入文件。MidiSystem.getMidiFileTypes(Sequence)方法返回系统可以写入特定序列的所有 MIDI 文件类型的数组。它通过调用每个已安装的MidiFileWriter服务的相应getMidiFileTypes方法来实现这一点，并将结果收集并以整数数组的形式返回，这可以被视为与给定Sequence兼容的所有文件类型的主列表。在写入Sequence到文件时，调用MidiSystem.write传递一个表示文件类型的整数，以及要写入的Sequence和输出文件；MidiSystem使用提供的类型来决定哪个已安装的MidiFileWriter应处理写入请求，并将相应的写入分派给适当的MidiFileWriter。