/* * Copyright (c) 1999-2000, Eric Moon. * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions, and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions, and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * 3. The name of the author may not be used to endorse or promote products * derived from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR * TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ // AudioFilterNode.h // * PURPOSE // A framework class designed to make it easy to develop simple // audio filters in the BeOS Media Kit. The actual DSP work // is done externally by an IAudioOp object. // // * NOT SUPPORTED YET... // - multiple inputs or outputs // - chaining multiple operations (yum) // // * HISTORY // e.moon 7sep99 Begun: abstracting from FlangerNode and // implementing IAudioOp. #ifndef __AudioFilterNode_H__ #define __AudioFilterNode_H__ #include <BufferProducer.h> #include <BufferConsumer.h> #include <Controllable.h> #include <Debug.h> #include <MediaEventLooper.h> #include "IAudioOpHost.h" // forwards class BBufferGroup; class BMediaAddOn; class AudioBuffer; class IAudioOpFactory; class IAudioOp; class IParameterSet; class AudioFilterNode : public BBufferConsumer, public BBufferProducer, public BControllable, public BMediaEventLooper, public IAudioOpHost { public: // *** HOOKS // *** FORMAT NEGOTIATION // +++++ 8sep99: there's currently no differentiation made between input // and output formats. there probably should be, though for // now you can do extra format restriction in your factory's // createOp() implementation... which is too late. // +++++ // +++++ okay, time to split out into getRequiredInputFormat(), ... etc // subclasses allowing format conversion will need to restrict buffer // sizes based on current connection (input or output.) // requests the required format for the given type (ioFormat.type must be // filled in!) // upon returning, any fields left as wildcards are negotiable. // Default implementation hands off to getPreferredFormat(), // yielding a rather strict node. virtual status_t getRequiredInputFormat( media_format& ioFormat) { return getPreferredInputFormat(ioFormat); } virtual status_t getRequiredOutputFormat( media_format& ioFormat) { return getPreferredOutputFormat(ioFormat); } // requests the required format for the given type (ioFormat.type must be // filled in!) // upon returning, all fields must be filled in. // // Default raw audio format: // 44100hz // host-endian // 1 channel // float // 1k buffers // virtual status_t getPreferredInputFormat( media_format& ioFormat); virtual status_t getPreferredOutputFormat( media_format& ioFormat); // test the given template format against a proposed format. // specialize wildcards for fields where the template contains // non-wildcard data; write required fields into proposed format // if they mismatch. // Returns B_OK if the proposed format doesn't conflict with the // template, or B_MEDIA_BAD_FORMAT otherwise. virtual status_t validateProposedInputFormat( const media_format& preferredFormat, media_format& ioProposedFormat); virtual status_t validateProposedOutputFormat( const media_format& preferredFormat, media_format& ioProposedFormat); // fill in wildcards in the given format. // (assumes the format passes validateProposedFormat().) // Default implementation: specializes all wildcards to format returned by // getPreferredXXXFormat() virtual void specializeInputFormat( media_format& ioFormat) { media_format preferred; preferred.type = B_MEDIA_RAW_AUDIO; #ifdef DEBUG status_t err = #endif getPreferredInputFormat(preferred); ASSERT(err == B_OK); _specialize_raw_audio_format(preferred, ioFormat); } virtual void specializeOutputFormat( media_format& ioFormat) { char fmt_buffer[256]; string_for_format(ioFormat, fmt_buffer, 255); PRINT(( "### specializeOutputFormat:\n" " given '%s'\n", fmt_buffer)); media_format preferred; preferred.type = B_MEDIA_RAW_AUDIO; #ifdef DEBUG status_t err = #endif getPreferredOutputFormat(preferred); ASSERT(err == B_OK); string_for_format(preferred, fmt_buffer, 255); PRINT(( " pref '%s'\n", fmt_buffer)); // ioFormat.SpecializeTo(&preferred); _specialize_raw_audio_format(preferred, ioFormat); string_for_format(ioFormat, fmt_buffer, 255); PRINT(( " writing '%s'\n", fmt_buffer)); } public: // *** ctor/dtor virtual ~AudioFilterNode(); // the node acquires ownership of opFactory AudioFilterNode( const char* name, IAudioOpFactory* opFactory, BMediaAddOn* addOn=0); public: // *** accessors const media_input& input() const { return m_input; } const media_output& output() const { return m_output; } public: // *** BMediaNode virtual status_t HandleMessage( int32 code, const void* data, size_t size); virtual BMediaAddOn* AddOn( int32* outID) const; virtual void SetRunMode( run_mode mode); protected: // *** BMediaEventLooper virtual void HandleEvent( const media_timed_event* event, bigtime_t howLate, bool realTimeEvent=false); // "The Media Server calls this hook function after the node has // been registered. This is derived from BMediaNode; BMediaEventLooper // implements it to call Run() automatically when the node is registered; // if you implement NodeRegistered() you should call through to // BMediaEventLooper::NodeRegistered() after you've done your custom // operations." virtual void NodeRegistered(); // "Augment OfflineTime() to compute the node's current time; it's called // by the Media Kit when it's in offline mode. Update any appropriate // internal information as well, then call through to the BMediaEventLooper // implementation." virtual bigtime_t OfflineTime(); //nyi public: // *** BBufferConsumer virtual status_t AcceptFormat( const media_destination& destination, media_format* ioFormat); // "If you're writing a node, and receive a buffer with the B_SMALL_BUFFER // flag set, you must recycle the buffer before returning." virtual void BufferReceived( BBuffer* buffer); // * make sure to fill in poInput->format with the contents of // pFormat; as of R4.5 the Media Kit passes poInput->format to // the producer in BBufferProducer::Connect(). virtual status_t Connected( const media_source& source, const media_destination& destination, const media_format& format, media_input* outInput); virtual void Disconnected( const media_source& source, const media_destination& destination); virtual void DisposeInputCookie( int32 cookie); // "You should implement this function so your node will know that the data // format is going to change. Note that this may be called in response to // your AcceptFormat() call, if your AcceptFormat() call alters any wildcard // fields in the specified format. // // Because FormatChanged() is called by the producer, you don't need to (and // shouldn't) ask it if the new format is acceptable. // // If the format change isn't possible, return an appropriate error from // FormatChanged(); this error will be passed back to the producer that // initiated the new format negotiation in the first place." virtual status_t FormatChanged( const media_source& source, const media_destination& destination, int32 changeTag, const media_format& newFormat); virtual status_t GetLatencyFor( const media_destination& destination, bigtime_t* outLatency, media_node_id* outTimeSource); virtual status_t GetNextInput( int32* ioCookie, media_input* outInput); virtual void ProducerDataStatus( const media_destination& destination, int32 status, bigtime_t tpWhen); // "This function is provided to aid in supporting media formats in which the // outer encapsulation layer doesn't supply timing information. Producers will // tag the buffers they generate with seek tags; these tags can be used to // locate key frames in the media data." virtual status_t SeekTagRequested( const media_destination& destination, bigtime_t targetTime, uint32 flags, media_seek_tag* outSeekTag, bigtime_t* outTaggedTime, uint32* outFlags); public: // *** BBufferProducer // "When a consumer calls BBufferConsumer::RequestAdditionalBuffer(), this // function is called as a result. Its job is to call SendBuffer() to // immediately send the next buffer to the consumer. The previousBufferID, // previousTime, and previousTag arguments identify the last buffer the // consumer received. Your node should respond by sending the next buffer // after the one described. // // The previousTag may be NULL. // Return B_OK if all is well; otherwise return an appropriate error code." virtual void AdditionalBufferRequested( const media_source& source, media_buffer_id previousBufferID, bigtime_t previousTime, const media_seek_tag* previousTag); //nyi virtual void Connect( status_t status, const media_source& source, const media_destination& destination, const media_format& format, char* ioName); virtual void Disconnect( const media_source& source, const media_destination& destination); virtual status_t DisposeOutputCookie( int32 cookie); virtual void EnableOutput( const media_source& source, bool enabled, int32* _deprecated_); virtual status_t FormatChangeRequested( const media_source& source, const media_destination& destination, media_format* ioFormat, int32* _deprecated_); //nyi virtual status_t FormatProposal( const media_source& source, media_format* ioFormat); virtual status_t FormatSuggestionRequested( media_type type, int32 quality, media_format* outFormat); virtual status_t GetLatency( bigtime_t* outLatency); virtual status_t GetNextOutput( int32* ioCookie, media_output* outOutput); // "This hook function is called when a BBufferConsumer that's receiving data // from you determines that its latency has changed. It will call its // BBufferConsumer::SendLatencyChange() function, and in response, the Media // Server will call your LatencyChanged() function. The source argument // indicates your output that's involved in the connection, and destination // specifies the input on the consumer to which the connection is linked. // newLatency is the consumer's new latency. The flags are currently unused." virtual void LatencyChanged( const media_source& source, const media_destination& destination, bigtime_t newLatency, uint32 flags); virtual void LateNoticeReceived( const media_source& source, bigtime_t howLate, bigtime_t tpWhen); // PrepareToConnect() is the second stage of format negotiations that happens // inside BMediaRoster::Connect(). At this point, the consumer's AcceptFormat() // method has been called, and that node has potentially changed the proposed // format. It may also have left wildcards in the format. PrepareToConnect() // *must* fully specialize the format before returning! virtual status_t PrepareToConnect( const media_source& source, const media_destination& destination, media_format* ioFormat, media_source* outSource, char* outName); virtual status_t SetBufferGroup( const media_source& source, BBufferGroup* group); virtual status_t SetPlayRate( int32 numerator, int32 denominator); virtual status_t VideoClippingChanged( const media_source& source, int16 numShorts, int16* clipData, const media_video_display_info& display, int32* outFromChangeTag); public: // *** BControllable virtual status_t GetParameterValue( int32 id, bigtime_t* outLastChangeTime, void* outValue, size_t* ioSize); virtual void SetParameterValue( int32 id, bigtime_t changeTime, const void* value, size_t size); public: // *** IAudioOpHost virtual IParameterSet* parameterSet() const; protected: // HandleEvent() impl. void handleParameterEvent( const media_timed_event* event); void handleStartEvent( const media_timed_event* event); void handleStopEvent( const media_timed_event* event); void ignoreEvent( const media_timed_event* event); protected: // *** internal operations status_t prepareFormatChange( const media_format& newFormat); void doFormatChange( const media_format& newFormat); // create and register a parameter web // +++++ 7sep99: hand off to IParameterSet::makeGroup() virtual void initParameterWeb(); // [re-]initialize operation if necessary virtual void updateOperation(); // create or discard buffer group if necessary virtual void updateBufferGroup(); // // construct delay line if necessary, reset filter state // virtual void initFilter(); // // virtual void startFilter(); // virtual void stopFilter(); // figure processing latency by doing 'dry runs' of processBuffer() virtual bigtime_t calcProcessingLatency(); // filter buffer data; inputBuffer and outputBuffer may be the same virtual void processBuffer( BBuffer* inputBuffer, BBuffer* outputBuffer); status_t _validate_raw_audio_format( const media_format& preferredFormat, media_format& ioProposedFormat); void _specialize_raw_audio_format( const media_format& templateFormat, media_format& ioFormat); private: // *** connection/format members // +++++ expose input & output to subclasses [8sep99] // Connections & associated state variables media_input m_input; media_output m_output; bool m_outputEnabled; // Time required by downstream consumer(s) to properly deliver a buffer bigtime_t m_downstreamLatency; // Worst-case time needed to fill a buffer bigtime_t m_processingLatency; // buffer group for on-the-fly conversion [8sep99] // (only created when necessary, ie. more data going out than coming in) BBufferGroup* m_bufferGroup; private: // *** parameters IParameterSet* m_parameterSet; private: // *** operations IAudioOpFactory* m_opFactory; // the current operation IAudioOp* m_op; private: // *** add-on stuff // host add-on BMediaAddOn* m_addOn; }; #endif /*__AudioFilterNode_H__*/
