From patchwork Mon Jun 12 22:40:41 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mark Thompson X-Patchwork-Id: 3952 Delivered-To: ffmpegpatchwork@gmail.com Received: by 10.103.22.4 with SMTP id 4csp78478vsw; Mon, 12 Jun 2017 15:44:37 -0700 (PDT) X-Received: by 10.28.236.134 with SMTP id h6mr9262111wmi.1.1497307477439; Mon, 12 Jun 2017 15:44:37 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1497307477; cv=none; d=google.com; s=arc-20160816; b=0aOiwn2o+3LysLhmEnX7ncFrvFqzePpGakgUZJPIYXZr6twdLP1yv/KMjgx8iOtvmn FxSzQqhXJcvTMGNRJnbQePvmMUre4oR8FJV46N0XWD1l1ZjDFFDvnCVYjKfcZM52dKLY L9KoyoPsuPPAc9hMgkDIZ/rSoC8mamTZzyQm+WzEb8LoFRNaKgsKmGYhP6w/U71MfKCQ mC5BTuXESMdJn0N3IjVVkMRXSzDnhFk1XikavodC67p30fYGb8dlY8wn1KuGYIUhNSvO 82wmTYkahyfpZIXJCOCgZHiErA2UYE3vwUPHAjbcDKOVCiNwTXtbqOk8kmoLyP8hJCjQ yaNQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:content-transfer-encoding:mime-version:reply-to :list-subscribe:list-help:list-post:list-archive:list-unsubscribe :list-id:precedence:subject:references:in-reply-to:message-id:date :to:from:dkim-signature:delivered-to:arc-authentication-results; bh=keNGhBmuL21EbUWS9rd9w+PjCStfdc7+4wE+X059lNE=; b=naCsd/wzvsQqA/LhgaxvENEJVotj/W9xiIhsalrqdCrJ/dIdGbkMxJcIk+IJkCkkUY q1rsVbDP1I3ZYUQQQWGZxD8VmNvIqWLK8m5I5fGHIDsUCKo8es9wPSfKHnaS8KHya3IL JZ5uExPAdATf/+odM0/CKJoIjPY3EV7HiCGEJV1sQLcSLqQGLVHCprlA7aoWJOb6clFo bqIqgrB5txY7BR0rd+kxhcKWi28C39pHoTkfL+nFdMCtLTXV8lwykDHm30uGqmNz/KfU iGic3Ba4CtnMTdp/iHtjRuzTXtJeejroNpimoGlbV600yo33AFVczYXTgfj3lgLjf22A 9XLg== ARC-Authentication-Results: i=1; mx.google.com; dkim=neutral (body hash did not verify) header.i=@jkqxz-net.20150623.gappssmtp.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org. [79.124.17.100]) by mx.google.com with ESMTP id j34si11274851wra.63.2017.06.12.15.44.37; Mon, 12 Jun 2017 15:44:37 -0700 (PDT) Received-SPF: pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) client-ip=79.124.17.100; Authentication-Results: mx.google.com; dkim=neutral (body hash did not verify) header.i=@jkqxz-net.20150623.gappssmtp.com; spf=pass (google.com: domain of ffmpeg-devel-bounces@ffmpeg.org designates 79.124.17.100 as permitted sender) smtp.mailfrom=ffmpeg-devel-bounces@ffmpeg.org Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 434B068A0D5; Tue, 13 Jun 2017 01:41:21 +0300 (EEST) X-Original-To: ffmpeg-devel@ffmpeg.org Delivered-To: ffmpeg-devel@ffmpeg.org Received: from mail-wr0-f173.google.com (mail-wr0-f173.google.com [209.85.128.173]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 697C668A09B for ; Tue, 13 Jun 2017 01:41:18 +0300 (EEST) Received: by mail-wr0-f173.google.com with SMTP id g76so113432609wrd.1 for ; Mon, 12 Jun 2017 15:41:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jkqxz-net.20150623.gappssmtp.com; s=20150623; h=from:to:subject:date:message-id:in-reply-to:references; bh=iEqphwWFMPGxllAVNPBqMm6Zd8xvihmHFZbtZoNGId4=; b=szbbbXh6EH/kwykmhUCzlltLNqs1Gr078PyGhJ9G7irDOl2XLbrsHrFdO1zJxTeCl0 vzKkKkFNbpotVRm9PwS5sFub9F3BeWd1wh67njNPDx188pyQXb6/oLxRXim5ntqa8R39 HafQhsFl/3SJygCNbVjTzFmgt7clU92l9Gl3fkO6rPjoolWS1cp7W7uweo0PzoW972eK B1hztY+SOOwDpWfHC0jftw97pai4MmY87cxvPnSox5VWDZMuRVyzEVYIgFPMWzWWt7Ef DZ61SN/nDhFbyzeNGmGJE/qTp8khoPMbX4+A47/vw6+GQVxopoRMoiebHR4zjTmi1pgZ l4WQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references; bh=iEqphwWFMPGxllAVNPBqMm6Zd8xvihmHFZbtZoNGId4=; b=rP6uPP5jRqIQx47gJy6dNbbmahKwn9ov0o1gKtXS4R2DzFa+2vYkYgwST6hNHId3fV NVzoWc1hXtWNCZlLrijfZrhWq1uNI2wNfprnAlJrM41ro0KpTUaIfSdEdttCLLFYpiIn r3g/bq4h0G8sVLzLK/8ofO2DoMFv4AlI1Ajtiv1QfpeQWCeo2jehIQlRNL1HK4FBtHBU q1Jxe7SnzTdEQkOVDvwIRlEe2LfhDtqdnAGtDh7PUyqfHqyNvv1Ba8m/YZ05wRWpElTD STlBt+x59nuE0ybTba9/Lz4B8/DaoEKBCDn84WQ2KgWw4vRbs9s6QtF+0Rp3W/d/+Fy3 PODQ== X-Gm-Message-State: AKS2vOz6EWa+zB1igITBhI+mAQ5ETz0S67owrtjY9Tw4kByvgCuz+ZOM 88Nn+rlinKKIUmSXruU= X-Received: by 10.223.136.131 with SMTP id f3mr718040wrf.151.1497307279907; Mon, 12 Jun 2017 15:41:19 -0700 (PDT) Received: from rywe.jkqxz.net (cpc91242-cmbg18-2-0-cust650.5-4.cable.virginm.net. [82.8.130.139]) by smtp.gmail.com with ESMTPSA id m191sm13098233wmg.30.2017.06.12.15.41.19 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 12 Jun 2017 15:41:19 -0700 (PDT) From: Mark Thompson To: ffmpeg-devel@ffmpeg.org Date: Mon, 12 Jun 2017 23:40:41 +0100 Message-Id: <20170612224041.6750-25-sw@jkqxz.net> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20170612224041.6750-1-sw@jkqxz.net> References: <20170612224041.6750-1-sw@jkqxz.net> Subject: [FFmpeg-devel] [PATCH 24/24] doc: Document hwupload, hwdownload and hwmap filters X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches MIME-Version: 1.0 Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" (cherry picked from commit 66aa9b94dae217a0fc5acfb704490707629d95ed) --- doc/filters.texi | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/doc/filters.texi b/doc/filters.texi index 023096f4e0..db0bdfe254 100644 --- a/doc/filters.texi +++ b/doc/filters.texi @@ -9040,6 +9040,104 @@ A floating point number which specifies chroma temporal strength. It defaults to @var{luma_tmp}*@var{chroma_spatial}/@var{luma_spatial}. @end table +@section hwdownload + +Download hardware frames to system memory. + +The input must be in hardware frames, and the output a non-hardware format. +Not all formats will be supported on the output - it may be necessary to insert +an additional @option{format} filter immediately following in the graph to get +the output in a supported format. + +@section hwmap + +Map hardware frames to system memory or to another device. + +This filter has several different modes of operation; which one is used depends +on the input and output formats: +@itemize +@item +Hardware frame input, normal frame output + +Map the input frames to system memory and pass them to the output. If the +original hardware frame is later required (for example, after overlaying +something else on part of it), the @option{hwmap} filter can be used again +in the next mode to retrieve it. +@item +Normal frame input, hardware frame output + +If the input is actually a software-mapped hardware frame, then unmap it - +that is, return the original hardware frame. + +Otherwise, a device must be provided. Create new hardware surfaces on that +device for the output, then map them back to the software format at the input +and give those frames to the preceding filter. This will then act like the +@option{hwupload} filter, but may be able to avoid an additional copy when +the input is already in a compatible format. +@item +Hardware frame input and output + +A device must be supplied for the output, either directly or with the +@option{derive_device} option. The input and output devices must be of +different types and compatible - the exact meaning of this is +system-dependent, but typically it means that they must refer to the same +underlying hardware context (for example, refer to the same graphics card). + +If the input frames were originally created on the output device, then unmap +to retrieve the original frames. + +Otherwise, map the frames to the output device - create new hardware frames +on the output corresponding to the frames on the input. +@end itemize + +The following additional parameters are accepted: + +@table @option +@item mode +Set the frame mapping mode. Some combination of: +@table @var +@item read +The mapped frame should be readable. +@item write +The mapped frame should be writeable. +@item overwrite +The mapping will always overwrite the entire frame. + +This may improve performance in some cases, as the original contents of the +frame need not be loaded. +@item direct +The mapping must not involve any copying. + +Indirect mappings to copies of frames are created in some cases where either +direct mapping is not possible or it would have unexpected properties. +Setting this flag ensures that the mapping is direct and will fail if that is +not possible. +@end table +Defaults to @var{read+write} if not specified. + +@item derive_device @var{type} +Rather than using the device supplied at initialisation, instead derive a new +device of type @var{type} from the device the input frames exist on. + +@item reverse +In a hardware to hardware mapping, map in reverse - create frames in the sink +and map them back to the source. This may be necessary in some cases where +a mapping in one direction is required but only the opposite direction is +supported by the devices being used. + +This option is dangerous - it may break the preceding filter in undefined +ways if there are any additional constraints on that filter's output. +Do not use it without fully understanding the implications of its use. +@end table + +@section hwupload + +Upload system memory frames to hardware surfaces. + +The device to upload to must be supplied when the filter is initialised. If +using ffmpeg, select the appropriate device with the @option{-filter_hw_device} +option. + @anchor{hwupload_cuda} @section hwupload_cuda