media/java/android/media/audiopolicy/AudioMixingRule.java - platform/frameworks/base - Git at Google

 /*
  * Copyright (C) 2014 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.media.audiopolicy;

 import android.annotation.SystemApi;
 import android.media.AudioAttributes;
 import android.os.Parcel;

 import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.Objects;


 /**
  * @hide
  *
  * Here's an example of creating a mixing rule for all media playback:
  * <pre>
  * AudioAttributes mediaAttr = new AudioAttributes.Builder()
  *         .setUsage(AudioAttributes.USAGE_MEDIA)
  *         .build();
  * AudioMixingRule mediaRule = new AudioMixingRule.Builder()
  *         .addRule(mediaAttr, AudioMixingRule.RULE_MATCH_ATTRIBUTE_USAGE)
  *         .build();
  * </pre>
  */
 @SystemApi
 public class AudioMixingRule {

     private AudioMixingRule(int mixType, ArrayList<AttributeMatchCriterion> criteria) {
         mCriteria = criteria;
         mTargetMixType = mixType;
     }

     /**
      * A rule requiring the usage information of the {@link AudioAttributes} to match.
      */
     @SystemApi
     public static final int RULE_MATCH_ATTRIBUTE_USAGE = 0x1;
     /**
      * A rule requiring the capture preset information of the {@link AudioAttributes} to match.
      */
     @SystemApi
     public static final int RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET = 0x1 << 1;

     private final static int RULE_EXCLUSION_MASK = 0x8000;
     /**
      * @hide
      * A rule requiring the usage information of the {@link AudioAttributes} to differ.
      */
     public static final int RULE_EXCLUDE_ATTRIBUTE_USAGE =
             RULE_EXCLUSION_MASK | RULE_MATCH_ATTRIBUTE_USAGE;
     /**
      * @hide
      * A rule requiring the capture preset information of the {@link AudioAttributes} to differ.
      */
     public static final int RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET =
             RULE_EXCLUSION_MASK | RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET;

     static final class AttributeMatchCriterion {
         AudioAttributes mAttr;
         int mRule;

         /** input parameters must be valid */
         AttributeMatchCriterion(AudioAttributes attributes, int rule) {
             mAttr = attributes;
             mRule = rule;
         }

         @Override
         public int hashCode() {
             return Objects.hash(mAttr, mRule);
         }

         void writeToParcel(Parcel dest) {
             dest.writeInt(mRule);
             if ((mRule == RULE_MATCH_ATTRIBUTE_USAGE) || (mRule == RULE_EXCLUDE_ATTRIBUTE_USAGE)) {
                 dest.writeInt(mAttr.getUsage());
             } else {
                 // capture preset rule
                 dest.writeInt(mAttr.getCapturePreset());
             }
         }
     }

     private final int mTargetMixType;
     int getTargetMixType() { return mTargetMixType; }
     private final ArrayList<AttributeMatchCriterion> mCriteria;
     ArrayList<AttributeMatchCriterion> getCriteria() { return mCriteria; }

     @Override
     public int hashCode() {
         return Objects.hash(mTargetMixType, mCriteria);
     }

     private static boolean isValidSystemApiRule(int rule) {
         switch(rule) {
             case RULE_MATCH_ATTRIBUTE_USAGE:
             case RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET:
                 return true;
             default:
                 return false;
         }
     }

     private static boolean isValidIntRule(int rule) {
         switch(rule) {
             case RULE_MATCH_ATTRIBUTE_USAGE:
             case RULE_EXCLUDE_ATTRIBUTE_USAGE:
             case RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET:
             case RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET:
                 return true;
             default:
                 return false;
         }
     }

     private static boolean isPlayerRule(int rule) {
         return ((rule == RULE_MATCH_ATTRIBUTE_USAGE)
                 || (rule == RULE_EXCLUDE_ATTRIBUTE_USAGE));
     }

     /**
      * Builder class for {@link AudioMixingRule} objects
      */
     @SystemApi
     public static class Builder {
         private ArrayList<AttributeMatchCriterion> mCriteria;
         private int mTargetMixType = AudioMix.MIX_TYPE_INVALID;

         /**
          * Constructs a new Builder with no rules.
          */
         @SystemApi
         public Builder() {
             mCriteria = new ArrayList<AttributeMatchCriterion>();
         }

         /**
          * Add a rule for the selection of which streams are mixed together.
          * @param attrToMatch a non-null AudioAttributes instance for which a contradictory
          *     rule hasn't been set yet.
          * @param rule {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE} or
          *     {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET}.
          * @return the same Builder instance.
          * @throws IllegalArgumentException
          */
         @SystemApi
         public Builder addRule(AudioAttributes attrToMatch, int rule)
                 throws IllegalArgumentException {
             if (!isValidSystemApiRule(rule)) {
                 throw new IllegalArgumentException("Illegal rule value " + rule);
             }
             return addRuleInt(attrToMatch, rule);
         }

         /**
          * Add a rule by exclusion for the selection of which streams are mixed together.
          * <br>For instance the following code
          * <br><pre>
          * AudioAttributes mediaAttr = new AudioAttributes.Builder()
          *         .setUsage(AudioAttributes.USAGE_MEDIA)
          *         .build();
          * AudioMixingRule noMediaRule = new AudioMixingRule.Builder()
          *         .excludeRule(mediaAttr, AudioMixingRule.RULE_MATCH_ATTRIBUTE_USAGE)
          *         .build();
          * </pre>
          * <br>will create a rule which maps to any usage value, except USAGE_MEDIA.
          * @param attrToMatch a non-null AudioAttributes instance for which a contradictory
          *     rule hasn't been set yet.
          * @param rule {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE} or
          *     {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET}.
          * @return the same Builder instance.
          * @throws IllegalArgumentException
          */
         @SystemApi
         public Builder excludeRule(AudioAttributes attrToMatch, int rule)
                 throws IllegalArgumentException {
             if (!isValidSystemApiRule(rule)) {
                 throw new IllegalArgumentException("Illegal rule value " + rule);
             }
             return addRuleInt(attrToMatch, rule | RULE_EXCLUSION_MASK);
         }

         /**
          * Add or exclude a rule for the selection of which streams are mixed together.
          * @param attrToMatch a non-null AudioAttributes instance for which a contradictory
          *     rule hasn't been set yet.
          * @param rule one of {@link AudioMixingRule#RULE_EXCLUDE_ATTRIBUTE_USAGE},
          *     {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE},
          *     {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET} or
          *     {@link AudioMixingRule#RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET}.
          * @return the same Builder instance.
          * @throws IllegalArgumentException
          */
         Builder addRuleInt(AudioAttributes attrToMatch, int rule)
                 throws IllegalArgumentException {
             if (attrToMatch == null) {
                 throw new IllegalArgumentException("Illegal null AudioAttributes argument");
             }
             if (!isValidIntRule(rule)) {
                 throw new IllegalArgumentException("Illegal rule value " + rule);
             } else {
                 // as rules are added to the Builder, we verify they are consistent with the type
                 // of mix being built. When adding the first rule, the mix type is MIX_TYPE_INVALID.
                 if (mTargetMixType == AudioMix.MIX_TYPE_INVALID) {
                     if (isPlayerRule(rule)) {
                         mTargetMixType = AudioMix.MIX_TYPE_PLAYERS;
                     } else {
                         mTargetMixType = AudioMix.MIX_TYPE_RECORDERS;
                     }
                 } else if (((mTargetMixType == AudioMix.MIX_TYPE_PLAYERS) && !isPlayerRule(rule))
                         || ((mTargetMixType == AudioMix.MIX_TYPE_RECORDERS) && isPlayerRule(rule)))
                 {
                     throw new IllegalArgumentException("Incompatible rule for mix");
                 }
             }
             synchronized (mCriteria) {
                 Iterator<AttributeMatchCriterion> crIterator = mCriteria.iterator();
                 while (crIterator.hasNext()) {
                     final AttributeMatchCriterion criterion = crIterator.next();
                     if ((rule == RULE_MATCH_ATTRIBUTE_USAGE)
                             || (rule == RULE_EXCLUDE_ATTRIBUTE_USAGE)) {
                         // "usage"-based rule
                         if (criterion.mAttr.getUsage() == attrToMatch.getUsage()) {
                             if (criterion.mRule == rule) {
                                 // rule already exists, we're done
                                 return this;
                             } else {
                                 // criterion already exists with a another rule, it is incompatible
                                 throw new IllegalArgumentException("Contradictory rule exists for "
                                         + attrToMatch);
                             }
                         }
                     } else if ((rule == RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET)
                             || (rule == RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET)) {
                         // "capture preset"-base rule
                         if (criterion.mAttr.getCapturePreset() == attrToMatch.getCapturePreset()) {
                             if (criterion.mRule == rule) {
                              // rule already exists, we're done
                                 return this;
                             } else {
                                 // criterion already exists with a another rule, it is incompatible
                                 throw new IllegalArgumentException("Contradictory rule exists for "
                                         + attrToMatch);
                             }
                         }
                     }
                 }
                 // rule didn't exist, add it
                 mCriteria.add(new AttributeMatchCriterion(attrToMatch, rule));
             }
             return this;
         }

         Builder addRuleFromParcel(Parcel in) throws IllegalArgumentException {
             int rule = in.readInt();
             AudioAttributes attr;
             if ((rule == RULE_MATCH_ATTRIBUTE_USAGE) || (rule == RULE_EXCLUDE_ATTRIBUTE_USAGE)) {
                 int usage = in.readInt();
                 attr = new AudioAttributes.Builder()
                         .setUsage(usage).build();
             } else if ((rule == RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET)
                     || (rule == RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET)) {
                 int preset = in.readInt();
                 attr = new AudioAttributes.Builder()
                         .setInternalCapturePreset(preset).build();
             } else {
                 in.readInt(); // assume there was in int value to read as for now they come in pair
                 throw new IllegalArgumentException("Illegal rule value " + rule + " in parcel");
             }
             return addRuleInt(attr, rule);
         }

         /**
          * Combines all of the matching and exclusion rules that have been set and return a new
          * {@link AudioMixingRule} object.
          * @return a new {@link AudioMixingRule} object
          */
         public AudioMixingRule build() {
             return new AudioMixingRule(mTargetMixType, mCriteria);
         }
     }
 }
	/*
	* Copyright (C) 2014 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.media.audiopolicy;

	import android.annotation.SystemApi;
	import android.media.AudioAttributes;
	import android.os.Parcel;

	import java.util.ArrayList;
	import java.util.Iterator;
	import java.util.Objects;


	/**
	* @hide
	*
	* Here's an example of creating a mixing rule for all media playback:
	* <pre>
	* AudioAttributes mediaAttr = new AudioAttributes.Builder()
	* .setUsage(AudioAttributes.USAGE_MEDIA)
	* .build();
	* AudioMixingRule mediaRule = new AudioMixingRule.Builder()
	* .addRule(mediaAttr, AudioMixingRule.RULE_MATCH_ATTRIBUTE_USAGE)
	* .build();
	* </pre>
	*/
	@SystemApi
	public class AudioMixingRule {

	private AudioMixingRule(int mixType, ArrayList<AttributeMatchCriterion> criteria) {
	mCriteria = criteria;
	mTargetMixType = mixType;
	}

	/**
	* A rule requiring the usage information of the {@link AudioAttributes} to match.
	*/
	@SystemApi
	public static final int RULE_MATCH_ATTRIBUTE_USAGE = 0x1;
	/**
	* A rule requiring the capture preset information of the {@link AudioAttributes} to match.
	*/
	@SystemApi
	public static final int RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET = 0x1 << 1;

	private final static int RULE_EXCLUSION_MASK = 0x8000;
	/**
	* @hide
	* A rule requiring the usage information of the {@link AudioAttributes} to differ.
	*/
	public static final int RULE_EXCLUDE_ATTRIBUTE_USAGE =
	RULE_EXCLUSION_MASK \| RULE_MATCH_ATTRIBUTE_USAGE;
	/**
	* @hide
	* A rule requiring the capture preset information of the {@link AudioAttributes} to differ.
	*/
	public static final int RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET =
	RULE_EXCLUSION_MASK \| RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET;

	static final class AttributeMatchCriterion {
	AudioAttributes mAttr;
	int mRule;

	/** input parameters must be valid */
	AttributeMatchCriterion(AudioAttributes attributes, int rule) {
	mAttr = attributes;
	mRule = rule;
	}

	@Override
	public int hashCode() {
	return Objects.hash(mAttr, mRule);
	}

	void writeToParcel(Parcel dest) {
	dest.writeInt(mRule);
	if ((mRule == RULE_MATCH_ATTRIBUTE_USAGE) \|\| (mRule == RULE_EXCLUDE_ATTRIBUTE_USAGE)) {
	dest.writeInt(mAttr.getUsage());
	} else {
	// capture preset rule
	dest.writeInt(mAttr.getCapturePreset());
	}
	}
	}

	private final int mTargetMixType;
	int getTargetMixType() { return mTargetMixType; }
	private final ArrayList<AttributeMatchCriterion> mCriteria;
	ArrayList<AttributeMatchCriterion> getCriteria() { return mCriteria; }

	@Override
	public int hashCode() {
	return Objects.hash(mTargetMixType, mCriteria);
	}

	private static boolean isValidSystemApiRule(int rule) {
	switch(rule) {
	case RULE_MATCH_ATTRIBUTE_USAGE:
	case RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET:
	return true;
	default:
	return false;
	}
	}

	private static boolean isValidIntRule(int rule) {
	switch(rule) {
	case RULE_MATCH_ATTRIBUTE_USAGE:
	case RULE_EXCLUDE_ATTRIBUTE_USAGE:
	case RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET:
	case RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET:
	return true;
	default:
	return false;
	}
	}

	private static boolean isPlayerRule(int rule) {
	return ((rule == RULE_MATCH_ATTRIBUTE_USAGE)
	\|\| (rule == RULE_EXCLUDE_ATTRIBUTE_USAGE));
	}

	/**
	* Builder class for {@link AudioMixingRule} objects
	*/
	@SystemApi
	public static class Builder {
	private ArrayList<AttributeMatchCriterion> mCriteria;
	private int mTargetMixType = AudioMix.MIX_TYPE_INVALID;

	/**
	* Constructs a new Builder with no rules.
	*/
	@SystemApi
	public Builder() {
	mCriteria = new ArrayList<AttributeMatchCriterion>();
	}

	/**
	* Add a rule for the selection of which streams are mixed together.
	* @param attrToMatch a non-null AudioAttributes instance for which a contradictory
	* rule hasn't been set yet.
	* @param rule {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE} or
	* {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET}.
	* @return the same Builder instance.
	* @throws IllegalArgumentException
	*/
	@SystemApi
	public Builder addRule(AudioAttributes attrToMatch, int rule)
	throws IllegalArgumentException {
	if (!isValidSystemApiRule(rule)) {
	throw new IllegalArgumentException("Illegal rule value " + rule);
	}
	return addRuleInt(attrToMatch, rule);
	}

	/**
	* Add a rule by exclusion for the selection of which streams are mixed together.
	* <br>For instance the following code
	* <br><pre>
	* AudioAttributes mediaAttr = new AudioAttributes.Builder()
	* .setUsage(AudioAttributes.USAGE_MEDIA)
	* .build();
	* AudioMixingRule noMediaRule = new AudioMixingRule.Builder()
	* .excludeRule(mediaAttr, AudioMixingRule.RULE_MATCH_ATTRIBUTE_USAGE)
	* .build();
	* </pre>
	* <br>will create a rule which maps to any usage value, except USAGE_MEDIA.
	* @param attrToMatch a non-null AudioAttributes instance for which a contradictory
	* rule hasn't been set yet.
	* @param rule {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE} or
	* {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET}.
	* @return the same Builder instance.
	* @throws IllegalArgumentException
	*/
	@SystemApi
	public Builder excludeRule(AudioAttributes attrToMatch, int rule)
	throws IllegalArgumentException {
	if (!isValidSystemApiRule(rule)) {
	throw new IllegalArgumentException("Illegal rule value " + rule);
	}
	return addRuleInt(attrToMatch, rule \| RULE_EXCLUSION_MASK);
	}

	/**
	* Add or exclude a rule for the selection of which streams are mixed together.
	* @param attrToMatch a non-null AudioAttributes instance for which a contradictory
	* rule hasn't been set yet.
	* @param rule one of {@link AudioMixingRule#RULE_EXCLUDE_ATTRIBUTE_USAGE},
	* {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE},
	* {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET} or
	* {@link AudioMixingRule#RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET}.
	* @return the same Builder instance.
	* @throws IllegalArgumentException
	*/
	Builder addRuleInt(AudioAttributes attrToMatch, int rule)
	throws IllegalArgumentException {
	if (attrToMatch == null) {
	throw new IllegalArgumentException("Illegal null AudioAttributes argument");
	}
	if (!isValidIntRule(rule)) {
	throw new IllegalArgumentException("Illegal rule value " + rule);
	} else {
	// as rules are added to the Builder, we verify they are consistent with the type
	// of mix being built. When adding the first rule, the mix type is MIX_TYPE_INVALID.
	if (mTargetMixType == AudioMix.MIX_TYPE_INVALID) {
	if (isPlayerRule(rule)) {
	mTargetMixType = AudioMix.MIX_TYPE_PLAYERS;
	} else {
	mTargetMixType = AudioMix.MIX_TYPE_RECORDERS;
	}
	} else if (((mTargetMixType == AudioMix.MIX_TYPE_PLAYERS) && !isPlayerRule(rule))
	\|\| ((mTargetMixType == AudioMix.MIX_TYPE_RECORDERS) && isPlayerRule(rule)))
	{
	throw new IllegalArgumentException("Incompatible rule for mix");
	}
	}
	synchronized (mCriteria) {
	Iterator<AttributeMatchCriterion> crIterator = mCriteria.iterator();
	while (crIterator.hasNext()) {
	final AttributeMatchCriterion criterion = crIterator.next();
	if ((rule == RULE_MATCH_ATTRIBUTE_USAGE)
	\|\| (rule == RULE_EXCLUDE_ATTRIBUTE_USAGE)) {
	// "usage"-based rule
	if (criterion.mAttr.getUsage() == attrToMatch.getUsage()) {
	if (criterion.mRule == rule) {
	// rule already exists, we're done
	return this;
	} else {
	// criterion already exists with a another rule, it is incompatible
	throw new IllegalArgumentException("Contradictory rule exists for "
	+ attrToMatch);
	}
	}
	} else if ((rule == RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET)
	\|\| (rule == RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET)) {
	// "capture preset"-base rule
	if (criterion.mAttr.getCapturePreset() == attrToMatch.getCapturePreset()) {
	if (criterion.mRule == rule) {
	// rule already exists, we're done
	return this;
	} else {
	// criterion already exists with a another rule, it is incompatible
	throw new IllegalArgumentException("Contradictory rule exists for "
	+ attrToMatch);
	}
	}
	}
	}
	// rule didn't exist, add it
	mCriteria.add(new AttributeMatchCriterion(attrToMatch, rule));
	}
	return this;
	}

	Builder addRuleFromParcel(Parcel in) throws IllegalArgumentException {
	int rule = in.readInt();
	AudioAttributes attr;
	if ((rule == RULE_MATCH_ATTRIBUTE_USAGE) \|\| (rule == RULE_EXCLUDE_ATTRIBUTE_USAGE)) {
	int usage = in.readInt();
	attr = new AudioAttributes.Builder()
	.setUsage(usage).build();
	} else if ((rule == RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET)
	\|\| (rule == RULE_EXCLUDE_ATTRIBUTE_CAPTURE_PRESET)) {
	int preset = in.readInt();
	attr = new AudioAttributes.Builder()
	.setInternalCapturePreset(preset).build();
	} else {
	in.readInt(); // assume there was in int value to read as for now they come in pair
	throw new IllegalArgumentException("Illegal rule value " + rule + " in parcel");
	}
	return addRuleInt(attr, rule);
	}

	/**
	* Combines all of the matching and exclusion rules that have been set and return a new
	* {@link AudioMixingRule} object.
	* @return a new {@link AudioMixingRule} object
	*/
	public AudioMixingRule build() {
	return new AudioMixingRule(mTargetMixType, mCriteria);
	}
	}
	}