nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BMediaNode_Overview.html

107 lines
15 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - System Overview - The Media Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheMediaKit_Overview.html" title="The Media Kit" /><link rel="prev" href="BMediaFormats_Overview.html" title="BMediaFormats" /><link rel="next" href="BMediaRoster_Overview.html" title="BMediaRoster" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BMediaFormats_Overview.html" title="BMediaFormats"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheMediaKit_Overview.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BMediaRoster_Overview.html" title="BMediaRoster"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - System Overview - The Media Kit</div></div><div id="headerB">Prev: <a href="BMediaFormats_Overview.html">BMediaFormats</a>  Up: <a href="TheMediaKit_Overview.html">The Media Kit</a>  Next: <a href="BMediaRoster_Overview.html">BMediaRoster</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaNode_Overview"></a>BMediaNode</h2></div></div></div><a id="id586721" class="indexterm"></a><p>The <a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>
class is the superclass of all participant nodes in the
Media Kit. However, you'll never derive directly from
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>;
instead, you'll derive from one of the system interface classes which in
turn are derived from
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a>.
Look at the documentation for those other classes (such as
<a class="link" href="BBufferProducer.html" title="BBufferProducer"><code class="classname">BBufferProducer</code></a> and
<a class="link" href="BBufferConsumer.html" title="BBufferConsumer"><code class="classname">BBufferConsumer</code></a>) for details
on how they're used, or see
"<a class="xref" href="TheMediaKit_Overview_Introduction.html#TheMediaKit_CreatingNewNodeClasses" title="Creating New Node Classes">Creating New Node Classes</a>" for
discussion on how this is done.</p><p>Because of the quirks of virtual inheritance (required by the use of
multiple inheritance), your node's constructor will have to call the
<a class="link" href="BMediaNode.html" title="BMediaNode"><code class="classname">BMediaNode</code></a> constructor.
See "<a class="xref" href="TheMediaKit_Overview_Introduction.html#TheMediaKit_AboutMultipleVirtualInheritance" title="About Multiple Virtual Inheritance">About Multiple Virtual Inheritance</a>".</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Applications shouldn't call a node's member functions directly;
instead, you call the
<a class="link" href="BMediaRoster.html" title="BMediaRoster"><code class="classname">BMediaRoster</code></a>
with a reference to the node and let
the request come to the node through the control port. The only exception
is if the node is subclassed directly within the application, in which case
<a class="link" href="BMediaNode.html#BMediaNode_Acquire" title="Acquire(), Release()"><code class="methodname">Acquire()</code></a>,
<a class="link" href="BMediaNode.html#BMediaNode_ID" title="ID()"><code class="methodname">ID()</code></a>,
<a class="link" href="BMediaNode.html#BMediaNode_Node" title="Node()"><code class="methodname">Node()</code></a>,
and <a class="link" href="BMediaNode.html#BMediaNode_Release"><code class="methodname">Release()</code></a>
can be called directly once
the node is registered—if you do this, be sure you don't call them
after the node is destroyed.</p></div></div></div><p>Calling a node's member functions directly from outside the node itself
can result in the chain of functions involved in coordinating nodes to be
called out of order. Worse, deadlock can result. So just don't do it,
even if you think you've found a safe way to pull it off.</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id586862"></a>Creating Your Own Node</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id586868"></a>Realtime Allocators and Thread Locking</h4></div></div></div><p>Media nodes are highly timing-sensitive creatures. The slightest delay in
performing their work can cause drastic problems in media playback or
recording quality. Virtual memory, normally of great benefit to users,
can work against them when doing media work. A poorly-timed virtual
memory hit can cause breaks in media performances.</p><p>The realtime memory allocation and locking functions provide a means for
nodes to lock down their memory to prevent it from being cached to disk
by the virtual memory system. This avoids situations in which the node
has to pause while it or its memory is fetched back from the swap file.</p><p>The user can use the Media preference application to configure what types
of nodes should use locked memory. Nodes should typically use the
realtime memory allocation functions instead of
<code class="function">malloc()</code> and <code class="function">free()</code>.
<a class="link" href="TheMediaKit_RealTimeFunctions.html#rtm_alloc" title="rtm_alloc(), rtm_realloc()"><code class="function">rtm_alloc()</code></a>
will automatically handle locking the memory if the
<code class="constant">B_MEDIA_REALTIME_ALLOCATOR</code> flag is set, so your node doesn't have to
worry about it.</p><p>In addition, if the realtime flag corresponding to the type of node
you're writing is set, your node should also call
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_thread" title="media_realtime_init_thread()"><code class="function">media_realtime_init_thread()</code></a>
to lock down the stacks of its threads.
Properly-written nodes can always call
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_thread" title="media_realtime_init_thread()"><code class="function">media_realtime_init_thread()</code></a>,
without checking the realtime flags, because this function will return
<code class="constant">B_MEDIA_REALTIME_DISABLED</code> if the corresponding flag isn't set. You can
simply ignore the error and move on.</p><p>For example:</p><pre class="programlisting example cpp"><span class="type">int32 *</span><code class="varname">myThreadData</code> = <code class="function">rtm_alloc</code>(4096);
<code class="varname">myThread</code> = <code class="function">spawn_thread</code>(<code class="function">myThreadFunction</code>, "Node Thread",
<code class="constant">B_NORMAL_PRIORITY</code>, &amp;<code class="varname">myThreadData</code>);
<span class="type">status_t</span> <code class="varname">err</code> = <code class="function">media_realtime_init_thread</code>(<code class="varname">myThread</code>, 32768,
<code class="constant">B_MEDIA_REALTIME_VIDEO</code>);
if (<code class="varname">err</code> != <code class="constant">B_OK</code> &amp;&amp; <code class="varname">err</code> != <code class="constant">B_MEDIA_REALTIME_DISABLED</code>) {
<code class="function">printf</code>("Can't lock down the thread.n");
}
...</pre><p>If your node requires realtime performance from an add-on or shared
library, you can use the
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_image" title="media_realtime_init_image()"><code class="function">media_realtime_init_image()</code></a>
function to lock down that image in memory. Note, however, that
any uses of <code class="function">malloc()</code> by
that image won't allocate locked memory; you can't control that. Still,
locking down the image itself can help performance even further.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Standard BeOS system libraries are Be's responsibility. If it's
appropriate for them to be locked, they're locked for you. Don't lock
them yourself. Both <code class="filename">libmedia.so</code>
and <code class="filename">libroot.so</code> have
<a class="link" href="TheMediaKit_Functions.html#media_realtime_init_image" title="media_realtime_init_image()"><code class="function">media_realtime_init_image()</code></a>
called on them.</p></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BMediaNode_Overview_NegotiatingAConnection"></a>Negotiating a Connection</h4></div></div></div><p>Establishing a connection between two nodes is a multi-step process. The
nodes need to agree upon a data format they both support before the
connection can even be established.</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h5 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id587092"></a>Special Considerations</h5></div></div></div><p>If the node you're writing could be connected by the system mixer (using
the Audio preference application, for example) as the default output, the
node needs to be as flexible as possible in terms of the formats it
accepts on its free inputs in the
<a class="link" href="BBufferConsumer.html#BBufferConsumer_GetNextInput" title="GetNextInput()"><code class="methodname">GetNextInput()</code></a>
function. The format your node returns from
<a class="link" href="BBufferConsumer.html#BBufferConsumer_GetNextInput" title="GetNextInput()"><code class="methodname">GetNextInput()</code></a>
will be used as the starting poing
in the negotiation process; the more wildcards you support, the better.</p><p>An application that wants to establish a connection between some other
node and your node will determine the format from the inputs into your
node and the outputs from the other node, then call
<a class="link" href="BMediaRoster.html#BMediaRoster_Connect" title="Connect(), Disconnect()"><code class="methodname">BMediaRoster::Connect()</code></a>
with that format.</p><p>If there are any wildcards in the format passed to
<code class="methodname">BMediaRoster::Format()</code>,
the media roster will call
<code class="methodname">BBufferProducer::ProposeFormat()</code>
in the node being connected to your
output node; the producer will specialize the wildcards to construct the
least-specific format that will guarantee that any remaining wildcards
can be specialized by your node without becoming incompatible with the
producer.</p><p>The resulting format may have some wildcards left (or, if the producer is
particularly picky, there may be none at all). The media roster will then
pass this format to your consumer node's
<a class="link" href="BBufferConsumer.html#BBufferConsumer_AcceptFormat" title="AcceptFormat()"><code class="methodname">BBufferConsumer::AcceptFormat()</code></a>
function. This function should be implemented to specialize the remaining
wildcards and return this format, which should describe a specific
format. This format will be used to establish the connection.</p></div></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BMediaFormats_Overview.html">BMediaFormats</a>  Up: <a href="TheMediaKit_Overview.html">The Media Kit</a>  Next: <a href="BMediaRoster_Overview.html">BMediaRoster</a> </div><div id="footerB"><div id="footerBL"><a href="BMediaFormats_Overview.html" title="BMediaFormats"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheMediaKit_Overview.html" title="The Media Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BMediaRoster_Overview.html" title="BMediaRoster"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink