src/dawn_native/d3d12/TextureCopySplitter.h

// Copyright 2017 The Dawn 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.

#ifndef DAWNNATIVE_D3D12_TEXTURECOPYSPLITTER_H_
#define DAWNNATIVE_D3D12_TEXTURECOPYSPLITTER_H_

#include "dawn_native/dawn_platform.h"

#include <array>

namespace dawn::native {

    struct TexelBlockInfo;

}  // namespace dawn::native

namespace dawn::native::d3d12 {

    struct TextureCopySubresource {
        static constexpr unsigned int kMaxTextureCopyRegions = 4;

        struct CopyInfo {
            uint64_t alignedOffset = 0;
            Origin3D textureOffset;
            Origin3D bufferOffset;
            Extent3D bufferSize;

            Extent3D copySize;
        };

        CopyInfo* AddCopy();

        uint32_t count = 0;
        std::array<CopyInfo, kMaxTextureCopyRegions> copies;
    };

    struct TextureCopySplits {
        static constexpr uint32_t kMaxTextureCopySubresources = 2;

        std::array<TextureCopySubresource, kMaxTextureCopySubresources> copySubresources;
    };

    // This function is shared by 2D and 3D texture copy splitter. But it only knows how to handle
    // 2D non-arrayed textures correctly, and just forwards "copySize.depthOrArrayLayers". See
    // details in Compute{2D|3D}TextureCopySplits about how we generate copy regions for 2D array
    // and 3D textures based on this function.
    // The resulting copies triggered by API like CopyTextureRegion are equivalent to the copy
    // regions defines by the arguments of TextureCopySubresource returned by this function and its
    // counterparts. These arguments should strictly conform to particular invariants. Otherwise,
    // D3D12 driver may report validation errors when we call CopyTextureRegion. Some important
    // invariants are listed below. For more details
    // of these invariants, see src/tests/unittests/d3d12/CopySplitTests.cpp.
    //   - Inside each copy region: 1) its buffer offset plus copy size should be less than its
    //     buffer size, 2) its buffer offset on y-axis should be less than copy format's
    //     blockInfo.height, 3) its buffer offset on z-axis should be 0.
    //   - Each copy region has an offset (aka alignedOffset) aligned to
    //     D3D12_TEXTURE_DATA_PLACEMENT_ALIGNMENT
    //   - The buffer footprint of each copy region should be entirely within the copied buffer,
    //     which means that the last "texel" of the buffer footprint doesn't go past the end of
    //     the buffer even though the last "texel" might not be copied.
    //   - If there are multiple copy regions, each copy region should not overlap with the others.
    //   - Copy region(s) combined should exactly be equivalent to the texture region to be copied.
    //   - Every pixel accessed by every copy region should not be out of the bound of the copied
    //     texture and buffer.
    TextureCopySubresource Compute2DTextureCopySubresource(Origin3D origin,
                                                           Extent3D copySize,
                                                           const TexelBlockInfo& blockInfo,
                                                           uint64_t offset,
                                                           uint32_t bytesPerRow);

    TextureCopySplits Compute2DTextureCopySplits(Origin3D origin,
                                                 Extent3D copySize,
                                                 const TexelBlockInfo& blockInfo,
                                                 uint64_t offset,
                                                 uint32_t bytesPerRow,
                                                 uint32_t rowsPerImage);

    TextureCopySubresource Compute3DTextureCopySplits(Origin3D origin,
                                                      Extent3D copySize,
                                                      const TexelBlockInfo& blockInfo,
                                                      uint64_t offset,
                                                      uint32_t bytesPerRow,
                                                      uint32_t rowsPerImage);
}  // namespace dawn::native::d3d12

#endif  // DAWNNATIVE_D3D12_TEXTURECOPYSPLITTER_H_