You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: api/common/6/hw-encoding.html
+19-19Lines changed: 19 additions & 19 deletions
Original file line number
Diff line number
Diff line change
@@ -141,17 +141,17 @@ <h2>API Reference</h2>
141
141
<divclass="textblock"><p>When recording video using the <code><aclass="el" href="classgz_1_1common_1_1VideoEncoder.html" title="The VideoEncoder class supports encoding a series of images to a video format, and then writing the v...">gz::common::VideoEncoder</a></code> class, you can opt-in to use hardware (HW) acceleration for the encoding process. By default, only software encoders are used. This tutorial will show how to configure the encoder for HW acceleration and will present ready-made commandlines for some typical use-cases.</p>
142
142
<p>You can either use the <code>VideoEncoder</code> class directly, or you can "meet it" in the video recorder plugin in Gazebo. In both cases, HW-accelerated encoding can be set up.</p>
143
143
<p>HW acceleration should provide you with higher encoding performance, potentially leaving more CPU power to the rest of your program/simulation, while taking a bit of GPU memory (video encoding uses different chips than 3D graphics or CUDA computations, so performance-wise, the rest of the GPU should be unaffected).</p>
<p>The support for HW-accelerated encoding is based on what the local installation of <code>libavcodec</code> (and your hardware) offers. If the libavcodec/FFMpeg your system has doesn't support HW acceleration, you're out of luck until you get a version that supports some. Some information about various aspects of the acceleration support by FFMpeg can be found on their <ahref="https://trac.ffmpeg.org/wiki/HWAccelIntro">HWAccelIntro wiki page</a>.</p>
157
157
<p>If FFMpeg is correctly installed, you can see the available HW encoders by calling <code>ffmpeg -hide_banner -encoders | grep 264</code>.</p>
<p>The last thing you need to decide is whether the selected encoder should use a HW surface (pixel buffer) or the default CPU-located one. With most encoders, this is just a performance issue and they will work both with CPU and GPU surfaces.</p>
220
220
<p>It is best if you perform experiments with HW surface used and not used and compare the performance. Select the one that suits your use case better.</p>
Putting it together - configuration via environment variables</h2>
223
223
<p>To ease configuration of the HW-accelerated encoding, there doesn't have to be explicit support for it in the code using <code>VideoEncoder</code>. The code may concentrate on implementing the recording procedure itself, and completely ignore any HW acceleration of the recording process. Users of the code can then enable the HW acceleration just using these 3 environment variables:</p>
<p>This is the main variable that allows the <code>VideoEncoder</code> to probe for supported HW-accelerated encoders. It is a colon-separated list of names described in the table above. Example: <code>GZ_VIDEO_ALLOWED_ENCODERS=NVENC:QSV</code>. Special value <code>ALL</code> means that all encoders should be tried. Special value <code>NONE</code> (or empty value) means that a SW encoder should be used.</p>
227
227
<p>If more values are specified, the system will probe all the allowed encoders trying to start them up (if device is specified, then only with the given device). The first allowed encoder that successfully finishes the probe will be used.</p>
228
228
<p>The probing mechanism isn't 100% reliable. But it does what's reasonable to do in such an autodetection loop - it checks whether the required/supported device files exist, and if they do (or if there are no device files, as on Windows), the library tries to create an encoding context. If the context is successfully created, the encoder is considered working. Sometimes, something can go wrong in a later stage (e.g. insufficient GPU memory), and that is a kind of thing you have to handle yourself.</p>
<p>This is a name of the encoder device as specified in the "Device Names" section. If empty, first working device will be used. This auto detection should suffice on single-GPU systems or if you don't care which GPU will be used. If a device is specified, only encoders accepting this device name as an argument will be probed.</p>
<li>empty: Let the library guess based on some pre-compiled hints.</li>
239
239
</ul>
240
240
<p>Refer to section "Using HW surface" for more in-depth description of the meaning of this variable. Usually, leaving it empty should be just fine.</p>
<p>These values can also be configured in code.</p>
244
244
<p>As stated earlier, if you use the standard 6-argument signature of <code>VideoEncoder::Start()</code>, configuration via the above described environment variables will be performed.</p>
</div><!-- fragment --><p>The three added arguments correspond to the environment variables, but with this signature you can set their values from code (and environment variables will have no effect then). This would be useful if you want to e.g. implement a GUI chooser for the acceleration.</p>
255
255
<p>The <code>FlagSet<HWEncoderType></code> captures a set of allowed encoders. Its value may be e.g. <code>gz::Common::HWEncoderType::QSV | gz::common::HWEncoderType::NVENC</code>.</p>
<p>To make sure you configured the HW acceleration right, you may look at info-level messages where <code>VideoEncoder</code> documents the detected encoder. It may look like:</p>
<divclass="line">[GUI] [Msg] Using encoder libx264</div>
295
-
</div><!-- fragment --><h1><aclass="anchor" id="autotoc_md13"></a>
295
+
</div><!-- fragment --><h1><aclass="anchor" id="examples"></a>
296
296
Examples</h1>
297
297
<p>Here are a few ready-made examples which might or might not work for you right-away. Just give them a try and dig deeper in the configuration if something is wrong.</p>
<p>The current distribution of FFMpeg via Conda for Windows does not include the h264_qsv encoder. It only has h264_nvenc. This means that using Intel GPUs for HW acceleration is not possible out of the box. A possible solution would be to build a custom build of ffmpeg in the workspace with gz-common. Pull requests with the relevant tutorial are welcome.</p>
<p>If you have a multi-GPU station with desktop-class (not server-class) GPUs, you will run into an artificial limitation from NVidia. You can only run 3 concurrent encoding sessions on one computer, no matter how many GPUs you have. The computer can even have 8 GPUs, but you will only be able to encode 3 videos at a time. The exact maxima of encoding sessions are described in <ahref="https://developer.nvidia.com/video-encode-and-decode-gpu-support-matrix-new">this NVidia support page</a>.</p>
318
318
<p>To make things worse, there is no API that would tell you the number of currently running NVEnc sessions. The only way to find out you're launching the fourth is trying to start encoding and getting a memory allocation error. This library catches this error and writes a lengthy description of what might have just happened (either really low memory or this artificial limit). Unfortunately, when you start the doomed fourth encoding session, all the three "legal" sessions will crash. This might be really troublesome on e.g. multi-user systems when you don't even know which jobs of the other users are using NVEnc.</p>
Copy file name to clipboardExpand all lines: api/common/6/index.html
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -139,7 +139,7 @@ <h2>API Reference</h2>
139
139
</div><!--header-->
140
140
<divclass="contents">
141
141
<divclass="textblock"><p><aclass="anchor" id="md_api"></a> Gazebo Common is a component in Gazebo, a set of libraries designed to rapidly develop robot and simulation applications.</p>
142
-
<h1><aclass="anchor" id="autotoc_md1"></a>
142
+
<h1><aclass="anchor" id="license"></a>
143
143
License</h1>
144
144
<p>The code associated with this documentation is licensed under an <ahref="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0 License</a>.</p>
145
145
<p>This documentation is licensed under a <ahref="http://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>. </p>
Copy file name to clipboardExpand all lines: api/common/6/install.html
+13-13Lines changed: 13 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -142,29 +142,29 @@ <h2>API Reference</h2>
142
142
<p>These instructions are for installing only Gazebo Common. If you're interested in using all the Gazebo libraries, check out this <ahref="https://gazebosim.org/docs/latest/install">Gazebo installation</a>.</p>
143
143
<p>We recommend following the Binary Installation instructions to get up and running as quickly and painlessly as possible.</p>
144
144
<p>The Source Installation instructions should be used if you need the very latest software improvements, you need to modify the code, or you plan to make a contribution.</p>
<p>On Ubuntu systems, <code>apt-get</code> can be used to install <code>gz-common</code>: </p><divclass="fragment"><divclass="line">sudo apt install libgz-common<#>-dev</div>
150
150
</div><!-- fragment --><p>Be sure to replace <code><#></code> with a number value, such as 2 or 3, depending on which version you need.</p>
<p>First, follow the <ahref="https://github.com/gazebosim/gz-cmake">gz-cmake</a> tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment.</p>
193
193
<p>Navigate to <code>condabin</code> if necessary to use the <code>conda</code> command (i.e., if Conda is not in your <code>PATH</code> environment variable. You can find the location of <code>condabin</code> in Anaconda Prompt, <code>where conda</code>).</p>
</div><!-- fragment --><p>Install Gazebo dependencies:</p>
197
197
<p>You can view available versions and their dependencies: </p><divclass="fragment"><divclass="line">conda search libgz-common* --channel conda-forge --info</div>
198
198
</div><!-- fragment --><p>Install dependencies, replacing <code><#></code> with the desired versions: </p><divclass="fragment"><divclass="line">conda install libgz-cmake<#> libgz-math<#> --channel conda-forge</div>
199
-
</div><!-- fragment --><h2><aclass="anchor" id="autotoc_md28"></a>
199
+
</div><!-- fragment --><h2><aclass="anchor" id="build-from-source"></a>
200
200
Build from Source</h2>
201
-
<h3><aclass="anchor" id="autotoc_md29"></a>
201
+
<h3><aclass="anchor" id="ubuntu-1"></a>
202
202
Ubuntu</h3>
203
203
<oltype="1">
204
204
<li>Clone the repository <divclass="fragment"><divclass="line">git clone https://github.com/gazebosim/gz-common</div>
<li>View the documentation by running the following command from the build directory. <divclass="fragment"><divclass="line">firefox doxygen/html/index.html</div>
264
264
</div><!-- fragment --></li>
265
265
</ol>
266
-
<h1><aclass="anchor" id="autotoc_md33"></a>
266
+
<h1><aclass="anchor" id="testing"></a>
267
267
Testing</h1>
268
268
<p>Follow these steps to run tests and static code analysis in your clone of this repository.</p>
0 commit comments