Merge "Update API documentation for static AudioTrack"

     * unsigned 32-bits.  That is, the next position after 0x7FFFFFFF is (int) 0x80000000.

     * This is a continuously advancing counter.  It will wrap (overflow) periodically,

     * for example approximately once every 27:03:11 hours:minutes:seconds at 44.1 kHz.

     * It is reset to zero by flush(), reload(), and stop().

     * It is reset to zero by {@link #flush()}, {@link #reloadStaticData()}, and {@link #stop()}.

     * If the track's creation mode is {@link #MODE_STATIC}, the return value indicates

     * the total number of frames played since reset,

     * <i>not</i> the current offset within the buffer.

     */

    public int getPlaybackHeadPosition() {

        return native_get_position();

    /**

     * Sets the period for the periodic notification event.

     * @param periodInFrames update period expressed in frames

     * @param periodInFrames update period expressed in frames.

     * Zero period means no position updates.  A negative period is not allowed.

     * @return error code or success, see {@link #SUCCESS}, {@link #ERROR_INVALID_OPERATION}

     */

    public int setPositionNotificationPeriod(int periodInFrames) {

    /**

     * Sets the playback head position.

     * Sets the playback head position within the static buffer.

     * The track must be stopped or paused for the position to be changed,

     * and must use the {@link #MODE_STATIC} mode.

     * @param positionInFrames playback head position expressed in frames

     * @param positionInFrames playback head position within buffer, expressed in frames.

     * Zero corresponds to start of buffer.

     * The position must not be greater than the buffer size in frames, or negative.

     * Though this method and {@link #getPlaybackHeadPosition()} have similar names,

     * the position values have different meanings.

     * <br>

     * If looping is currently enabled and the new position is greater than or equal to the

     * loop end marker, the behavior varies by API level: for API level 22 and above,

     * the looping is first disabled and then the position is set.

     * For earlier API levels, the behavior is unspecified.

     * @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},

     *    {@link #ERROR_INVALID_OPERATION}

     */

     * Similarly to setPlaybackHeadPosition,

     * the track must be stopped or paused for the loop points to be changed,

     * and must use the {@link #MODE_STATIC} mode.

     * @param startInFrames loop start marker expressed in frames

     * @param startInFrames loop start marker expressed in frames.

     * Zero corresponds to start of buffer.

     * The start marker must not be greater than or equal to the buffer size in frames, or negative.

     * @param endInFrames loop end marker expressed in frames

     * @param endInFrames loop end marker expressed in frames.

     * The total buffer size in frames corresponds to end of buffer.

     * The end marker must not be greater than the buffer size in frames.

     * For looping, the end marker must not be less than or equal to the start marker,

     * but to disable looping

     * it is permitted for start marker, end marker, and loop count to all be 0.

     * @param loopCount the number of times the loop is looped.

     * If any input parameters are out of range, this method returns {@link #ERROR_BAD_VALUE}.

     * If the loop period (endInFrames - startInFrames) is too small for the implementation to

     * support,

     * {@link #ERROR_BAD_VALUE} is returned.

     * The loop range is the interval [startInFrames, endInFrames).

     * <br>

     * For API level 22 and above, the position is left unchanged,

     * unless it is greater than or equal to the loop end marker, in which case

     * it is forced to the loop start marker.

     * For earlier API levels, the effect on position is unspecified.

     * @param loopCount the number of times the loop is looped; must be greater than or equal to -1.

     *    A value of -1 means infinite looping, and 0 disables looping.

     *    A value of positive N means to "loop" (go back) N times.  For example,

     *    a value of one means to play the region two times in total.

     * @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},

     *    {@link #ERROR_INVALID_OPERATION}

     */

    //--------------------

    /**

     * Starts playing an AudioTrack.

     * If track's creation mode is {@link #MODE_STATIC}, you must have called write() prior.

     * If track's creation mode is {@link #MODE_STATIC}, you must have called one of

     * the {@link #write(byte[], int, int)}, {@link #write(short[], int, int)},

     * or {@link #write(float[], int, int, int)} methods.

     * If the mode is {@link #MODE_STREAMING}, you can optionally prime the

     * output buffer by writing up to bufferSizeInBytes (from constructor) before starting.

     * This priming will avoid an immediate underrun, but is not required.

     *

     * @throws IllegalStateException

     */

    }

    /**

     * Notifies the native resource to reuse the audio data already loaded in the native

     * layer, that is to rewind to start of buffer.

     * The track's creation mode must be {@link #MODE_STATIC}.

     * Sets the playback head position within the static buffer to zero,

     * that is it rewinds to start of static buffer.

     * The track must be stopped or paused, and

     * the track's creation mode must be {@link #MODE_STATIC}.

     * <p>

     * For API level 22 and above, also resets the value returned by

     * {@link #getPlaybackHeadPosition()} to zero.

     * For earlier API levels, the reset behavior is unspecified.

     * <p>

     * {@link #setPlaybackHeadPosition(int)} to zero

     * is recommended instead when the reset of {@link #getPlaybackHeadPosition} is not needed.

     * @return error code or success, see {@link #SUCCESS}, {@link #ERROR_BAD_VALUE},

     *  {@link #ERROR_INVALID_OPERATION}

     */