127 lines
5.2 KiB
C++
127 lines
5.2 KiB
C++
// Copyright 2019 The MediaPipe Authors.
|
|
//
|
|
// 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.
|
|
//
|
|
// Defines OutputStream, which allows Calculator implementations to produce
|
|
// outputs, and allows clients to access the results produced by
|
|
// CalculatorGraph.
|
|
|
|
#ifndef MEDIAPIPE_FRAMEWORK_OUTPUT_STREAM_H_
|
|
#define MEDIAPIPE_FRAMEWORK_OUTPUT_STREAM_H_
|
|
|
|
#include <string>
|
|
|
|
#include "absl/base/macros.h"
|
|
#include "mediapipe/framework/packet.h"
|
|
#include "mediapipe/framework/port.h"
|
|
#include "mediapipe/framework/timestamp.h"
|
|
|
|
namespace mediapipe {
|
|
|
|
class OutputStream {
|
|
public:
|
|
OutputStream(const OutputStream&) = delete;
|
|
OutputStream& operator=(const OutputStream&) = delete;
|
|
|
|
// Returns the name of the stream.
|
|
virtual const std::string& Name() const = 0;
|
|
|
|
// Adds a Packet to the output stream. It is CHECKed that the Packet contains
|
|
// the data and a timestamp. The most common way to create such a Packet is
|
|
// "Adopt(ptr).At(timestamp)".
|
|
//
|
|
// The timestamp of the packet must satisfy Timestamp::IsAllowedInStream().
|
|
// If the scheduling policy considers packet timestamps when scheduling
|
|
// calculator nodes, packet timestamps must meet additional requirements:
|
|
// * The timestamp of the packet must be greater than those of the previously
|
|
// added Packets, and not less than NextTimestampBound().
|
|
// * If an OutputStream contains a Packet with the timestamp
|
|
// Timestamp::PreStream() or Timestamp::PostStream(), the packet must be
|
|
// the only packet in the stream.
|
|
// Violation of any of these conditions causes a CHECK-failure.
|
|
//
|
|
// NOTE: AddPacket() cannot report errors via the return value. Instead of a
|
|
// CHECK-failure, a subclass of OutputStream should use a callback function
|
|
// to report errors.
|
|
virtual void AddPacket(const Packet& packet) = 0;
|
|
// Takes an rvalue reference of the packet and moves the packet to the output
|
|
// stream. This AddPacket variant has the exact same logic as the const
|
|
// lvalue reference version except the move behavior.
|
|
virtual void AddPacket(Packet&& packet) = 0;
|
|
|
|
// Syntactic sugar for a common way to add Packets.
|
|
template <typename T>
|
|
void Add(T* ptr, Timestamp timestamp) {
|
|
AddPacket(Adopt(ptr).At(timestamp));
|
|
}
|
|
|
|
// Indicates that the next output will arrive no earlier than a certain
|
|
// timestamp. Calling this method may save memory by not buffering more
|
|
// packets than needed. It is recommended that the Calculator implementation
|
|
// call this method whenever such a bound is available. The argument should
|
|
// either satisfy Timestamp::IsAllowedInStream() or be a value returned by
|
|
// Timestamp::NextAllowedInStream().
|
|
//
|
|
// Rather than calling SetNextTimestampBound(Timestamp::Max()), use
|
|
// Close() below.
|
|
virtual void SetNextTimestampBound(Timestamp timestamp) = 0;
|
|
|
|
// Returns the next timestamp bound.
|
|
virtual Timestamp NextTimestampBound() const = 0;
|
|
|
|
// If a Calculator is guaranteed not to add any more Packets to an
|
|
// OutputStream but may continue processing, it SHOULD call Close()
|
|
// on a stream. An example of this is an audio/video decoder applied to
|
|
// a file containing no audio and thus producing no Packets in the audio
|
|
// output stream. If a downstream Calculator takes both the audio and
|
|
// the video streams as inputs, and the decoder doesn't call Close()
|
|
// on the audio OutputStream, then the framework will buffer all the
|
|
// videos frames while waiting for the possibility that an audio frame
|
|
// will still appear with an early timestamp.
|
|
virtual void Close() = 0;
|
|
|
|
// true iff the OutputStream is closed.
|
|
virtual bool IsClosed() const = 0;
|
|
|
|
// Set the offset. If set, this means any packet which gets output
|
|
// will have a timestamp of at least input_timestamp + offset.
|
|
// The offset may be negative. May be called from Calculator::Open(),
|
|
// but not from Process() nor Close().
|
|
virtual void SetOffset(TimestampDiff offset) = 0;
|
|
|
|
// Returns true iff SetOffset() has been called.
|
|
virtual bool OffsetEnabled() const = 0;
|
|
|
|
// Returns the offset set by the Calculator in the Open() method (returns 0
|
|
// if the offset hasn't been set).
|
|
virtual TimestampDiff Offset() const = 0;
|
|
|
|
// Sets the header for this OutputStream. May be called from
|
|
// Calculator::Open(), but not from Process() nor Close(). This header will
|
|
// be accessible by downstream Calculators via InputStream::Header(). The
|
|
// header's timestamp must be unset.
|
|
virtual void SetHeader(const Packet& packet) = 0;
|
|
|
|
// Returns the header set by the Calculator in the Open() method, or an
|
|
// empty Packet if none was set.
|
|
virtual const Packet& Header() const = 0;
|
|
|
|
protected:
|
|
OutputStream() {}
|
|
virtual ~OutputStream() {}
|
|
};
|
|
|
|
} // namespace mediapipe
|
|
|
|
#endif // MEDIAPIPE_FRAMEWORK_OUTPUT_STREAM_H_
|