1// Copyright (c) 2012 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef UI_SURFACE_TRANSPORT_DIB_H_
6#define UI_SURFACE_TRANSPORT_DIB_H_
7
8#include "base/basictypes.h"
9#include "base/memory/shared_memory.h"
10#include "ui/surface/surface_export.h"
11
12#if defined(OS_WIN)
13#include <windows.h>
14#endif
15
16class SkCanvas;
17
18// -----------------------------------------------------------------------------
19// A TransportDIB is a block of memory that is used to transport pixels
20// between processes: from the renderer process to the browser, and
21// between renderer and plugin processes.
22// -----------------------------------------------------------------------------
23class SURFACE_EXPORT TransportDIB {
24 public:
25  ~TransportDIB();
26
27  // Two typedefs are defined. A Handle is the type which can be sent over
28  // the wire so that the remote side can map the transport DIB. The Id typedef
29  // is sufficient to identify the transport DIB when you know that the remote
30  // side already may have it mapped.
31#if defined(OS_WIN)
32  typedef HANDLE Handle;
33  // On Windows, the Id type includes a sequence number (epoch) to solve an ABA
34  // issue:
35  //   1) Process A creates a transport DIB with HANDLE=1 and sends to B.
36  //   2) Process B maps the transport DIB and caches 1 -> DIB.
37  //   3) Process A closes the transport DIB and creates a new one. The new DIB
38  //      is also assigned HANDLE=1.
39  //   4) Process A sends the Handle to B, but B incorrectly believes that it
40  //      already has it cached.
41  struct HandleAndSequenceNum {
42    HandleAndSequenceNum()
43        : handle(NULL),
44          sequence_num(0) {
45    }
46
47    HandleAndSequenceNum(HANDLE h, uint32 seq_num)
48        : handle(h),
49          sequence_num(seq_num) {
50    }
51
52    bool operator==(const HandleAndSequenceNum& other) const {
53      return other.handle == handle && other.sequence_num == sequence_num;
54    }
55
56    bool operator<(const HandleAndSequenceNum& other) const {
57      // Use the lexicographic order on the tuple <handle, sequence_num>.
58      if (other.handle != handle)
59        return other.handle < handle;
60      return other.sequence_num < sequence_num;
61    }
62
63    HANDLE handle;
64    uint32 sequence_num;
65  };
66  typedef HandleAndSequenceNum Id;
67
68  // Returns a default, invalid handle, that is meant to indicate a missing
69  // Transport DIB.
70  static Handle DefaultHandleValue() { return NULL; }
71#else  // OS_POSIX
72  typedef base::SharedMemoryHandle Handle;
73  // On POSIX, the inode number of the backing file is used as an id.
74#if defined(OS_ANDROID)
75  typedef base::SharedMemoryHandle Id;
76#else
77  typedef base::SharedMemoryId Id;
78#endif
79
80  // Returns a default, invalid handle, that is meant to indicate a missing
81  // Transport DIB.
82  static Handle DefaultHandleValue() { return Handle(); }
83#endif
84
85  // Create a new TransportDIB, returning NULL on failure.
86  //
87  // The size is the minimum size in bytes of the memory backing the transport
88  // DIB (we may actually allocate more than that to give us better reuse when
89  // cached).
90  //
91  // The sequence number is used to uniquely identify the transport DIB. It
92  // should be unique for all transport DIBs ever created in the same
93  // renderer.
94  static TransportDIB* Create(size_t size, uint32 sequence_num);
95
96  // Map the referenced transport DIB.  The caller owns the returned object.
97  // Returns NULL on failure.
98  static TransportDIB* Map(Handle transport_dib);
99
100  // Create a new |TransportDIB| with a handle to the shared memory. This
101  // always returns a valid pointer. The DIB is not mapped.
102  static TransportDIB* CreateWithHandle(Handle handle);
103
104  // Returns true if the handle is valid.
105  static bool is_valid_handle(Handle dib);
106
107  // Returns true if the ID refers to a valid dib.
108  static bool is_valid_id(Id id);
109
110  // Returns a canvas using the memory of this TransportDIB. The returned
111  // pointer will be owned by the caller. The bitmap will be of the given size,
112  // which should fit inside this memory.
113  //
114  // On POSIX, this |TransportDIB| will be mapped if not already. On Windows,
115  // this |TransportDIB| will NOT be mapped and should not be mapped prior,
116  // because PlatformCanvas will map the file internally.
117  //
118  // Will return NULL on allocation failure. This could be because the image
119  // is too large to map into the current process' address space.
120  SkCanvas* GetPlatformCanvas(int w, int h);
121
122  // Map the DIB into the current process if it is not already. This is used to
123  // map a DIB that has already been created. Returns true if the DIB is mapped.
124  bool Map();
125
126  // Return a pointer to the shared memory.
127  void* memory() const;
128
129  // Return the maximum size of the shared memory. This is not the amount of
130  // data which is valid, you have to know that via other means, this is simply
131  // the maximum amount that /could/ be valid.
132  size_t size() const { return size_; }
133
134  // Return the identifier which can be used to refer to this shared memory
135  // on the wire.
136  Id id() const;
137
138  // Return a handle to the underlying shared memory. This can be sent over the
139  // wire to give this transport DIB to another process.
140  Handle handle() const;
141
142 private:
143  TransportDIB();
144
145  // Verifies that the dib can hold a canvas of the requested dimensions.
146  bool VerifyCanvasSize(int w, int h);
147
148  explicit TransportDIB(base::SharedMemoryHandle dib);
149  base::SharedMemory shared_memory_;
150  uint32 sequence_num_;
151  size_t size_;  // length, in bytes
152
153  DISALLOW_COPY_AND_ASSIGN(TransportDIB);
154};
155
156#endif  // UI_SURFACE_TRANSPORT_DIB_H_
157