Skip to content

Commit

Permalink
Updated readme.
Browse files Browse the repository at this point in the history
  • Loading branch information
kekyo committed Apr 12, 2024
1 parent 5b27b77 commit 678eb26
Show file tree
Hide file tree
Showing 2 changed files with 122 additions and 0 deletions.
62 changes: 62 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -531,6 +531,68 @@ deviceObservable.
// ...
```

## Customize buffer pooling (Advanced topic)

FlashCap has a buffer pooling interface for reused buffers.
It is implemented by the `BufferPool` base class, which extends this class.

The default implementation is the `DefaultBufferPool` class, which is used automatically.
This class is a simple implementation,
but uses weak references to allow the GC to reclaim buffers that are no longer in use.

If you want to replace buffer pooling with your own implementation,
implement the following two abstract methods:

```csharp
// Base class for buffer pooling.
public abstract class BufferPool
{
protected BufferPool()
{ /* ... */ }

// Get the buffer.
public abstract byte[] Rent(int minimumSize);

// Release the buffer.
public abstract void Return(byte[] buffer);
}
```

* The `Rent()` method should return a buffer of the size specified or larger in the argument.
* The `Return()` method should pool to take back the buffer specified in the argument, since it is no longer used.

.NET has GC, the simplest (and non-pooling) implementation would be:

```csharp
public sealed class FakeBufferPool : BufferPool
{
public override byte[] Rent(int minimumSize) =>
// Always generate a buffer.
new byte[minimumSize];

public override void Return(byte[] buffer)
{
// (Unfollow the `buffer` reference and let the GC collect it.)
}
}
```

For example, some of you may know that the .NET Core version `System.Buffers` has an `ArrayPool` class.
By extending `BufferPool`, you can use such an existing buffer pooling implementation or your own implementation.

If you implement your own class in this way, pass it to the constructor of `CaptureDevices` for FlashCap to use:

```csharp
// Create and use a buffer pooling instance.
var bufferPool = new FakeBufferPool();

var devices = new CaptureDevices(bufferPool);

// ...
```

It is used as a common buffer pooling for all devices enumerated from this instance.

## Master for frame processor (Advanced topic)

Welcome to the underground dungeon, where FlashCap's frame processor is a polished gem.
Expand Down
60 changes: 60 additions & 0 deletions README_ja.md
Original file line number Diff line number Diff line change
Expand Up @@ -487,6 +487,66 @@ deviceObservable.
// ...
```

## バッファプーリングのカスタマイズ (Advanced topic)

FlashCapは、再利用されるバッファのための、バッファプーリングインターフェイスを持っています。
これは、`BufferPool` 基底クラスで、このクラスを継承して実装します。

既定の実装は `DefaultBufferPool` クラスで、自動的に使用されます。
このクラスは単純な実装ですが、弱参照を使用して、使われなくなったバッファをGCが回収可能にしています。

バッファプーリングを独自の実装で置き換えたい場合は、以下の2個の抽象メソッドを実装します:

```csharp
// バッファプーリングの基底クラス
public abstract class BufferPool
{
protected BufferPool()
{ /* ... */ }

// バッファを取得する
public abstract byte[] Rent(int minimumSize);

// バッファを解放する
public abstract void Return(byte[] buffer);
}
```

* `Rent()`メソッドは、引数で指定されたサイズ以上のバッファを返す必要があります。
* `Return()`メソッドは、引数で指定されたバッファがもう使われないため、プーリングで引き取るようにします。

.NETにはGCがあるため、最も単純な(かつ、プーリングを行わない)実装は、以下のようになります:

```csharp
public sealed class FakeBufferPool : BufferPool
{
public override byte[] Rent(int minimumSize) =>
// 常に生成
new byte[minimumSize];

public override void Return(byte[] buffer)
{
// (`buffer` 参照を放置して、GCが回収するに任せる)
}
}
```

例えば、.NET Core世代の `System.Buffers` には `ArrayPool` クラスがあることをご存じの方も居るでしょう。
`BufferPool`を拡張することで、このような既存のバッファプーリング実装や、独自の実装を使用することが出来ます。

このようにして独自のクラスを実装した場合は、`CaptureDevices`のコンストラクタに渡して、FlashCapに使用させます:

```csharp
// バッファプーリングインスタンスを生成して使用
var bufferPool = new FakeBufferPool();

var devices = new CaptureDevices(bufferPool);

// ...
```

この`CaptureDevices`のインスタンスから列挙された全てのデバイスで、共通のバッファプーリングとして使用されます。

## フレームプロセッサをマスターする (Advanced topic)

地下ダンジョンへようこそ。FlashCapのフレームプロセッサは、磨けば光る宝石です。しかし、余程のことが無い限り、フレームプロセッサを理解する必要はありません。この解説は、やむを得ずフレームプロセッサを扱う場合の参考にして下さい。また、FlashCapが[デフォルトで内蔵するフレームプロセッサの実装](https://github.com/kekyo/FlashCap/tree/main/FlashCap/FrameProcessors)も参考になるでしょう。
Expand Down

0 comments on commit 678eb26

Please sign in to comment.